Skip to content

Quickstart — curl

The "list my telescopes, create a draft observation, publish it" sketch. Uses the raw HTTP API; no SDK.

Prereqs

  • An access token. See Auth for how to get one.
  • The base URL for your environment. See Environments.
  • curl and jq for pretty-printing.

For this walkthrough, set:

export SKYNET_API=https://api.skynetgo.org
export TOKEN="<paste-your-access-token>"

1. Who am I?

The /v1/me endpoint returns the authenticated user record.

curl -sH "Authorization: Bearer $TOKEN" \
  "$SKYNET_API/v1/me" | jq .

If this fails with 401, your token is expired or doesn't match the environment. Refresh it (see Auth → Refreshing) or get a new one.

2. List telescopes you can use

curl -sH "Authorization: Bearer $TOKEN" \
  "$SKYNET_API/v1/telescopes?size=10" | jq '.items[] | {id, uid, name, slug}'

The response is a paginated Page<Telescope> envelope (see Conventions → Pagination).

3. List observing accounts you can submit through

curl -sH "Authorization: Bearer $TOKEN" \
  "$SKYNET_API/v1/me/observing-accounts" | jq '.items[] | {id, uid, name, queueAccessGrants}'

Note an id from this list — you'll use it as the funding source for the observation.

4. Create a draft observation

curl -sH "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$SKYNET_API/v1/observations" \
  -d '{
    "name": "Quickstart M51",
    "ownerId": <your-user-or-org-id>,
    "kind": "draft",
    "iterations": 1,
    "priority": 50
  }' | jq .

The response includes the new observation's id and uid. Note them:

export OBS_ID=<id-from-response>

5. Set the target

curl -sH "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X PATCH "$SKYNET_API/v1/observations/$OBS_ID/target" \
  -d '{
    "name": "M51",
    "position": {
      "positionType": "fixed",
      "frame": "equatorial",
      "ra": 202.4696,
      "dec": 47.1952
    }
  }' | jq .

6. Add an imaging request

curl -sH "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$SKYNET_API/v1/observations/$OBS_ID/requests" \
  -d '{
    "requestType": "opticalImaging",
    "iterations": 1,
    "filterTypes": ["V"],
    "exposureMode": "time",
    "exposureTime": 60.0
  }' | jq .

7. Attach the funding grant

curl -sH "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$SKYNET_API/v1/observations/$OBS_ID/observing-grants" \
  -d '{ "observingGrantId": <grant-id-from-step-3> }' | jq .

8. Publish

curl -sH "Authorization: Bearer $TOKEN" \
  -X POST "$SKYNET_API/v1/observations/$OBS_ID/publish" | jq .

If the publish call returns 200, the observation is now an instance and visible to the scheduler. If it returns 4xx, the detail message will tell you which validation check failed (most commonly: missing target, missing requests, or the grant not reaching a telescope that can fulfill the request).

9. Watch it run

# Poll the observation
curl -sH "Authorization: Bearer $TOKEN" \
  "$SKYNET_API/v1/observations/$OBS_ID" | jq '{status, progress, lastActivityOn}'

# List its tasks
curl -sH "Authorization: Bearer $TOKEN" \
  "$SKYNET_API/v1/observations/$OBS_ID/tasks" | jq '.items[] | {id, taskType, status, telescopeId}'

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

Cleanup

If you were just testing, cancel the observation:

curl -sH "Authorization: Bearer $TOKEN" \
  -X POST "$SKYNET_API/v1/observations/$OBS_ID/cancel" | jq .

Next steps