Creating observations
This guide shows how to submit observations programmatically — resolve a target, build the request, pin it to a telescope, and retrieve the resulting frames — for both sidereal targets (deep-sky objects) and non-sidereal targets (asteroids, comets, satellites) under rate tracking.
It assumes you’ve read Authentication and Conventions. The web observation editor submits the same content (as a spec envelope through POST /v1/observation-specs:publish) — this guide is its programmatic equivalent.
The model
Section titled “The model”A single POST creates the whole observation. One ObservationCreate body bundles four things:
graph LR O["Observation"] --> T["Target<br/>what to point at"] O --> C["OpticalImagingConfiguration<br/>tracking + brightness models"] O --> R["requests<br/>filter + exposure per pass"] O --> G["Funding<br/>observingGrantUids"] O --> I["Instruments<br/>instrumentMode + instrumentUids"]
- Target — a name plus a
position(a catalog object, fixed coordinates, or a full orbit). - Configuration —
trackingMode(siderealortarget), dithering, and the brightness/saturation models that size exposures. - Requests — one or more exposure passes (filter + exposure spec + repeat count).
- Funding — the observing grant(s) that pay for it, which decide the telescopes it can run on, and optionally the instrument(s) to restrict it to (
instrumentMode: "include"+instrumentUids).
Any HTTP client works: the wire format is plain JSON. The examples use httpx in Python, built-in fetch in TypeScript (Node 20+), and curl with jq.
import os, httpxclient = httpx.Client( base_url="https://api.skynetgo.org/v1", headers={"Authorization": f"Bearer {os.environ['SKYNET_TOKEN']}"}, timeout=30.0,)const API = 'https://api.skynetgo.org/v1';async function api(path: string, init: RequestInit = {}): Promise<any> { const res = await fetch(`${API}${path}`, { ...init, headers: { Authorization: `Bearer ${process.env.SKYNET_TOKEN}`, 'Content-Type': 'application/json', ...init.headers, }, }); if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`); return res.json();}export SKYNET=https://api.skynetgo.org/v1export TOK=$SKYNET_TOKEN # see Authenticationauth=(-H "Authorization: Bearer $TOK" -H "Content-Type: application/json")For typed models, generate them from the OpenAPI document (see Quickstart: Python and Quickstart: TypeScript).
Step 1 — Find your submission context
Section titled “Step 1 — Find your submission context”You need an observing grant that funds the telescope, that telescope’s imager, and the filter specifiers you want. You do not send an owner: you create the observation under the entity that owns the grant’s observing account (/users/{slug} or /organizations/{slug}), and the API rejects a grant from another owner’s account.
# Telescopes you can observe with; each embeds its instruments:scopes = client.get("/me/observing-access/telescopes").raise_for_status().json()telescope = next(t for t in scopes if t["name"] == "<telescope-name>")telescope_uid = telescope["uid"]
# The telescope's optical imager + its filters:imager = next(i for i in telescope["instruments"] if i["instrumentType"] == "optical_imager")instrument_uid = imager["uid"]filter_specifiers = sorted({f for w in imager["filterWheels"] for pos in w["positions"] for f in pos["filterIds"]})
# One of your grants that can fund this telescope, and the owner it belongs to:grants = client.get("/me/observing-access/observing-grants", params={"telescopeUid": telescope_uid}).raise_for_status().json()grant_uid = grants[0]["uid"]owner = grants[0]["account"]["owner"]owner_path = f"/{'organizations' if owner['entityType'] == 'organization' else 'users'}/{owner['slug']}"// Telescopes you can observe with; each embeds its instruments:const scopes = await api('/me/observing-access/telescopes');const telescope = scopes.find((t: any) => t.name === '<telescope-name>');
// The telescope's optical imager + its filters:const imager = telescope.instruments.find((i: any) => i.instrumentType === 'optical_imager');const instrumentUid = imager.uid;const filterSpecifiers = [...new Set(imager.filterWheels.flatMap((w: any) => w.positions.flatMap((pos: any) => pos.filterIds)))];
// One of your grants that can fund this telescope, and the owner it belongs to:const grants = await api(`/me/observing-access/observing-grants?telescopeUid=${telescope.uid}`);const grantUid = grants[0].uid;const owner = grants[0].account.owner;const ownerPath = `${owner.entityType === 'organization' ? 'organizations' : 'users'}/${owner.slug}`;curl -s "${auth[@]}" "$SKYNET/me/observing-access/telescopes" | jq '.[] | {uid,slug,name}'export TELESCOPE_UID=<telescope-uid>curl -s "${auth[@]}" "$SKYNET/me/observing-access/telescopes?telescopeUid=$TELESCOPE_UID" \ | jq '.[].instruments[] | select(.instrumentType=="optical_imager") | {uid, filters: [.filterWheels[].positions[].filterIds[]] | unique}'curl -s "${auth[@]}" "$SKYNET/me/observing-access/observing-grants?telescopeUid=$TELESCOPE_UID" \ | jq '.[] | {uid, owner: .account.owner.slug, ownerType: .account.owner.entityType}'Keep the telescope’s uid, one grant’s uid and its owner, the imager’s uid, and the filter specifier(s) you want (e.g. "lum").
Step 2 — Resolve a target
Section titled “Step 2 — Resolve a target”Named objects — asteroids, comets, satellites, solar-system bodies
Section titled “Named objects — asteroids, comets, satellites, solar-system bodies”GET /catalog-objects/search?q= resolves a name, designation, or catalog number to a ready-to-submit position block (covering SIMBAD stars/DSOs, NORAD satellites with live TLEs, MPC orbits and comets, and major bodies).
hit = client.get("/catalog-objects/search", params={"q": "Eros"}).raise_for_status().json()[0]position = hit["position"] # {"positionType": "catalog", "catalogObjectUid": "<uid>", ...}const hits = await api('/catalog-objects/search?q=Eros');const position = hits[0].position; // { positionType: 'catalog', catalogObjectUid: '<uid>', ... }curl -s "${auth[@]}" "$SKYNET/catalog-objects/search?q=Eros" \ | jq '.[0].position' # → {positionType:"catalog", catalogObjectUid:"<uid>", ...}Deep-sky objects observable now
Section titled “Deep-sky objects observable now”GET /common-targets?latitudeDeg=&longitudeDeg= ranks visible DSOs (galaxies, nebulae, clusters) by brightness and hours-visible for a site, returning raDeg / decDeg you submit as a fixed position. Take the site from the telescope record you picked in Step 1 (publicLatitudeDeg / publicLongitudeDeg).
curl -s "${auth[@]}" "$SKYNET/common-targets?latitudeDeg=<site-latitude>&longitudeDeg=<site-longitude>" \ | jq '[.[] | {name, targetType, raDeg, decDeg, maxAlt: .observability[0].maxAltitude}] | sort_by(-.maxAlt)[:10]'Step 3 — Build and submit
Section titled “Step 3 — Build and submit”POST /users/{slug}/observations or POST /organizations/{slug}/observations, for the owner of the grant’s account. The body below is the minimal valid shape; see the Observation, OpticalImagingConfiguration, and OpticalImagingRequest schemas for every field.
# --- pick ONE position ---# (a) catalog object (asteroid / satellite), from Step 2:position = {"positionType": "catalog", "catalogObjectUid": hit["position"]["catalogObjectUid"]}# (b) fixed DSO:# position = {"positionType": "fixed",# "coordinates": {"coordinateType": "equatorial", "raDeg": 49.575, "decDeg": -66.5}}
body = { "name": "Eros rate-track test", "target": {"name": "Eros", "position": position}, "opticalImagingConfiguration": { "trackingMode": "target", # 'target' for movers, 'sidereal' for DSOs "ditherStrategy": "none", "temporalOffsetSec": 0.0, "maxTiles": 1, "tileOverlap": 0.0, # brightness/saturation models size exposures (required for SNR / well-depth): "brightnessModel": {"modelType": "source", "magnitudeMag": 14.0, "filterId": "V"}, "saturationModel": {"modelType": "source", "magnitudeMag": 8.0, "filterId": "V"}, }, "requests": [{ "requestType": "optical_imaging", "order": 0, "filterSpecifierIds": ["lum"], "exposureTimeSec": 10.0, # set ONE of: exposureTimeSec | targetSnr | targetFullWellFraction "sampleCount": 3, }], "observingGrantUids": [grant_uid], "instrumentMode": "include", # restrict to instrumentUids "instrumentUids": [instrument_uid],}
created = client.post(f"{owner_path}/observations", json=body).raise_for_status().json()print("created observation", created["uid"])// ownerPath from Step 1: the owner of the grant's account.const created = await api(`/${ownerPath}/observations`, { method: 'POST', body: JSON.stringify({ name: 'Eros rate-track test', target: { name: 'Eros', position, // the catalog position from Step 2 // or a fixed DSO: // position: { positionType: 'fixed', // coordinates: { coordinateType: 'equatorial', raDeg: 49.575, decDeg: -66.5 } }, }, opticalImagingConfiguration: { trackingMode: 'target', // 'target' for movers, 'sidereal' for DSOs ditherStrategy: 'none', temporalOffsetSec: 0.0, maxTiles: 1, tileOverlap: 0.0, brightnessModel: { modelType: 'source', magnitudeMag: 14.0, filterId: 'V' }, saturationModel: { modelType: 'source', magnitudeMag: 8.0, filterId: 'V' }, }, requests: [{ requestType: 'optical_imaging', order: 0, filterSpecifierIds: ['lum'], exposureTimeSec: 10.0, // one sizing mode sampleCount: 3, }], observingGrantUids: [grantUid], instrumentMode: 'include', // restrict to instrumentUids instrumentUids: [instrumentUid],}) });console.log('created observation', created.uid);curl -s "${auth[@]}" -X POST "$SKYNET/users/<owner-slug>/observations" -d '{ "name": "Eros rate-track test", "target": { "name": "Eros", "position": { "positionType": "catalog", "catalogObjectUid": "<catalog-object-uid>" } }, "opticalImagingConfiguration": { "trackingMode": "target", "ditherStrategy": "none", "temporalOffsetSec": 0.0, "maxTiles": 1, "tileOverlap": 0.0, "brightnessModel": { "modelType": "source", "magnitudeMag": 14.0, "filterId": "V" }, "saturationModel": { "modelType": "source", "magnitudeMag": 8.0, "filterId": "V" } }, "requests": [ { "requestType": "optical_imaging", "order": 0, "filterSpecifierIds": ["lum"], "exposureTimeSec": 10.0, "sampleCount": 3 } ], "observingGrantUids": ["<grant-uid>"], "instrumentMode": "include", "instrumentUids": ["<instrument-uid>"]}' | jq '{uid, name, status}'The choices that matter
Section titled “The choices that matter”| Field | Meaning |
|---|---|
opticalImagingConfiguration.trackingMode |
sidereal for stars/DSOs; target for non-sidereal rate tracking of asteroids/comets/satellites. |
repointingStrategy, temporalOffsetSec |
(on the config) repoint policy and lead-ahead offset for fast movers. |
| request exposure spec | Set one of exposureTimeSec, targetSnr, targetFullWellFraction. SNR / well-depth need the config’s brightnessModel to size against. |
observingGrantUids |
The grants that fund the observation; together they decide which telescopes it can run on. Every grant’s account must belong to the owner in the URL. |
instrumentMode + instrumentUids |
include restricts the observation to the listed instruments (exclude rules them out). With the default none, instrumentUids is ignored. There’s no telescope field on the body: pin a telescope by including only its imager. |
sampleCount, and the scheduling-policy fields on the body (epochCount, cadence*, copies*) |
How many frames per pass, and how passes repeat over time. Defaults give a single epoch, ASAP. See the scheduling guide. |
Step 4 — Track progress and download results
Section titled “Step 4 — Track progress and download results”Frames land as assets under the observation. Poll incrementally with createdAfter, transfer any that are still node-resident, then download.
OBS=<observation-uid># New frames since a cutoff (newest-first by default):curl -s "${auth[@]}" "$SKYNET/observations/$OBS/assets?createdAfter=2026-06-28T00:00:00Z" \ | jq '.items[] | {uid, name: .file.name, role, transferState, qaStatus}'
# If transferState != "transferred", request it off the node, then poll the one asset:curl -s "${auth[@]}" -X POST "$SKYNET/observations/$OBS/assets/<asset-uid>/request-transfer"curl -s "${auth[@]}" "$SKYNET/observations/$OBS/assets/<asset-uid>" | jq '{transferState, copyStatus}'
# Download (redirects via /files/{uid}/data to a presigned storage URL; follow with -L):curl -sL "${auth[@]}" "$SKYNET/observations/$OBS/assets/<asset-uid>/data" -o frame.fitsUseful asset filters: role / roleExclude, qaStatus / serverQaStatus, transferState, isTransferrable, name, taskUids. For realtime delivery instead of polling, subscribe over the WebSocket streams.
Sharp edges
Section titled “Sharp edges”Next steps
Section titled “Next steps”- Conventions — pagination, errors, discriminators.
- Scheduling & repetition — epochs, cadence, copies.
- Observation schema and the Observation API reference — every field and endpoint.
- WebSocket streams — push delivery of new assets and state.