Skip to content

Quickstart: Python

The same “list telescopes, create an observation, watch it run” walkthrough as the curl quickstart, in Python with httpx. For the full treatment (catalog and non-sidereal targets, exposure sizing, file download) see Creating observations.

  • Python 3.10+ and httpx (pip install httpx).
  • An access token. See Auth; a scoped token cannot create observations.
import os
import time
import httpx
API = "https://api.skynetgo.org/v1"
TOKEN = os.environ["SKYNET_TOKEN"]
client = httpx.Client(
base_url=API,
headers={"Authorization": f"Bearer {TOKEN}"},
timeout=30.0,
)

An observation is created in one POST from a complete body. The wire format is camelCase JSON with snake_case enum values, so plain dicts map one to one onto the API reference.

def main() -> None:
# 1. Who am I?
me = client.get("/me").raise_for_status().json()
print(f"Hello, {me['username']}")
# 2. A telescope you can submit to; each entry embeds its instruments
scopes = client.get("/me/observing-access/telescopes").raise_for_status().json()
telescope = scopes[0]
imager = next(i for i in telescope["instruments"] if i["instrumentType"] == "optical_imager")
filter_specifier = imager["filterWheels"][0]["positions"][0]["filterIds"][0]
# 3. One of your grants that funds it; its account's owner owns the observation
grants = client.get(
"/me/observing-access/observing-grants", params={"telescopeUid": telescope["uid"]},
).raise_for_status().json()
grant = grants[0]
owner = grant["account"]["owner"]
owner_path = "organizations" if owner["entityType"] == "organization" else "users"
# 4. Create the observation in one call
body = {
"name": "Py 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", # restricts the observation to instrumentUids
"instrumentUids": [imager["uid"]],
}
resp = client.post(f"/{owner_path}/{owner['slug']}/observations", json=body)
if resp.status_code == 422:
raise SystemExit(f"Validation failed: {resp.json()['detail']}")
created = resp.raise_for_status().json()
obs_uid = created["uid"]
print(f"Created observation {obs_uid} (status={created['status']})")
# 5. Watch it run
for _ in range(5):
time.sleep(20)
snap = client.get(f"/observations/{obs_uid}").raise_for_status().json()
print(f" status={snap['status']} progress={snap['progressFraction']}")
if __name__ == "__main__":
main()
  • Field names are camelCase, enum values are snake_case — "requestType": "optical_imaging", not "opticalImaging". See Conventions.
  • Pin the instrument with "instrumentMode": "include" — without it instrumentUids is ignored.
  • Exposure sizing — set one of exposureTimeSec, targetSnr, or targetFullWellFraction per request. If you set more than one, the first in that order wins and the others are ignored.
  • Errors are {"detail": ...}: a 422 lists the fields that failed validation; a 403 means a missing permission, a grant you don’t hold, or a scoped token.

If you want typed request and response models now, generate them from the OpenAPI document the API reference is built from, https://docs.skynetgo.org/openapi.json, with a generator such as datamodel-code-generator:

Terminal window
pip install datamodel-code-generator
datamodel-codegen --url https://docs.skynetgo.org/openapi.json --input-file-type openapi --output skynet_models.py