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.
Prereqs
Section titled “Prereqs”- 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.
curlandjqfor pretty-printing.
For this walkthrough, set:
export SKYNET=https://api.skynetgo.org/v1export TOKEN="<paste-your-access-token>"auth=(-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json")1. Who am I?
Section titled “1. Who am I?”The /me endpoint returns the authenticated user record.
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.
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>3. A funding grant
Section titled “3. A funding grant”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.
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"4. Create the observation
Section titled “4. Create the observation”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.
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.
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.
5. Watch it run
Section titled “5. Watch it run”# Poll the observationcurl -s "${auth[@]}" "$SKYNET/observations/$OBS_UID" \ | jq '{status, progressFraction, lastActivityOn}'
# List the tasks the scheduler created from itcurl -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.
Cleanup
Section titled “Cleanup”If you were just testing, cancel the observation (drops any pending tasks):
curl -s "${auth[@]}" -X PATCH "$SKYNET/observations/$OBS_UID" \ -d '{ "status": "canceled" }' | jq '{uid, status}'Next steps
Section titled “Next steps”- Creating observations — catalog and non-sidereal (asteroid/satellite) targets, exposure sizing, and downloading the resulting frames.
- Conventions — pagination, errors, and discriminators.
- Quickstart: Python or Quickstart: TypeScript, including how to generate typed models from the OpenAPI document.
- WebSocket streams for realtime task progress.