Skip to content

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.

  • 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.

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 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.

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:

Terminal window
npm install openapi-fetch
npx openapi-typescript https://docs.skynetgo.org/openapi.json -o skynet.d.ts
import 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.