Quickstart: TypeScript
The same “list telescopes, create an observation, watch it run” walkthrough as the curl quickstart, in TypeScript with plain fetch. For the full treatment (catalog and non-sidereal targets, exposure sizing, file download) see Creating observations.
Prereqs
Section titled “Prereqs”- Node 20+ (for built-in
fetch). - An access token. See Auth; a scoped token cannot create observations.
const API = 'https://api.skynetgo.org/v1';const token = process.env.SKYNET_TOKEN!;
async function api<T>(path: string, init: RequestInit = {}): Promise<T> { const res = await fetch(`${API}${path}`, { ...init, headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...init.headers, }, }); if (!res.ok) { throw new Error(`HTTP ${res.status}: ${await res.text()}`); } return res.json() as Promise<T>;}For refresh-token rotation, read the current token inside api() instead of capturing a constant.
Walkthrough
Section titled “Walkthrough”An observation is created in one POST from a complete body. The wire format is camelCase JSON with snake_case enum values, matching the API reference.
async function main() { // 1. Who am I? const user = await api<any>('/me'); console.log(`Hello, ${user.username}`);
// 2. A telescope you can submit to; each entry embeds its instruments const scopes = await api<any[]>('/me/observing-access/telescopes'); const telescope = scopes[0]; const imager = telescope.instruments.find((i: any) => i.instrumentType === 'optical_imager'); const filterSpecifier = imager.filterWheels[0].positions[0].filterIds[0];
// 3. One of your grants that funds it; its account's owner owns the observation const grants = await api<any[]>(`/me/observing-access/observing-grants?telescopeUid=${telescope.uid}`); const grant = grants[0]; const owner = grant.account.owner; const ownerPath = owner.entityType === 'organization' ? 'organizations' : 'users';
// 4. Create the observation in one call const created = await api<any>(`/${ownerPath}/${owner.slug}/observations`, { method: 'POST', body: JSON.stringify({ name: 'TS 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: [filterSpecifier], exposureTimeSec: 60.0, sampleCount: 1, }], observingGrantUids: [grant.uid], instrumentMode: 'include', // restricts the observation to instrumentUids instrumentUids: [imager.uid], }), }); console.log(`Created observation ${created.uid} (status=${created.status})`);
// 5. Watch it run for (let i = 0; i < 5; i++) { await new Promise(r => setTimeout(r, 20_000)); const obs = await api<any>(`/observations/${created.uid}`); console.log(`${i}: status=${obs.status} progress=${obs.progressFraction}`); }}
main().catch(err => { console.error('Failed:', err); process.exit(1);});- Field names are camelCase, enum values are snake_case —
requestType: 'optical_imaging', not'opticalImaging'. See Conventions. - Pin the instrument with
instrumentMode: 'include'— without itinstrumentUidsis ignored. - Exposure sizing — set one of
exposureTimeSec,targetSnr, ortargetFullWellFractionper 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.
Typed client
Section titled “Typed client”For typed paths, parameters and bodies now, generate types from the OpenAPI document the API reference is built from, https://docs.skynetgo.org/openapi.json, with openapi-typescript and call the API through openapi-fetch:
npm install openapi-fetchnpx openapi-typescript https://docs.skynetgo.org/openapi.json -o skynet.d.tsimport createClient from 'openapi-fetch';import type { paths } from './skynet.d.ts';
const client = createClient<paths>({ baseUrl: 'https://api.skynetgo.org', // paths in the document already start with /v1 headers: { Authorization: `Bearer ${process.env.SKYNET_TOKEN}` },});
const { data, error, response } = await client.GET('/v1/me');openapi-fetch doesn’t throw on non-2xx responses: check error and response.status. Polymorphic resources (requests, positions, devices) come out as discriminated unions, so TypeScript narrows the concrete shape when you switch on the discriminator.
Next steps
Section titled “Next steps”- Creating observations — catalog and non-sidereal targets, exposure sizing, file download.
- For realtime subscriptions, see WebSocket streams.
- For the Python equivalent, see Quickstart: Python.