Node API Endpoints: Registration, Heartbeat, and Data Upload

Node endpoints form the data backbone of The Telescope Net. Every Seestar telescope running the node agent communicates exclusively through these routes — from the one-time registration that provisions its identity, through nightly heartbeats and plan downloads, to the photometry measurements and FITS images that flow back to the cloud after each observation. All endpoints except POST /api/v1/nodes/register, GET /api/v1/nodes/pair/{token}, and GET /api/v1/aavso-files require the X-Node-Id and X-Api-Key headers issued at registration.

POST /api/v1/nodes/pair

Submit an activation code to a waiting node via a shared pairing token. The member app calls this endpoint after the user creates an activation code; the unregistered node polls GET /api/v1/nodes/pair/{token} to receive it.

Request
Response
Example

Auth: Authorization: Bearer <token> (member)

pairing_token

string

required

The pairing token displayed by the unregistered node agent (format WORD-NNNN, e.g. NOVA-4821).

activation_code

string

required

The activation code in BS-YYYY-XXXXXXXX format to deliver to the node.

200 OK

boolean

true when the code is stored for the node to collect.

400 is returned when either field is missing.404 is returned when the activation code does not exist.409 is returned when the activation code has already been used.

curl -X POST https://api.thetelescope.net/api/v1/nodes/pair \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{"pairing_token": "NOVA-4821", "activation_code": "BS-2026-ABCD1234"}'

{"ok": true}

GET /api/v1/nodes/pair/

Poll for an activation code that the member app has pushed to this pairing token. The node agent calls this endpoint on a 30-second loop before it is registered. When a code is available it is returned and the entry is consumed — subsequent calls return {"code": null}.

Request
Response
Example

Auth: None

token

string

required

The pairing token shown by the node agent (e.g. NOVA-4821). Case-insensitive.

200 OK

code

string

The activation code in BS-YYYY-XXXXXXXX format, or null when no code has been pushed yet.

curl https://api.thetelescope.net/api/v1/nodes/pair/NOVA-4821

{"code": "BS-2026-ABCD1234"}

POST /api/v1/nodes/register

Register a new node and obtain its permanent API credentials. This endpoint is called once during first-boot setup and requires an activation code rather than existing node credentials.

After registration succeeds, the node agent saves the returned node_id and api_key to data/cloud_state.json. All subsequent calls use those credentials. You should not call this endpoint again unless the state file is lost — if the same activation code is re-presented within 15 minutes of first use, the server will return the same credentials idempotently.

Request
Response
Example

Auth: None — activation code in request body

activation_code

string

required

Single-use code in BS-YYYY-XXXXXXXX format obtained from a member’s account or an admin bulk-generation call.

latitude

float

required

Observatory latitude in decimal degrees. Must not be exactly 0.0 — the server rejects the null island.

longitude

float

required

Observatory longitude in decimal degrees.

telescope_model

string

Model name, e.g. "ZWO Seestar S50". Used to seed hardware spec defaults when not overridden by the activation code.

aperture_mm

float

Telescope aperture in millimetres (default 50.0 for Seestar S50).

focal_length_mm

float

Focal length in millimetres (default 250.0).

filter_set

string

JSON array string of photometric filter names, e.g. '["CV"]' or '["B","V","R","I"]'.

tier

integer

Capability tier: 1 = Seestar (default), 2 = filtered, 3 = spectroscopy.

owner_name

string

Human-readable name for the observatory or owner. Falls back to the activation code’s stored value if omitted.

portable

boolean

true if the telescope moves between sites. Portable nodes start in sleeping status and activate when a session begins.

Show Additional hardware fields

elevation

float

Elevation above sea level in metres.

city

string

City or locality name.

country

string

Country name or ISO code.

utc_offset_hours

float

Local UTC offset, e.g. -5.0.

mount_type

string

"alt_az" (default) or "equatorial".

max_exposure_s

float

Maximum sub-frame exposure in seconds (default 30.0 for alt-az field rotation limit).

mag_bright_limit

float

Brightest target magnitude this node can safely image (default 6.0).

mag_faint_limit

float

Faintest reachable magnitude (default 15.5).

has_dew_heater

boolean

Prevents lens fogging in humid conditions.

has_enclosure

boolean

Dome or minidome — can operate in light rain.

has_ups

boolean

Survives brief power cuts.

200 OK

node_id

string

Unique node identifier, e.g. "node_a3f9b2c1". Persist this for all subsequent API calls.

api_key

string

Secret API key. Treat as a password — never log or expose in URLs.

Error codes

Status	Meaning
`404`	Activation code not found
`409`	Activation code already used (outside retry window)
`410`	Activation code expired
`400`	Missing or invalid location coordinates

curl -X POST https://api.thetelescope.net/api/v1/nodes/register \
     -H "Content-Type: application/json" \
     -d '{
       "activation_code": "BS-2026-ABCD1234",
       "latitude": 30.2672,
       "longitude": -97.7431,
       "telescope_model": "ZWO Seestar S50",
       "aperture_mm": 50,
       "filter_set": "[\"CV\"]",
       "tier": 1
     }'

{
  "node_id": "node_a3f9b2c1",
  "api_key": "aBcDeFgHiJkLmNoPqRsTuVwXyZ012345"
}

POST /api/v1/nodes/heartbeat

Send a 60-second liveness signal to the cloud. The node agent calls this endpoint on a fixed interval throughout the night. The server updates last_heartbeat on the node record, which drives the online/offline indicator visible to members. Nodes that have not heartbeated within 15 minutes are considered offline.

Request
Response
Example

Auth: X-Node-Id + X-Api-KeyThe request body is optional. When included, conditions are stored against the node record and made available to the scheduler for weather-aware planning.

conditions

object

Current local observing conditions snapshot.

Show Condition fields

conditions.clear_fraction

float

Sky clarity fraction, 0.0 (overcast) to 1.0 (fully clear).

conditions.humidity

float

Relative humidity percentage, 0–100.

conditions.temperature_c

float

Ambient temperature in Celsius.

conditions.utc_offset_hours

float

Current UTC offset. When present, updates the node’s stored offset so plans use the correct local-time window.

200 OK

boolean

Always true when the heartbeat is accepted.

server_time

string

ISO 8601 UTC timestamp of when the heartbeat was recorded. The node agent can use this to detect significant clock drift.

curl -X POST https://api.thetelescope.net/api/v1/nodes/heartbeat \
     -H "X-Node-Id: node_a3f9b2c1" \
     -H "X-Api-Key: <api_key>" \
     -H "Content-Type: application/json" \
     -d '{"conditions": {"clear_fraction": 0.95, "humidity": 42, "utc_offset_hours": -5.0}}'

{
  "ok": true,
  "server_time": "2026-06-15T03:00:00.000000+00:00"
}

GET /api/v1/nodes/me

Retrieve the full registry entry for the authenticated node, including all hardware fields and performance metrics computed by the nightly maintenance loop.

Request
Response
Example

Auth: X-Node-Id + X-Api-KeyNo request body or query parameters.

200 OK — Returns the node’s public view (all columns except api_key and owner_email).

node_id

string

Unique node identifier.

latitude

float

Observatory latitude.

longitude

float

Observatory longitude.

tier

integer

Capability tier (1–3).

aperture_mm

float

Telescope aperture.

filter_set

string

JSON array of photometric filter names.

status

string

Node status: active, sleeping, vacation, or disabled.

online

boolean

Derived field: true when last_heartbeat is within 15 minutes and status is active.

reliability_score

float

Composite 0–1 scheduler multiplier recomputed nightly from AAVSO acceptance rate, outlier rate, observation frequency, and photometric precision.

total_observations

integer

Lifetime measurement count.

aavso_accepted

integer

Measurements submitted to AAVSO.

last_conditions

object

Most recently uploaded conditions snapshot.

curl -H "X-Node-Id: node_a3f9b2c1" \
     -H "X-Api-Key: <api_key>" \
     https://api.thetelescope.net/api/v1/nodes/me

{
  "node_id": "node_a3f9b2c1",
  "latitude": 30.2672,
  "longitude": -97.7431,
  "city": "Austin",
  "country": "US",
  "tier": 1,
  "aperture_mm": 50.0,
  "filter_set": "[\"CV\"]",
  "status": "active",
  "online": true,
  "reliability_score": 0.82,
  "scheduler_trust_score": 0.79,
  "total_observations": 1423,
  "aavso_accepted": 1287,
  "last_conditions": {"clear_fraction": 0.95, "humidity": 42}
}

GET /api/v1/plan

Download the current nightly observation plan for this node. The plan is generated by the CHORUS scheduler each evening based on target scores, node location, weather forecast, and network-wide coverage balance. If no current plan exists the server generates one on demand.

Request
Response
Example

Auth: X-Node-Id + X-Api-KeyNo request body or query parameters.

200 OK

plan

object

The full ObservationPlan object, or null if no observable night window exists.

Show Plan fields

plan.plan_id

string

Unique plan identifier.

plan.node_id

string

The node this plan was generated for.

plan.night

string

Local evening date in YYYY-MM-DD format.

plan.generated_at

string

ISO 8601 UTC timestamp of plan generation.

plan.items

array

Ordered list of PlanItem objects.

Show PlanItem fields

target

string

Target name, e.g. "SS_Cyg".

float

Right ascension in decimal hours.

dec

float

Declination in decimal degrees.

expDur

float

Sub-frame exposure duration in seconds.

expCount

integer

Number of sub-frames to stack.

binning

integer

Camera binning factor.

startTime

string

Scheduled start in node-local HH:MM format.

filter

string

Photometric filter to use.

score

float

Composite scheduling score (0–1) for this target on this node.

observation_mode

string

"single_epoch" or "time_series".

duration_minutes

float

Total time on target for time-series mode.

curl -H "X-Node-Id: node_a3f9b2c1" \
     -H "X-Api-Key: <api_key>" \
     https://api.thetelescope.net/api/v1/plan

{
  "plan": {
    "plan_id": "plan_20260615_node_a3f9b2c1",
    "node_id": "node_a3f9b2c1",
    "night": "2026-06-15",
    "generated_at": "2026-06-15T01:00:00.000000+00:00",
    "items": [
      {
        "target": "SS_Cyg",
        "ra": 21.7,
        "dec": 43.59,
        "expDur": 30.0,
        "expCount": 40,
        "binning": 1,
        "startTime": "22:15",
        "filter": "CV",
        "score": 0.87,
        "observation_mode": "single_epoch",
        "duration_minutes": 20.0
      }
    ]
  }
}

POST /api/v1/measurements

Upload a single photometry measurement. The cloud validates the measurement against physical bounds, stores it, and runs cross-validation against co-temporal observations from other nodes. Measurements that pass cross-validation and meet quality thresholds are queued for AAVSO submission.

Request
Response
Example

Auth: X-Node-Id + X-Api-Key

measurement

object

required

The photometry result from photometry.run_pipeline().

Show Measurement fields

measurement.target_name

string

required

Target name, e.g. "SS_Cyg".

measurement.bjd

float

required

Barycentric Julian Date. Must be between 2,400,000 and 2,500,000.

measurement.magnitude

float

required

Measured magnitude. Must be between −5 and 30.

measurement.uncertainty

float

required

1-σ photometric uncertainty in magnitudes. Must be between 0 and 5.

measurement.filter

string

required

Photometric filter used, e.g. "CV", "V", "B".

measurement.quality_flag

string

required

"good", "acceptable", or "poor". Only good and acceptable are eligible for AAVSO submission.

measurement.airmass

float

Observing airmass at time of exposure.

measurement.fwhm

float

Full-width half-maximum of the stellar PSF in pixels.

measurement.snr

float

Signal-to-noise ratio of the target aperture.

measurement.comparison_stars

integer

Number of comparison stars used in ensemble photometry.

measurement.zero_point

float

Photometric zero-point for this frame.

measurement.zp_scatter

float

RMS scatter of comparison star zero-points.

measurement.fits_file

string

Filename of the source FITS frame (for traceability).

measurement.sky_mag

float

Measured sky background brightness in mag/arcsec².

conditions

object

Observing conditions at the time of this measurement. Stored alongside the measurement for quality analysis.

200 OK

boolean

true when the measurement was accepted and stored.

integer

Database row ID of the stored measurement. null for idempotent duplicate submissions.

duplicate

boolean

Present and true when the same node/target/BJD/filter combination was already stored.

400 is returned when the measurement fails validation bounds.

curl -X POST https://api.thetelescope.net/api/v1/measurements \
     -H "X-Node-Id: node_a3f9b2c1" \
     -H "X-Api-Key: <api_key>" \
     -H "Content-Type: application/json" \
     -d '{
       "measurement": {
         "target_name": "SS_Cyg",
         "bjd": 2460476.5123,
         "magnitude": 11.42,
         "uncertainty": 0.018,
         "filter": "CV",
         "quality_flag": "good",
         "airmass": 1.23,
         "fwhm": 2.8,
         "snr": 142.5,
         "comparison_stars": 7
       },
       "conditions": {"clear_fraction": 0.95, "humidity": 38}
     }'

{
  "ok": true,
  "id": 84721
}

POST /api/v1/images

Upload a raw FITS frame. The server stores the file under cloud_data/images/ and returns a storage path. File size is capped at the server’s 128 MB content limit.

Request
Response
Example

Auth: X-Node-Id + X-Api-KeyContent-Type: multipart/form-data

file

required

The FITS file to upload. Attach as a multipart form field named file.

200 OK

boolean

true when the file was stored.

stored

string

Relative path under the image storage root where the file was saved.

400 is returned when no file is attached or storage fails.

curl -X POST https://api.thetelescope.net/api/v1/images \
     -H "X-Node-Id: node_a3f9b2c1" \
     -H "X-Api-Key: <api_key>" \
     -F "file=@SS_Cyg_2026-06-15_001.fits"

{
  "ok": true,
  "stored": "node_a3f9b2c1/2026-06-15/SS_Cyg_2026-06-15_001.fits"
}

POST /api/v1/aavso-files

Upload an AAVSO Extended Format text file (.txt) generated by the node’s photometry pipeline. Files are stored under cloud_data/aavso_files/<date>/ and can be downloaded by an operator to email to observations@aavso.org. File size is capped at 512 KB.

Request
Response
Example

Auth: X-Node-Id + X-Api-KeyContent-Type: multipart/form-data

file

required

The AAVSO .txt file. Filenames are sanitised server-side; a .txt extension is appended automatically if missing.

200 OK

boolean

true when the file was stored.

path

string

Relative path under the AAVSO file storage root.

curl -X POST https://api.thetelescope.net/api/v1/aavso-files \
     -H "X-Node-Id: node_a3f9b2c1" \
     -H "X-Api-Key: <api_key>" \
     -F "file=@SS_Cyg_20260615.txt"

{
  "ok": true,
  "path": "2026-06-15/SS_Cyg_20260615.txt"
}

GET /api/v1/aavso-files

List all uploaded AAVSO Extended Format text files, newest first. No authentication required — the list is public so operators can locate files to email to AAVSO.

Request
Response
Example

Auth: NoneNo query parameters.

200 OK

files

array

Array of file metadata objects, sorted newest-first.

Show File fields

path

string

Relative path under the AAVSO file root, e.g. "2026-06-15/SS_Cyg_20260615.txt".

size

integer

File size in bytes.

modified

string

ISO 8601 UTC timestamp of last modification.

download

string

URL path for downloading this file, e.g. "/api/v1/aavso-files/download/2026-06-15/SS_Cyg_20260615.txt".

count

integer

Total number of files.

curl https://api.thetelescope.net/api/v1/aavso-files

{
  "files": [
    {
      "path": "2026-06-15/SS_Cyg_20260615.txt",
      "size": 2048,
      "modified": "2026-06-15T11:00:00.000000+00:00",
      "download": "/api/v1/aavso-files/download/2026-06-15/SS_Cyg_20260615.txt"
    }
  ],
  "count": 1
}

GET /api/v1/aavso-files/download/

Download a specific AAVSO text file by its relative path. Returns the file as an attachment. Path traversal is blocked server-side.

Request
Response
Example

Auth: None

path

string

required

Relative path from the AAVSO file listing, e.g. 2026-06-15/SS_Cyg_20260615.txt.

200 OK — Binary file download with Content-Disposition: attachment.400 is returned for path traversal attempts.404 is returned when the file does not exist.

curl -O https://api.thetelescope.net/api/v1/aavso-files/download/2026-06-15/SS_Cyg_20260615.txt

POST /api/v1/incidents

Report a structured reliability incident from the node agent. The cloud stores it in the reliability_incidents table, making hardware faults, slew failures, emergency parks, and similar events visible to remote operators the moment they occur.

Request
Response
Example

Auth: X-Node-Id + X-Api-Key

incident_type

string

required

Machine-readable event name, e.g. "slew_failure", "emergency_park", "disk_full".

severity

string

One of "info", "warning", "error", or "critical". Defaults to "info".

target_name

string

Target being observed when the incident occurred, if applicable.

detail

object

Structured detail dict (max 4 KB after serialisation). Any extra fields beyond incident_type should go here.

200 OK

boolean

true when the incident is recorded.

400 is returned when incident_type is missing.

curl -X POST https://api.thetelescope.net/api/v1/incidents \
     -H "X-Node-Id: node_a3f9b2c1" \
     -H "X-Api-Key: <api_key>" \
     -H "Content-Type: application/json" \
     -d '{
       "incident_type": "slew_failure",
       "severity": "error",
       "target_name": "SS_Cyg",
       "detail": {"error_code": "MOUNT_STALL", "az_deg": 210.5}
     }'

{"ok": true}

GET /api/v1/interrupts

Poll for unexpired high-priority target interrupts broadcast by the cloud. The node agent calls this endpoint regularly alongside its heartbeat to detect urgent retargeting requests — for example, a supernova alert or gamma-ray burst follow-up that takes precedence over the nightly plan.

Request
Response
Example

Auth: X-Node-Id + X-Api-KeyNo request body or query parameters.

200 OK

interrupts

array

List of unexpired interrupts applicable to this node. Interrupts targeted at a specific set of node IDs are filtered — only interrupts relevant to the calling node are returned.

Show Interrupt fields

integer

Unique interrupt ID. Use this with POST /api/v1/interrupts/{id}/ack to acknowledge.

name

string

Target name.

ra_deg

float

Target right ascension in decimal degrees.

dec_deg

float

Target declination in decimal degrees.

float

Right ascension in decimal hours (pre-converted for node schedule compatibility).

dec

float

Declination in decimal degrees.

mag

float

Estimated target magnitude.

reason

string

Human-readable reason for the interrupt, e.g. "SN candidate" or "GRB afterglow follow-up".

created_at

string

ISO 8601 UTC timestamp of interrupt creation.

expires_at

string

ISO 8601 UTC timestamp after which the interrupt is no longer active.

acked

boolean

true if this node has already acknowledged the interrupt.

curl -H "X-Node-Id: node_a3f9b2c1" \
     -H "X-Api-Key: <api_key>" \
     https://api.thetelescope.net/api/v1/interrupts

{
  "interrupts": [
    {
      "id": 42,
      "name": "SN2026abc",
      "ra_deg": 210.5,
      "dec_deg": 54.3,
      "ra": 14.033,
      "dec": 54.3,
      "mag": 14.2,
      "reason": "Type Ia SN candidate — early-phase follow-up requested",
      "created_at": "2026-06-15T02:10:00.000000+00:00",
      "expires_at": "2026-06-16T02:10:00.000000+00:00",
      "acked": false
    }
  ]
}

POST /api/v1/interrupts//ack

Acknowledge receipt of an interrupt. Once acknowledged, the acked field is set to true for this node on subsequent polls. Acknowledgment does not remove the interrupt — it remains visible to all other eligible nodes until it expires.

Request
Response
Example

Auth: X-Node-Id + X-Api-Key

integer

required

The interrupt ID from the GET /api/v1/interrupts response.

200 OK

boolean

true when acknowledgment is recorded.

404 is returned when the interrupt ID is not found.

curl -X POST \
     -H "X-Node-Id: node_a3f9b2c1" \
     -H "X-Api-Key: <api_key>" \
     https://api.thetelescope.net/api/v1/interrupts/42/ack

{"ok": true}

GET /api/v1/nodes/config-patches

Retrieve pending config.yaml patches queued by the help assistant for this node. The node agent polls this endpoint alongside plan and interrupt polling to pick up any configuration changes pushed remotely.

Request
Response
Example

Auth: X-Node-Id + X-Api-KeyNo request body or query parameters.

200 OK

patches

array

List of pending patch objects. Each patch has an id and a patch dict of config keys to update.

curl -H "X-Node-Id: node_a3f9b2c1" \
     -H "X-Api-Key: <api_key>" \
     https://api.thetelescope.net/api/v1/nodes/config-patches

{
  "patches": [
    {
      "id": 7,
      "patch": {"photometry": {"min_snr": 12.0}}
    }
  ]
}

POST /api/v1/nodes/config-patches//ack

Acknowledge a config patch after applying it. Reports success or failure back to the cloud so the help assistant knows whether the change took effect.

Request
Response
Example

Auth: X-Node-Id + X-Api-Key

patch_id

integer

required

The patch ID from the config-patches list.

boolean

true when the patch was applied successfully. Defaults to true if omitted.

error

string

Error message (up to 500 characters) when ok is false.

200 OK

boolean

true when the acknowledgment is recorded.

curl -X POST https://api.thetelescope.net/api/v1/nodes/config-patches/7/ack \
     -H "X-Node-Id: node_a3f9b2c1" \
     -H "X-Api-Key: <api_key>" \
     -H "Content-Type: application/json" \
     -d '{"ok": true}'

{"ok": true}

Overview

Endpoints

Node API Endpoints: Registration, Heartbeat, and Data Upload

POST /api/v1/nodes/pair

GET /api/v1/nodes/pair/

POST /api/v1/nodes/register

POST /api/v1/nodes/heartbeat

GET /api/v1/nodes/me

GET /api/v1/plan

POST /api/v1/measurements

POST /api/v1/images

POST /api/v1/aavso-files

GET /api/v1/aavso-files

GET /api/v1/aavso-files/download/

POST /api/v1/incidents

GET /api/v1/interrupts

POST /api/v1/interrupts//ack

GET /api/v1/nodes/config-patches

POST /api/v1/nodes/config-patches//ack

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​POST /api/v1/nodes/pair

​GET /api/v1/nodes/pair/

​POST /api/v1/nodes/register

​POST /api/v1/nodes/heartbeat

​GET /api/v1/nodes/me

​GET /api/v1/plan

​POST /api/v1/measurements

​POST /api/v1/images

​POST /api/v1/aavso-files

​GET /api/v1/aavso-files

​GET /api/v1/aavso-files/download/

​POST /api/v1/incidents

​GET /api/v1/interrupts

​POST /api/v1/interrupts//ack

​GET /api/v1/nodes/config-patches

​POST /api/v1/nodes/config-patches//ack

Build docs developers (and LLMs) love

POST /api/v1/nodes/pair

GET /api/v1/nodes/pair/

POST /api/v1/nodes/register

POST /api/v1/nodes/heartbeat

GET /api/v1/nodes/me

GET /api/v1/plan

POST /api/v1/measurements

POST /api/v1/images

POST /api/v1/aavso-files

GET /api/v1/aavso-files

GET /api/v1/aavso-files/download/

POST /api/v1/incidents

GET /api/v1/interrupts

POST /api/v1/interrupts//ack

GET /api/v1/nodes/config-patches

POST /api/v1/nodes/config-patches//ack