Skip to content

Quickstart: curl

The “list my telescopes, create an observation, watch it run” sketch. Raw HTTP, no SDK.

An observation is created in one POST from a complete spec — there’s no draft-then-publish handshake. For the full treatment (catalog/non-sidereal targets, exposure sizing, asset download) see Creating observations.

  • An access token. A personal API token created without scopes is the quickest; a scoped token cannot create observations.
  • The base URL for your environment. See Environments.
  • curl and jq for pretty-printing.

For this walkthrough, set:

Terminal window
export SKYNET=https://api.skynetgo.org/v1
export TOKEN="<paste-your-access-token>"
auth=(-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json")

The /me endpoint returns the authenticated user record.

Terminal window
curl -s "${auth[@]}" "$SKYNET/me" | jq '{uid, slug, username}'

If this fails with 401, your token is expired, revoked, or doesn’t match the environment. OAuth access tokens can be refreshed (see Auth → Refreshing).

2. Telescopes you can submit to, and their imagers

Section titled “2. Telescopes you can submit to, and their imagers”

/me/observing-access/telescopes lists the telescopes your observing grants reach. Each entry embeds its instruments, so the same response gives you the optical imager’s uid and the filter specifiers you can request.

Terminal window
curl -s "${auth[@]}" "$SKYNET/me/observing-access/telescopes" | jq '.[] | {uid, slug, name}'
export TELESCOPE_UID=<uid-from-the-list>
curl -s "${auth[@]}" "$SKYNET/me/observing-access/telescopes?telescopeUid=$TELESCOPE_UID" \
| jq '.[].instruments[] | select(.instrumentType=="optical_imager")
| {uid, name, filters: [.filterWheels[].positions[].filterIds[]] | unique}'
export IMAGER_UID=<instrument-uid>

Pick one of your observing grants that funds the telescope. The grant’s observing account decides who owns the observation: you create it under that account’s owner.

Terminal window
curl -s "${auth[@]}" "$SKYNET/me/observing-access/observing-grants?telescopeUid=$TELESCOPE_UID" \
| jq '.[] | {uid, account: .account.name, owner: .account.owner.slug, ownerType: .account.owner.entityType}'
export GRANT_UID=<grant-uid>
export OWNER=users/<owner-slug> # or organizations/<owner-slug> when ownerType is "organization"

One POST carries the whole observation: the target, the imaging configuration (tracking + tiling), the exposure requests, and the funding. You do not send an owner: the owner is the entity in the path, and every grant’s account must belong to it.

Terminal window
curl -s "${auth[@]}" -X POST "$SKYNET/$OWNER/observations" -d '{
"name": "Quickstart M51",
"target": {
"name": "M51",
"position": {
"positionType": "fixed",
"coordinates": { "coordinateType": "equatorial", "raDeg": 202.4696, "decDeg": 47.1952 }
}
},
"opticalImagingConfiguration": {
"trackingMode": "sidereal",
"ditherStrategy": "none",
"temporalOffsetSec": 0.0,
"maxTiles": 1,
"tileOverlap": 0.0
},
"requests": [
{ "requestType": "optical_imaging", "order": 0,
"filterSpecifierIds": ["<filter-specifier>"], "exposureTimeSec": 60.0, "sampleCount": 1 }
],
"observingGrantUids": ["<grant-uid>"],
"instrumentMode": "include",
"instrumentUids": ["<imager-uid>"]
}' | jq '{uid, name, status}'

instrumentMode: "include" is what restricts the observation to the listed imager; without it instrumentUids is ignored and the observation may run on any telescope the grant reaches.

The response includes the new observation’s uid, the identifier every later call uses. It’s created active and visible to the scheduler immediately.

Terminal window
export OBS_UID=<uid-from-response>

If the call returns 4xx, the detail message names the failed check — most commonly no grant (400), a grant whose account belongs to a different owner than the path (400), a grant you don’t hold (403), or a camelCase enum value such as "opticalImaging" (422; enum values are snake_case). See Conventions and the gotchas.

Terminal window
# Poll the observation
curl -s "${auth[@]}" "$SKYNET/observations/$OBS_UID" \
| jq '{status, progressFraction, lastActivityOn}'
# List the tasks the scheduler created from it
curl -s "${auth[@]}" "$SKYNET/observation-tasks?observationUids=$OBS_UID" \
| jq '.items[] | {uid, taskType, status, instrumentUid}'

For a live view, subscribe to the observation_event WebSocket stream — see WebSocket protocol.

If you were just testing, cancel the observation (drops any pending tasks):

Terminal window
curl -s "${auth[@]}" -X PATCH "$SKYNET/observations/$OBS_UID" \
-d '{ "status": "canceled" }' | jq '{uid, status}'