METADATA FIRST · API V1
Find observations before pixels.
Query sky footprints, detector arrays and observation dates. Metadata endpoints do not download images. The API base URL is the same site address as this viewer. This development instance has not undergone public hosted load verification.
Sky viewer · Download OpenAPI contract · Supported options
Try a metadata-only request
This example uses mode=cache_only and cannot fetch image pixels or archive metadata.
Durable field downloads
POST /api/v1/field-downloads accepts RA, Dec, fov_arcmin and up to 500 indexed observation_ids. It returns a persistent job ID. Read GET /api/v1/field-downloads/{id} for every observation’s status and current common-stretch sequence_id. POST an empty object to /api/v1/field-downloads/{id}/stop to stop after the current cutout. Posting the same field/IDs explicitly resumes stopped or interrupted work. Closing the browser does not cancel the server job; a server restart leaves it interrupted until explicitly resumed. Three consecutive failures pause the job rather than hammer an unavailable archive.
Endpoints
GET /api/v1/field-audit?ra=…&dec=…&fov_arcmin=… reviews every locally indexed overlap without downloading headers/pixels. GET /api/v1/catalogue-sync reports all-sky ingestion status. POST /api/v1/mosaics accepts the sequence request schema and builds an explicitly exploratory spatial mosaic from same-detector/release sources.
| Method | Route | Purpose |
|---|---|---|
| GET | /api/v1/observations | Spatial search, detector/release/date filters, chronological pagination |
| GET | /api/v1/observations/{id} | One indexed record and archive provenance |
| GET | /api/v1/coverage | Known completeness and freshness; no upstream call |
| GET | /api/v1/targets · /options · /status | Presets, capabilities and latency telemetry |
| GET | /api/v1/overlays/gaia or wise | Catalogue positions with epoch/motion caveats |
| POST | /api/v1/sequences | Explicitly prepare 1–24 selected image regions |
| GET | /api/v1/sequences/{id} | Read status; never resume image downloads implicitly |
| GET | /api/v1/products/{id}/{name} | Read an existing PNG, GIF, manifest or aligned array |
| GET | /api/v1/cutouts/{id} | Read an existing native-region FITS |
Integration rules
Use mode=auto to fetch missing archive metadata on demand, or mode=cache_only to stay offline. A missing or stale region index is reported explicitly. An empty incomplete result is not proof of no public coverage. All FOV values are circular diameters in arcminutes; coordinates are ICRS degrees. Time filters use inclusive exposure-interval overlap in MJD.
Use detector=1..6, collections=spherex_dr1,spherex_qr3, start_mjd, end_mjd, sort=asc|desc and limit=1..500. Follow pagination.next_cursor; changing filters invalidates it. A 409 catalogue_changed response means restart pagination.
Metadata bounds describe the detector range, not the wavelength at the target. Footprint overlap does not establish detection, usable masks, independent epochs or matching spectral responses. Sequence products retain additional scientific limitations.
Public metadata GETs allow cross-origin reads without credentials. Image-preparation POSTs allow same-origin browser calls by default; an operator can explicitly configure additional allowed origins/hosts for an authorized deployment. The server remains bound to localhost by default.
JavaScript
const query = new URLSearchParams({
ra: '133.7951291667', dec: '-7.2451472222',
fov_arcmin: '5', detector: '4', limit: '20', mode: 'cache_only'
});
const response = await fetch(`${base}/api/v1/observations?${query}`);
const data = await response.json();
if (!response.ok) throw new Error(data.error.message);
console.log(data.observations, data.coverage);Explicit image preparation
POST /api/v1/sequences
Content-Type: application/json
{"ra":133.7951291667,"dec":-7.2451472222,"fov_arcmin":5,
"observation_ids":["...indexed image ID..."],
"match_wavelengths":true,"cached_only":true}cached_only=true returns 409 for a sequence that is not already prepared. Omitting it authorizes bounded on-demand image preparation. It never requests all observations in the catalogue.