Skip to content

Conventions

Rules that apply across endpoints. Worth skimming before you start building.

Field names are camelCase in JSON responses (observatoryUid). Send camelCase too; request bodies also accept the snake_case field names, and most query parameters are listed in both spellings (telescopeUid and telescope_uid).

Only field names are camelCase. Enum values stay snake_case: "requestType": "optical_imaging", "instrumentType": "optical_imager", "status": "canceled".

Most request bodies silently ignore unknown fields rather than rejecting them, so a misspelled field name drops that setting without an error. Read the created record back when it matters.

All data endpoints sit under /v1/ (the OAuth endpoints and health checks do not):

GET /v1/observations
GET /v1/observations/{uid}
PATCH /v1/observations/{uid}
DELETE /v1/observations/{uid}
POST /v1/users/{slug}/observations

Records you create on behalf of an owner are created under that owner: POST /v1/users/{slug}/… or POST /v1/organizations/{slug}/….

A handful of operations live as action endpoints under the resource — e.g., POST /v1/observations/{uid}/apply-spec — or as colon actions on a collection, e.g. POST /v1/observation-specs:plan. These take no body or take a small action-specific payload.

Every record has a uid, a UUID string that is its public identifier. Resources are addressed by uid everywhere: in paths, in query filters (telescopeUid, ownerUids) and in request bodies (observingGrantUids, instrumentUids, catalogObjectUid). Users, organizations, telescopes, observatories, groups and queues also take their slug where a path says so. A path parameter the API reference names {observation_id} or {telescope_id} takes that resource’s uid (or slug). Integer id fields are internal and are being removed from the wire.

Several core resources are polymorphic — they share a base type and specialize through concrete subclasses. Each carries a discriminator field in JSON that tells you which concrete kind you’re looking at.

Resource family Discriminator (wire) Discriminator (Python)
Device deviceType device_type
Instrument instrumentType instrument_type
ObservationTask taskType task_type
ObservationRequest requestType request_type
Target position positionType position_type
ObservingGrant grantType grant_type
Entity entityType entity_type
OperationalConstraint constraintType constraint_type
Coordinates coordinateType coordinate_type
DataTool dataToolType data_tool_type
FilterSpecifier filterSpecifierType filter_specifier_type
Invitation invitationType invitation_type
DeviceModel deviceType device_type
BrightnessModel modelType model_type
SpectralComponent spectralComponentType spectral_component_type
TemporalComponent temporalComponentType temporal_component_type
CatalogObject catalogObjectType catalog_object_type
ResourceRef resourceType resource_type
Integration integrationType integration_type
Message (WS) kind kind

When unmarshaling polymorphic JSON, switch on the discriminator first, then validate against the concrete subtype. Types generated from the OpenAPI document model these as discriminated unions.

List endpoints return a Page<T> envelope:

{
"items": [ /* T[] */ ],
"total": 1234,
"page": 1,
"size": 50,
"pages": 25
}

Query params:

  • page — 1-based page number. Default 1.
  • size — items per page. Default 50, maximum 100.

Not every list endpoint is paginated: some return a plain JSON array (for example GET /v1/me/observing-access/telescopes), and the graph endpoints under /v1/graphs/ return a richer envelope that includes related resources. The API reference shows each endpoint’s response shape.

Filter params are documented per endpoint in the API reference. Common ones:

  • ownerUids — restrict to records owned by specific entities. Many filters repeat (?ownerUids=…&ownerUids=…), and some have a negated form with a leading - (for example -ownerUids=… or -status=canceled).
  • createdAfter / createdBefore — time-range filters, on the endpoints that offer them.

Sorting is via sortBy=field, with a leading - for descending (sortBy=-created_on); each endpoint lists its sortable fields. Default ordering is endpoint-specific.

REST errors come back as FastAPI’s standard envelope:

{ "detail": "<error message>" }

For validation errors (422 Unprocessable Entity), FastAPI returns its richer per-field envelope:

{
"detail": [
{
"type": "missing",
"loc": ["body", "name"],
"msg": "Field required",
"input": null
}
]
}

The WebSocket protocol has its own richer error envelope — { kind: "error", code, message, details, id } — with code drawn from invalid, forbidden, not_found, conflict, internal. See WebSocket protocol.

The platform doesn’t currently advertise an Idempotency-Key header. POST endpoints that create resources are not idempotent — if you retry blindly, you may end up with duplicates. Strategies:

  • Prefer status transitions via PATCH /v1/observations/{uid} (e.g. { "status": "canceled" }), which are idempotent because the target state is.
  • Capture the response’s uid and check before retrying on network failure. Clients cannot choose the uid of a new record.

Skynet does not currently impose rate limits on the public API’s data endpoints (sign-in and contact forms are rate limited). Practice basic civility — back off on 5xx, batch where possible, avoid tight polling loops in favor of WebSocket subscriptions. If you have a use case that requires high request volume, talk to the team first.

All timestamps are ISO 8601 UTC strings (date-time in the OpenAPI document); parse them into your language’s date type.

Many records carry an isDeleted flag rather than being removed. Whether a list hides flagged records is per endpoint: some lists take an isDeleted filter, and GET /v1/observations does not filter on the flag. Restoring a soft-deleted record is per-resource.