Admin API Endpoints: Scheduling, Codes, and Operations

Admin endpoints give operators direct control over the scheduling pipeline, node onboarding, and science configuration. They are protected by a single shared X-Admin-Key header configured in cloud/config.yaml. These endpoints are not intended for node agents or member apps — they are designed for cron jobs, deployment scripts, and manual operator intervention. All of them require the admin key to be present and correct on every call; there is no admin session or token.

Always change server.admin_key in cloud/config.yaml from any default value before deploying to a public network. Admin endpoints have no rate limiting and grant full control over ingestion, scheduling, activation code issuance, and scoring weights. Treat the admin key with the same care as a root database password.

POST /api/v1/admin/ingest

Trigger alert ingestion from all configured broker sources followed immediately by a full rescoring pass. This is normally called on a cron schedule, but can be triggered manually to pick up a breaking transient alert outside the regular cadence.

Request
Response
Example

Auth: X-Admin-KeyNo request body required.

200 OKThe response mirrors the alerts.ingest_all() return value, which includes per-source ingestion counts.

targets_ingested

integer

Total new targets added or updated across all broker sources.

sources

object

Per-source breakdown of ingestion results.

curl -X POST \
     -H "X-Admin-Key: your-admin-key" \
     https://api.thetelescope.net/api/v1/admin/ingest

{
  "targets_ingested": 12,
  "sources": {
    "alerce": {"new": 8, "updated": 3},
    "gaia_alerts": {"new": 1, "updated": 0}
  }
}

POST /api/v1/admin/replan

Trigger a full network rescore followed by fresh observation plan generation for all active nodes. Use after changing scoring weights, adding new targets, or whenever you want plans to reflect the current network state immediately rather than waiting for the scheduled nightly run.

Request
Response
Example

Auth: X-Admin-KeyNo request body required.

curl -X POST \
     -H "X-Admin-Key: your-admin-key" \
     https://api.thetelescope.net/api/v1/admin/replan

{
  "scored_pairs": 1316,
  "plans_generated": 28
}

POST /api/v1/admin/activation-codes

Generate one or more activation codes in bulk. Codes are written to the database immediately and can be distributed to new members or embedded in installer packages. Optionally link generated codes to a specific member account.

Request
Response
Example

Auth: X-Admin-Key

count

integer

Number of codes to generate. Range 1–100. Default 1.

expires_days

integer

Number of days until the codes expire. Default 90.

user_id

string

Optional. Link all generated codes to a specific member account (e.g. "u_4a8b1c2d"). When a code linked to an account is used at registration, the node is automatically added to that member’s node list.

200 OK

codes

array

Array of generated activation code strings in BS-YYYY-XXXXXXXX format.

expires_at

string

ISO 8601 UTC expiry timestamp shared by all generated codes.

curl -X POST \
     -H "X-Admin-Key: your-admin-key" \
     -H "Content-Type: application/json" \
     -d '{"count": 5, "expires_days": 60}' \
     https://api.thetelescope.net/api/v1/admin/activation-codes

{
  "codes": [
    "BS-2026-A1B2C3D4",
    "BS-2026-E5F6G7H8",
    "BS-2026-I9J0K1L2",
    "BS-2026-M3N4O5P6",
    "BS-2026-Q7R8S9T0"
  ],
  "expires_at": "2026-08-14T14:22:00.000000+00:00"
}

POST /api/v1/interrupts

Broadcast a high-priority target interrupt to nodes. The server selects eligible nodes based on their current observability score for the target (requiring a minimum score of 0.35 by default) unless an explicit node list is provided. Nodes poll GET /api/v1/interrupts regularly and will see the interrupt on their next poll cycle.

This endpoint uses X-Admin-Key authentication rather than node or member credentials. It shares the /api/v1/interrupts path with the node’s GET poll endpoint — the HTTP method determines which handler is invoked.

Request
Response
Example

Auth: X-Admin-Key

name

string

required

Target name, e.g. "SN2026abc".

ra_deg

float

required

Right ascension in decimal degrees.

dec_deg

float

required

Declination in decimal degrees.

mag

float

Estimated target magnitude. Used for exposure time planning on the node.

reason

string

Human-readable reason for the interrupt, e.g. "Type Ia SN candidate — early follow-up".

expires_hours

float

Interrupt lifetime in hours. Default 12.0. Nodes that have not acted before expiry will not see the interrupt on subsequent polls.

node_ids

array

Optional list of specific node IDs to target. When omitted and escalate is true, the server automatically selects eligible nodes by observability score.

escalate

boolean

When true (default) and no node_ids are given, automatically select up to 50 nodes with score ≥ min_score for the target.

min_score

float

Minimum composite score threshold for automatic node selection. Default 0.35.

replan

boolean

When true, immediately regenerate observation plans for all notified nodes so the interrupt target appears in tonight’s schedule without waiting for the next plan cycle.

200 OK

boolean

true when the interrupt is recorded.

integer

Database ID of the created interrupt.

node_ids

array

List of node IDs that will see this interrupt. Empty array when the interrupt is broadcast to all nodes.

curl -X POST \
     -H "X-Admin-Key: your-admin-key" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "SN2026abc",
       "ra_deg": 210.5,
       "dec_deg": 54.3,
       "mag": 14.2,
       "reason": "Type Ia SN candidate — early-phase follow-up requested",
       "expires_hours": 24,
       "escalate": true,
       "replan": true
     }' \
     https://api.thetelescope.net/api/v1/interrupts

{
  "ok": true,
  "id": 42,
  "node_ids": [
    "node_a3f9b2c1",
    "node_b7e2d4f0",
    "node_c1a9e3b5"
  ]
}

GET /api/v1/admin/tuning

Retrieve the currently active observability scoring weights and the last 20 entries from the weight audit log. Use this to inspect what the CHORUS scheduler is using and to understand the history of any automated or manual weight adjustments.

Request
Response
Example

Auth: X-Admin-KeyNo request body or query parameters.

200 OK

active_weights

object

The scoring weights currently applied to every (target, node) score computation. Keys correspond to the observability factors.

Show Weight fields

active_weights.light_pollution

float

Weight for sky darkness factor.

active_weights.weather

float

Weight for cloud cover and transparency forecast.

active_weights.moon

float

Weight for lunar interference penalty.

active_weights.airmass

float

Weight for target altitude / airmass.

active_weights.window

float

Weight for the available observing window length.

active_weights.telescope

float

Weight for node hardware capability and reliability score.

history

array

Up to 20 most recent weight change records from the weight_history audit table, newest first.

Show History record fields

integer

History row ID.

changed_at

string

ISO 8601 UTC timestamp of the change.

old_weights

object

Weight values before the change.

new_weights

object

Weight values after the change.

rationale

string

Human or model-generated explanation of why the weights were changed.

model

string

Identifier of the auto-tuner model that made the change, if automated.

applied

boolean

true when the weights in this record were actually pushed to the live config.

curl -H "X-Admin-Key: your-admin-key" \
     https://api.thetelescope.net/api/v1/admin/tuning

{
  "active_weights": {
    "light_pollution": 0.20,
    "weather": 0.25,
    "moon": 0.15,
    "airmass": 0.15,
    "window": 0.15,
    "telescope": 0.10
  },
  "history": [
    {
      "id": 7,
      "changed_at": "2026-06-15T02:30:00.000000+00:00",
      "old_weights": {"light_pollution": 0.18, "weather": 0.27},
      "new_weights": {"light_pollution": 0.20, "weather": 0.25},
      "rationale": "Increased light_pollution weight — darker sites have better AAVSO acceptance rates",
      "model": "chorus_tuner_v2",
      "applied": true
    }
  ]
}

POST /api/v1/admin/tuning/rollback

Restore the previous scoring weights from the audit log. This is the manual safety valve for cases where an automated tuning run produced unexpected results.

Request
Response
Example

Auth: X-Admin-KeyNo request body required. The server automatically uses the most recent old_weights entry from the weight_history table.

200 OK

restored_weights

object

The weight set now active after the rollback. Same structure as active_weights in the tuning GET response.

404 is returned when there is no tuning history to roll back to.

curl -X POST \
     -H "X-Admin-Key: your-admin-key" \
     https://api.thetelescope.net/api/v1/admin/tuning/rollback

{
  "restored_weights": {
    "light_pollution": 0.18,
    "weather": 0.27,
    "moon": 0.15,
    "airmass": 0.15,
    "window": 0.15,
    "telescope": 0.10
  }
}

GET /api/v1/admin/sky-quality

Retrieve measured sky brightness statistics per node for a rolling time window, derived from actual sky_mag values uploaded with photometry measurements. Useful for detecting cloud, smoke, or lunar contamination that the node’s declared light_pollution_mpsas does not capture.

Request
Response
Example

Auth: X-Admin-Key

days

float

Look-back window in days. Default 30.

200 OK

days

float

The look-back window used.

nodes

array

Per-node sky quality summary, sorted by mean_sky_mag descending (darkest first).

Show Node sky quality fields

node_id

string

Node identifier.

city

string

Node city.

declared_mpsas

float

Static light pollution value from node registration.

n_frames

integer

Number of frames with valid sky_mag measurements in the window.

mean_sky_mag

float

Mean measured sky brightness (mpsas).

best_sky_mag

float

Darkest recorded sky brightness.

worst_sky_mag

float

Brightest (most polluted) sky brightness recorded.

last_seen

string

Timestamp of most recent measurement in the window.

curl -H "X-Admin-Key: your-admin-key" \
     "https://api.thetelescope.net/api/v1/admin/sky-quality?days=7"

{
  "days": 7.0,
  "nodes": [
    {
      "node_id": "node_a3f9b2c1",
      "city": "Austin",
      "declared_mpsas": 18.9,
      "n_frames": 412,
      "mean_sky_mag": 18.72,
      "best_sky_mag": 19.31,
      "worst_sky_mag": 17.04,
      "last_seen": "2026-06-15T03:05:00.000000+00:00"
    }
  ]
}

GET /api/v1/admin/patrol

Retrieve recent photometric patrol detections — potential transient events flagged by the data pipeline during flux-differential analysis of photometry submissions.

Request
Response
Example

Auth: X-Admin-KeyNo request body or query parameters.

200 OK — Returns recent patrol detection records from the patrol_detections table.

curl -H "X-Admin-Key: your-admin-key" \
     https://api.thetelescope.net/api/v1/admin/patrol

GET /api/v1/admin/incidents

List structured reliability incidents reported by nodes and the cloud pipeline. Incidents are automatically created for hardware faults, photometry quality failures, emergency parks, and cross-validation outlier clusters.

Request
Response
Example

Auth: X-Admin-Key

status

string

Filter by incident status. Options: "active" (open + investigating, default), "resolved", "all".

200 OK

incidents

array

Array of incident records from the incidents table.

count

integer

Number of records returned.

curl -H "X-Admin-Key: your-admin-key" \
     "https://api.thetelescope.net/api/v1/admin/incidents?status=active"

{
  "count": 2,
  "incidents": [
    {
      "id": 101,
      "node_id": "node_b7e2d4f0",
      "status": "open",
      "incident_type": "outlier_cluster",
      "severity": "warning",
      "opened_at": "2026-06-15T01:00:00.000000+00:00"
    }
  ]
}

PATCH /api/v1/admin/incidents/

Update a structured incident’s status, root cause, resolution note, or resolver. Setting status to "resolved" automatically stamps resolved_at if not already set.

Request
Response
Example

Auth: X-Admin-Key

incident_id

integer

required

Incident ID from the incidents list.

status

string

New status: "open", "investigating", or "resolved".

root_cause

string

Root cause classification: "weather", "hardware", "software", "optics", or "unknown".

resolution_note

string

Free-text description of what was found and how it was fixed.

resolver

string

Name or email of the person resolving the incident.

curl -X PATCH \
     -H "X-Admin-Key: your-admin-key" \
     -H "Content-Type: application/json" \
     -d '{
       "status": "resolved",
       "root_cause": "weather",
       "resolution_note": "Outlier cluster caused by thin cirrus, cleared by 03:00 UTC",
       "resolver": "ops@thetelescope.net"
     }' \
     https://api.thetelescope.net/api/v1/admin/incidents/101

{
  "incident": {
    "id": 101,
    "status": "resolved",
    "root_cause": "weather",
    "resolution_note": "Outlier cluster caused by thin cirrus, cleared by 03:00 UTC",
    "resolver": "ops@thetelescope.net",
    "resolved_at": "2026-06-15T09:30:00.000000+00:00"
  }
}

GET /api/v1/admin/subscribers

List all waitlist subscribers, including their email, referral source, equipment, subscription timestamp, assigned activation code, and current status.

Request
Response
Example

Auth: X-Admin-KeyNo request body or query parameters.

200 OK — Returns all subscriber records from the subscribers table.

curl -H "X-Admin-Key: your-admin-key" \
     https://api.thetelescope.net/api/v1/admin/subscribers

PATCH /api/v1/admin/subscribers//status

Update the status of a waitlist subscriber, e.g. to mark them as "invited" or "active" after sending their welcome email.

Request
Response
Example

Auth: X-Admin-Key

sub_id

integer

required

Subscriber ID from the subscribers list.

status

string

required

New subscriber status string (e.g. "pending", "invited", "active").

curl -X PATCH \
     -H "X-Admin-Key: your-admin-key" \
     -H "Content-Type: application/json" \
     -d '{"status": "invited"}' \
     https://api.thetelescope.net/api/v1/admin/subscribers/42/status

GET /api/v1/admin/science-program-suggestions

List all member-submitted science program ideas, ordered by submission date descending.

Request
Response
Example

Auth: X-Admin-KeyNo request body or query parameters.

200 OK

suggestions

array

Array of suggestion records including id, user_id, email, title, description, target_examples, notes, status, and created_at.

total

integer

Total number of suggestions.

curl -H "X-Admin-Key: your-admin-key" \
     https://api.thetelescope.net/api/v1/admin/science-program-suggestions

{
  "suggestions": [
    {
      "id": 12,
      "user_id": "u_4a8b1c2d",
      "email": "jane@example.com",
      "title": "Symbiotic Star Monitoring Campaign",
      "status": "pending",
      "created_at": "2026-06-15T14:00:00.000000+00:00"
    }
  ],
  "total": 1
}

PATCH /api/v1/admin/science-program-suggestions//status

Update the review status of a member-submitted science program suggestion.

Request
Response
Example

Auth: X-Admin-Key

suggestion_id

integer

required

Suggestion ID from the suggestions list.

status

string

required

New status. Must be one of: "pending", "reviewed", "accepted", or "declined".

200 OK

boolean

true when updated.

400 is returned when the status value is not one of the permitted values.

curl -X PATCH \
     -H "X-Admin-Key: your-admin-key" \
     -H "Content-Type: application/json" \
     -d '{"status": "accepted"}' \
     https://api.thetelescope.net/api/v1/admin/science-program-suggestions/12/status

{"ok": true}

PATCH /api/v1/site/config

Update public site configuration. Currently supports updating the displayed member count on the tour page.

Request
Response
Example

Auth: X-Admin-Key

member_count

integer

New value for the publicly displayed member count.

200 OK — Returns the full updated site config object (same shape as GET /api/v1/site/config).

member_count

integer

The updated member count.

curl -X PATCH \
     -H "X-Admin-Key: your-admin-key" \
     -H "Content-Type: application/json" \
     -d '{"member_count": 50}' \
     https://api.thetelescope.net/api/v1/site/config

{"member_count": 50}

Overview

Endpoints

Admin API Endpoints: Scheduling, Codes, and Operations

POST /api/v1/admin/ingest

POST /api/v1/admin/replan

POST /api/v1/admin/activation-codes

POST /api/v1/interrupts

GET /api/v1/admin/tuning

POST /api/v1/admin/tuning/rollback

GET /api/v1/admin/sky-quality

GET /api/v1/admin/patrol

GET /api/v1/admin/incidents

PATCH /api/v1/admin/incidents/

GET /api/v1/admin/subscribers

PATCH /api/v1/admin/subscribers//status

GET /api/v1/admin/science-program-suggestions

PATCH /api/v1/admin/science-program-suggestions//status

PATCH /api/v1/site/config

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​POST /api/v1/admin/ingest

​POST /api/v1/admin/replan

​POST /api/v1/admin/activation-codes

​POST /api/v1/interrupts

​GET /api/v1/admin/tuning

​POST /api/v1/admin/tuning/rollback

​GET /api/v1/admin/sky-quality

​GET /api/v1/admin/patrol

​GET /api/v1/admin/incidents

​PATCH /api/v1/admin/incidents/

​GET /api/v1/admin/subscribers

​PATCH /api/v1/admin/subscribers//status

​GET /api/v1/admin/science-program-suggestions

​PATCH /api/v1/admin/science-program-suggestions//status

​PATCH /api/v1/site/config

Build docs developers (and LLMs) love

POST /api/v1/admin/ingest

POST /api/v1/admin/replan

POST /api/v1/admin/activation-codes

POST /api/v1/interrupts

GET /api/v1/admin/tuning

POST /api/v1/admin/tuning/rollback

GET /api/v1/admin/sky-quality

GET /api/v1/admin/patrol

GET /api/v1/admin/incidents

PATCH /api/v1/admin/incidents/

GET /api/v1/admin/subscribers

PATCH /api/v1/admin/subscribers//status

GET /api/v1/admin/science-program-suggestions

PATCH /api/v1/admin/science-program-suggestions//status

PATCH /api/v1/site/config