Conventions
Rules that apply across endpoints. Worth skimming before you start building.
Wire format — camelCase JSON
Section titled “Wire format — camelCase JSON”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.
Resource URIs
Section titled “Resource URIs”All data endpoints sit under /v1/ (the OAuth endpoints and health checks do not):
GET /v1/observationsGET /v1/observations/{uid}PATCH /v1/observations/{uid}DELETE /v1/observations/{uid}POST /v1/users/{slug}/observationsRecords 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.
Polymorphic resources and discriminators
Section titled “Polymorphic resources and discriminators”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.
Pagination
Section titled “Pagination”List endpoints return a Page<T> envelope:
{ "items": [ /* T[] */ ], "total": 1234, "page": 1, "size": 50, "pages": 25}Query params:
page— 1-based page number. Default1.size— items per page. Default50, maximum100.
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.
Filtering and sorting
Section titled “Filtering and sorting”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.
Error model
Section titled “Error model”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.
Idempotency
Section titled “Idempotency”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
uidand check before retrying on network failure. Clients cannot choose theuidof a new record.
Rate limits
Section titled “Rate limits”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.
Timestamps
Section titled “Timestamps”All timestamps are ISO 8601 UTC strings (date-time in the OpenAPI document); parse them into your language’s date type.
Soft delete
Section titled “Soft delete”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.