HTTP API reference

One JSON and binary API for both datasets. Small anonymous reads, account access and reproducible release identifiers.

API 3.1 · source stars release 55c97bc0c218a6c5 · source SS release ef7caf53a399bc1f

Basics#

All endpoints live under one base URL:

Text

https://asassn-v3.ifa.hawaii.edu/v3/

The public service is https://asassn-v3.ifa.hawaii.edu. This deployment serves 19 stars and 54 Solar System objects; check /v3/release for actual coverage.

Methods. Science reads use GET or bounded batch POSTs. Account changes use same-origin POSTs. Science GET endpoints send Access-Control-Allow-Origin: *, so a web page on any site can call them.
Anonymous. Interactive use needs no account and no key. Accounts and API tokens are available for larger bounded requests.
Deterministic. Science values are reproducible for a fixed release and selection. Account usage and operational metadata change over time.
Strict parameters. An unknown or repeated parameter is an error (400), not silently ignored. Integers may be decimal or hex (exclude_quality=0x17).
Compression. Responses are compressed with zstd, brotli or gzip, in that order of preference, according to your Accept-Encoding. curl needs --compressed to ask for it.

Launch status#

Each dataset reports its state in /v3/release as datasets.stars.state and datasets.ss.state. While a dataset is loading or being verified, its endpoints answer 503 with error dataset_unavailable and a Retry-After header; the other dataset keeps working. Both real sample datasets are ready; full-survey coverage is not yet available on this server.

Batch streams and tokens are enabled. Large asynchronous jobs and arbitrary queries remain unavailable; some inherited endpoint descriptions describe future work.

Identifiers#

Stars: {ref} in /v3/stars/{ref}: The V3 star_id, an integer that fits safely in a JavaScript number (also written sp3:11010359 or V3 11010359), an AV3 name such as AV3_085448.87+200630.6, or a Gaia id written Gaia DR3 660820614442429056 or Gaia DR2 … (encode the spaces: Gaia%20DR3%20660820614442429056). Encode + as %2B in a URL. V2 ids are different numbers and do not work here.
Gaia: /v3/stars/gaia/{release}/{source_id}: A Gaia DR3 (dr3, or edr3: the same ids) or DR2 (dr2) source_id. JSON always carries Gaia ids as decimal strings, because they need 63 bits. See Gaia lookups.
Solar system: {ref} in /v3/ss/objects/{ref}: The object_id, a 63-bit integer that JSON always carries as a decimal string; a slug (20, 2P, C_2020_F3, 2019_AB1, id-<object_id>); or any name, number, designation, packed designation or SPK id that matches one object. An ambiguous name such as encke returns 300 with the candidates; an unknown one returns 404 with suggestions. Percent-encode spaces and slashes: C%2F2020%20F3.

Gaia lookups#

Every V3 star was matched to Gaia DR3 and Gaia DR2 at epoch 2015.5 (how, and how well). Three ways in:

One id: GET /v3/stars/gaia/dr3/660820614442429056 returns {release, source_id, epoch, matches: [...]}. Each match has the star_id, name, position, reference magnitude, sep_mas, quality and both Gaia ids. Usually there is one match; a shared source lists every V3 star matched to it, nearest first. The answer is also available under /v3/r/{serve_id}/.
Many ids: POST /v3/stars/gaia/dr3 with the body {"ids": [...]}, up to 3 anonymous or 100 authenticated ids per request, as JSON integers or decimal strings. The results come back in your order: {source_id, star_id, n_stars, sep_mas, quality, name, ra, dec, mag}, with star_id: null when there is no V3 star and an error for an id that is not a valid Gaia source_id. Each source ID counts toward the daily quota; request and shared-IP limits also apply.
Anywhere a star is named: /v3/stars/Gaia%20DR3%20660820614442429056/lc, and /v3/resolve?q=Gaia DR3 …. /v3/resolve also accepts DR3 <id>, GDR2 <id>, Gaia <id> and a bare 15–19 digit id. Without a named release it tries DR3, then DR2, and the candidate's match_kind (gaia_dr3 or gaia_dr2) says which matched.

A Gaia id with no V3 star returns 404 not_found. Its suggestions name the other release when the id is a match there, and explain the cone-search fallback: find the source's position and call /v3/stars/cone. An id that cannot be a Gaia source_id returns 400 invalid_id.

Versioned URLs and `serve_id`#

Every GET endpoint is also available under /v3/r/{serve_id}/, for example

Python

import json, urllib.request
base = "https://asassn-v3.ifa.hawaii.edu"
with urllib.request.urlopen(base + "/v3/release") as response:
    serve_id = json.load(response)["datasets"]["stars"]["serve_id"]
url = f"{base}/v3/r/{serve_id}/stars/11010359/lc?format=csv"
with urllib.request.urlopen(url) as response:
    csv_bytes = response.read()

Each dataset has one serve_id: the first 16 hex digits of a SHA-256 over the release id, the decoder version, the default parameters and the format version. Any change to the data, the decoder or a default produces a new serve_id. A versioned URL pins the science release. This account-enabled service sends no-store responses so every request passes admission. Use versioned URLs when you need to reproduce a result exactly; the website uses them for every light curve.

Get the current ids from /v3/release or from the X-SP3-Serve-Id response header. A serve_id the server no longer serves returns 404 release_not_served with the ids it does serve.

Formats#

Light-curve endpoints take format=sp3c (the default, binary), json, csv, ecsv, arrow or parquet. Cone searches take json (default) or csv. Text and Parquet downloads carry a Content-Disposition file name. All formats hold the same values exactly; the formats page describes each one.

Response headers#

Header	Meaning
`X-SP3-Serve-Id`	The `serve_id` of the dataset that answered
`X-SP3-Rows`	Number of light-curve rows in the body
`Server-Timing`	`read`, `decode`, `encode` and `total` times in milliseconds
`ETag`	On versioned URLs; send it back in `If-None-Match` to get `304 Not Modified`
`Retry-After`	On 429 and 503: seconds to wait before retrying

Browsers can read all of these from JavaScript (Access-Control-Expose-Headers).

Caching#

API and account responses use Cache-Control: no-store and vary by Cookie and Authorization. Internally cached results still pass quota and access checks. Release-pinned URLs provide reproducibility without bypassing admission. Static website assets have short browser caching.

Rate limits and accounts

Access	Source requests/day	Download/day	Targets/batch	Cone radius
No account	500	512 MiB	3	60 arcsec
Registered (email login)	3,000	4 GiB	100	600 arcsec
Verified by the ASAS-SN team	50,000	100 GiB	1,000	3,600 arcsec

Verification requires team approval. Email confirmation or Google/Apple sign-in alone does not grant the highest tier. Daily allowances count repeated source requests, searches and batch entries; they are not counts of distinct stars. All tokens share their account’s allowance.

Rates are 30, 60 and 120 science requests/minute for the three tiers, with bursts of 8, 12 and 20. Shared IP limits also apply: 180 requests/minute, a combined 100,000 source requests / 200 GiB daily ceiling, and a separate 5,000 / 5 GiB budget shared by anonymous and registered requests. Team-verified use does not consume that smaller budget. IPv6 addresses share a /64 budget. At most two requests run per IP/account (four for team-verified requests), eight globally. Cached results still pass admission. Responses are capped at 16 MiB anonymous and 64 MiB authenticated; use smaller batches when light curves are large.

Honor Retry-After on 429/503 responses. Metadata and account controls have separate limits, so exhausted data quotas do not prevent token revocation.

Access tokens

Register or sign in to create a revocable token, then send Authorization: Bearer <token>. The Python client reads ASASSNV3_TOKEN. Account changes require a same-origin browser session and CSRF; API tokens authorize science queries only. Recovery uses the one-time code issued at registration. Recovery revokes all sessions and tokens. Large asynchronous jobs remain disabled.

Errors#

Every error is JSON:

JSON

{"error": "invalid_parameter", "message": "aperture must be one of default, 1, 1.5, 2, 3, all",
 "request_id": "…"}

error is a stable code for programs; message is for people. Some errors add a details object, and 300 and 404 add candidates or suggestions.

Status	`error`	Meaning
300	`ambiguous`	The name matches several objects; `candidates` lists them
400	`invalid_parameter`, `unknown_parameter`, `invalid_id`, `invalid_json`	Fix the request; the message names the parameter
401, 403	`unauthorized`, `forbidden`	Missing, invalid or insufficient token
404	`not_found`	No such star or object; SS and Gaia lookups add `suggestions`
404	`release_not_served`	The `serve_id` in the path is not served; the response lists the current ones
409	`release_mismatch`	rc1 client only: the client expected another release
413	`too_many_ids`, `query_too_large`, `response_too_large`	Split the request
429	`rate_limited`	Slow down; see `Retry-After`
503	`busy`, `dataset_unavailable`, `draining`	Try again after `Retry-After`
500	`internal_error`	Our fault; please report the `request_id`

A star with no photometry is not an error: its light curve returns 200 with n = 0.

Endpoints#

Method	Path	Summary	Access
GET	`/v3/health`	Liveness and readiness	anonymous
GET	`/v3/release`	Served releases and their serve ids	anonymous
GET	`/v3/status`	Status banner and dataset states	anonymous (token optional)
GET	`/v3/flags`	Quality-bit definitions and presets	anonymous
GET	`/v3/resolve`	Parse and resolve a search string	anonymous
GET	`/v3/stars/cone`	Cone search of the V3 star catalog	anonymous
GET	`/v3/stars/{ref}`	Star summary	anonymous
GET	`/v3/stars/{ref}/lc`	Star light curve	anonymous
GET	`/v3/ss/suggest`	Autocomplete solar-system names	anonymous
GET	`/v3/ss/resolve`	Resolve a solar-system name	anonymous
GET	`/v3/ss/objects/{ref}`	Solar-system object summary	anonymous
GET	`/v3/ss/objects/{ref}/lc`	Solar-system light curve	anonymous
GET	`/v3/ss/objects/{ref}/orbit`	Orbit polyline	anonymous
GET	`/v3/ss/top-names.json`	Top 5,000 names for instant autocomplete	anonymous
GET	`/v3/stars/gaia/{release}/{source_id}`	Gaia DR3 / DR2 source_id -> V3 star (crossmatch at epoch 2015.5)	anonymous
POST	`/v3/stars/gaia/{release}`	Many Gaia source_ids -> V3 stars at once (results in request order; ids as strings)	anonymous
POST	`/v3/stars/lc`	Batch of star light curves (stream)	anonymous ≤ 3 ids; token ≤ 100
POST	`/v3/ss/lc`	Batch of solar-system light curves (stream)	anonymous ≤ 3 refs; token ≤ 100
POST	`/v3/jobs`	Submit a bulk job Coming soon	token
GET	`/v3/jobs/{id}`	Job status Coming soon	token
DELETE	`/v3/jobs/{id}`	Cancel a job or delete its files Coming soon	token
GET	`/v3/jobs/{id}/files/{name}`	Download a job output file Coming soon	token
POST	`/v3/cone`	rc1 cone search Coming soon	anonymous
POST	`/v3/query`	rc1 native packet stream Coming soon	token

The machine-readable description is openapi.json (OpenAPI 3).

Meta#

GET `/v3/health`#

Liveness and readiness

auth anonymouscache no-store

200 once the process has opened its data, checked the verification receipts and passed its decode self-test; 503 before that. Never cached.

Responses

200 Ready application/json
503 Error (dataset_unavailable, draining) application/json

GET `/v3/release`#

Served releases and their serve ids

auth anonymouscache no-store

Release identifiers, counts and serve_id for each dataset. The top-level api_version, release_id and error_models keys keep the rc1 client working.

Responses

200 Release description application/json

Example

Recorded response GET /v3/release

{
  "api_version": "3.1",
  "release_id": "55c97bc0c218a6c52fa9345281389dd39a8c4bd139d55c14ca87bd209a760d09",
  "error_models": ["legacy"],
  "datasets": {
    "stars": {
      "release_id": "55c97bc0c218a6c52fa9345281389dd39a8c4bd139d55c14ca87bd209a760d09",
      "serve_id": "4b8c08cfa8db7f77",
      "format": "ASASSN-packed-serving-1",
      "n_stars": 164180266,
      "n_rows": 1208287002041,
      "n_images": 15164380,
      "reference_epoch": 2015.5,
      "state": "ready"
    },
    "ss": {
      "release_id": "ef7caf53a399bc1f041b92883a3793bcf362f12899312c429f0c3c70e7ac6053",
      "serve_id": "9da09aa7b791c1e0",
      "format": "ASASSN-ss-release-1",
      "n_objects": 196860,
      "n_observations": 2104444707,
      "n_measurements": 12614759891,
      "apertures": [0.75, 1.0, 1.25, 1.5, 2.0, 3.0],
      "bands": ["g", "V"],
      "products": ["red", "conv"],
      "state": "ready"
    }
  },
/* … 2 more lines */

GET `/v3/status`#

Status banner and dataset states

auth anonymous (token optional)cache no-store

The operator message shown as the site banner, and each dataset's state (ready, loading or unavailable). With a valid token it also returns the token's limits and usage.

Responses

200 Status application/json

Example

Recorded response GET /v3/status

{"message": null, "datasets": {"stars": "ready", "ss": "ready"}}

GET `/v3/flags`#

Quality-bit definitions and presets

auth anonymouscache no-store

The 13 Q5 quality bits (value, bit, name, group, meaning), the SS moving_quality bits, and the recommended definitions and presets (stars: recommended 0x17, strict 0x1F7F, all 0).

Also available as GET /v3/r/{serve_id}/flags, with the specified release (versioned URLs).

Responses

200 Flag tables application/json

Resolution#

GET `/v3/resolve`#

Parse and resolve a search string

auth anonymouscache no-store

Uses local data only (the server makes no outbound calls). Understands coordinates with an optional radius, AV3 names, sp3:<n>, bare integers, and solar-system names, numbers and designations. Stellar names such as OJ 287 are resolved in the browser through Sesame; sesame_suggested is true when the text looks like such a name and nothing local matched.

Also available as GET /v3/r/{serve_id}/resolve, with the specified release (versioned URLs).

Parameters

Parameter	In	Type	Default	Description
`q`required	query	string ≤ 256 chars	—	Search text. e.g. `08:54:48.9 +20:06:30.6 r=30"`
`scope`	query	string one of `auto`, `stars`, `ss`	`auto`	Restrict the interpretation. A bare integer is a star id in `stars`, an asteroid number in `ss`, and both in `auto`.
`limit`	query	integer ≥ 1, ≤ 50	`10`	Maximum number of candidates.

Responses

200 Parsed query and candidates application/json
400 Error (invalid_parameter, unknown_parameter, invalid_id) application/json
429 Error (rate_limited) application/json
503 Error (busy, dataset_unavailable, draining) application/json

Example

Recorded response GET /v3/resolve?q=AV3_085448.87%2B200630.6

{
  "query": "AV3_085448.87+200630.6",
  "scope": "auto",
  "parsed": {"kind": "av3", "name": "AV3_085448.87+200630.6", "ordinal": false},
  "candidates": [
    {
      "type": "star",
      "star_id": 11010359,
      "name": "AV3_085448.87+200630.6",
      "ra": 133.7036455,
      "dec": 20.1085113,
      "mag": 15.415035059,
      "match_kind": "av3"
    }
  ],
  "status": "unique",
  "sesame_suggested": false
}

Stars#

GET `/v3/stars/cone`#

Cone search of the V3 star catalog

auth anonymouscache no-store

Stars within r arcsec of (ra, dec), sorted by separation. Positions are ICRS at the catalog reference epoch 2015.5. n_epochs_g and n_epochs_V count every default-aperture row, including non-detections.

Also available as GET /v3/r/{serve_id}/stars/cone, with the specified release (versioned URLs).

Parameters

Parameter	In	Type	Default	Description
`ra`required	query	number ≥ 0, ≤ 360	—	Right ascension, degrees (ICRS). e.g. `133.7036`
`dec`required	query	number ≥ -90, ≤ 90	—	Declination, degrees (ICRS). e.g. `20.1085`
`r`	query	number ≥ 0.001, ≤ 600	`60`	Radius in arcsec. At most 60 anonymously and 600 with a token.
`limit`	query	integer ≥ 1, ≤ 1000	`100`	Maximum rows. `truncated` is true when more stars matched.
`mag_max`	query	number ≥ -5, ≤ 30	—	Only stars with catalog g magnitude at or brighter than this.
`format`	query	string one of `json`, `csv`	`json`	Response format.

Responses

200 Matching stars application/json, text/csv
400 Error (invalid_parameter, unknown_parameter, invalid_id) application/json
429 Error (rate_limited) application/json
503 Error (busy, dataset_unavailable, draining) application/json

Example

Recorded response GET /v3/stars/cone?dec=20.1085&r=60&ra=133.7036

{
  "serve_id": "4b8c08cfa8db7f77",
  "ra": 133.7036,
  "dec": 20.1085,
  "r": 60.0,
  "truncated": false,
  "rows": [
    {
      "star_id": 11010359,
      "name": "AV3_085448.87+200630.6",
      "ra": 133.7036455,
      "dec": 20.1085113,
      "pmra": 0.0,
      "pmdec": -0.14,
      "mag": 15.415035059,
      "mag_err": 0.0275620086823,
      "n_fields": 3,
      "sep_arcsec": 0.15910374871725178,
      "n_epochs_g": 8328,
      "n_epochs_V": 1848
    },
    {
      "star_id": 11010364,
      "name": "AV3_085445.08+200649.9",
      "ra": 133.6878247,
      "dec": 20.1138676,
      "pmra": 12.77,
      "pmdec": -8.9,
/* … 9 more lines */

GET `/v3/stars/{ref}`#

Star summary

auth anonymouscache no-store

Catalog entry, available apertures and the list of curves (field, band, aperture, row count). Approximately 1 KB; reads no photometry.

Also available as GET /v3/r/{serve_id}/stars/{ref}, with the specified release (versioned URLs).

Parameters

Parameter	In	Type	Default	Description
`ref`required	path	string	—	Star reference: the integer `star_id` (row index in the V3 catalog) or an AV3 name such as `AV3_085448.87+200630.6` (optional `_s<star_id>` and `_ap<100\|150\|200\|300>` suffixes, or the ordinal form `AV3_<n>`). e.g. `11010359`

Responses

200 Star summary application/json
400 Error (invalid_parameter, unknown_parameter, invalid_id) application/json
429 Error (rate_limited) application/json
503 Error (busy, dataset_unavailable, draining) application/json
404 Error (not_found) application/json

GET `/v3/stars/{ref}/lc`#

Star light curve

auth anonymouscache no-store

Decoded photometry for one star. Rows are grouped by curve (entry, field, band) in rc1 order and sorted by jd within each curve; the curve column indexes header.curves. Values are identical to the rc1 reference decoder. The decile bits 8-12 are computed on the full curve, before the rows and exclude_quality filters, so filtering never changes which rows carry them.

Also available as GET /v3/r/{serve_id}/stars/{ref}/lc, with the specified release (versioned URLs).

Parameters

Parameter	In	Type	Default	Description
`ref`required	path	string	—	Star reference: the integer `star_id` (row index in the V3 catalog) or an AV3 name such as `AV3_085448.87+200630.6` (optional `_s<star_id>` and `_ap<100\|150\|200\|300>` suffixes, or the ordinal form `AV3_<n>`). e.g. `11010359`
`aperture`	query	string one of `default`, `1`, `1.5`, `2`, `3`, `all`	`default`	Aperture radius in pixels (8.0 arcsec/px). `default` is the star's catalog default aperture; `all` returns every aperture the star has.
`band`	query	string one of `g`, `V`, `all`	`all`	Photometric band.
`fields`	query	string	`all`	Comma-separated ASAS-SN field names (e.g. `F0855+21_0458`). Default: all fields.
`cols`	query	string one of `lean`, `full`	`lean`	Column set. `lean` is what the website plots; `full` adds jd, ut_date, image, fwhm, zp, counts, counts_err, wcs_med, zp_fit_std, x, y and flat.
`rows`	query	string one of `all`, `detected`	`all`	`detected` drops non-detections.
`exclude_quality`	query	integer ≥ 0, ≤ 65,535	`0`	Drop rows whose `quality` shares any bit with this mask (decimal or 0x hex). 0 keeps every row; the website's Recommended preset is 23 (0x17). See flags.html.
`error_model`	query	string one of `legacy`	`legacy`	Uncertainty model. Only `legacy` is served until the v2 noise supplement is installed.
`format`	query	string one of `sp3c`, `json`, `csv`, `ecsv`, `arrow`, `parquet`	`sp3c`	Response format. `sp3c` is the compact binary columnar format used by the website; the others carry the same values (text floats use the shortest round-trip decimal). Text and Parquet responses set `Content-Disposition`.

Responses

200 The light curve. n = 0 when the star has no photometry. application/vnd.asassn.sp3c, application/json, text/csv, text/x-ecsv, application/vnd.apache.arrow.stream, application/vnd.apache.parquet
304 Not modified (If-None-Match matched the ETag).
400 Error (invalid_parameter, unknown_parameter, invalid_id) application/json
429 Error (rate_limited) application/json
503 Error (busy, dataset_unavailable, draining) application/json
404 Error (not_found, release_not_served) application/json
413 Error (response_too_large) application/json

GET `/v3/stars/gaia/{release}/{source_id}`#

Gaia DR3 / DR2 source_id -> V3 star (crossmatch at epoch 2015.5)

Also available as GET /v3/r/{serve_id}/stars/gaia/{release}/{source_id}, with the specified release (versioned URLs).

Parameters

Parameter	In	Type	Default	Description
`release`required	path	string one of `dr3`, `dr2`, `edr3`	—	Gaia data release (edr3 = dr3: the same source_ids and astrometry)
`source_id`required	path	string `^[0-9]{1,19}$`	—	Gaia source_id (decimal)

Responses

200 the V3 star(s) matched to the source, closest first application/json
304 Not modified (ETag)
400 invalid_parameter | unknown_parameter | invalid_id | invalid_json application/json
404 not_found: no V3 star is matched to this Gaia source (body.suggestions: the other release when the id is a match there, and the cone search) application/json
429 rate_limited (Retry-After) application/json
503 busy | dataset_unavailable | draining (Retry-After) application/json

POST `/v3/stars/gaia/{release}`#

Many Gaia source_ids -> V3 stars at once (results in request order; ids as strings)

Parameters

Parameter	In	Type	Default	Description
`release`required	path	string one of `dr3`, `dr2`, `edr3`	—	Gaia data release (edr3 = dr3: the same source_ids and astrometry)

Request body `application/json`

Field	Type	Default	Description
`ids`required	array of integer \| string ≤ 100 items; anonymous ≤ 3	—	Gaia source_ids: JSON integers or decimal strings

Responses

200 {release, n, n_found, serve_id, results: [{source_id, star_id|null, n_stars, sep_mas, quality, name, ra, dec, mag} | {source_id, star_id: null, error}]} application/json
400 invalid_parameter (body, ids, release) application/json
413 too_many_ids | query_too_large (body > limits.max_body_bytes) application/json
503 busy | dataset_unavailable (no Gaia sidecar) application/json

Solar system#

GET `/v3/ss/suggest`#

Autocomplete solar-system names

auth anonymouscache no-store

Prefix and token matches over approximately 980,000 name keys (numbers, names with diacritics folded, designations, packed designations, comets, SPK ids). Ranked by recommended difference-image detections.

Also available as GET /v3/r/{serve_id}/ss/suggest, with the specified release (versioned URLs).

Parameters

Parameter	In	Type	Default	Description
`q`required	query	string ≤ 256 chars	—	Partial name. e.g. `mass`
`n`	query	integer ≥ 1, ≤ 20	`10`	Maximum suggestions.

Responses

200 SS records with matched and match_kind application/json
400 Error (invalid_parameter, unknown_parameter, invalid_id) application/json
429 Error (rate_limited) application/json
503 Error (busy, dataset_unavailable, draining) application/json

Example

Recorded response GET /v3/ss/suggest?q=mass

{
  "query": "mass",
  "results": [
    {
      "object_id": "5624785654134724447",
      "slug": "20",
      "name": "(20) Massalia",
      "kind": "asteroid",
      "number": 20,
      "designation": null,
      "packed": ["00020"],
      "orbit_class": "Inner main belt",
      "H": 6.54,
      "n_obs": 10027,
      "n_obs_g": 8095,
      "n_obs_V": 1932,
      "n_good_g": 2729,
      "n_good_V": 674,
      "n_good_conv": 3424,
      "n_good": 3424,
      "median_mag_g": 11.274,
      "brightest_mag_g": 9.141,
      "brightest_pred_mag": 8.531,
      "first_jd": 2456438.11812,
      "last_jd": 2461276.47466,
      "first_good_jd": 2456443.10236,
      "last_good_jd": 2461260.2397,
      "matched": "massalia",
/* … 59 more lines */

GET `/v3/ss/resolve`#

Resolve a solar-system name

auth anonymouscache no-store

Exact resolution of a name, number, designation, packed designation or SPK id.

Also available as GET /v3/r/{serve_id}/ss/resolve, with the specified release (versioned URLs).

Parameters

Parameter	In	Type	Default	Description
`q`required	query	string ≤ 256 chars	—	Name to resolve. e.g. `Encke`
`limit`	query	integer ≥ 1, ≤ 50	`20`	Maximum number of candidates and suggestions to return.

Responses

200 {query, status, candidates[], suggestions[]} application/json
400 Error (invalid_parameter, unknown_parameter, invalid_id) application/json
429 Error (rate_limited) application/json
503 Error (busy, dataset_unavailable, draining) application/json

GET `/v3/ss/objects/{ref}`#

Solar-system object summary

auth anonymouscache no-store

The SS record plus observation counts per band and product, the orbit elements block, the resolved default selection and notes. Reads no photometry.

Also available as GET /v3/r/{serve_id}/ss/objects/{ref}, with the specified release (versioned URLs).

Parameters

Parameter	In	Type	Default	Description
`ref`required	path	string	—	Solar-system object reference: the decimal `object_id`, a slug (`20`, `2P`, `C_2020_F3`, `2019_AB1`, `id-<object_id>`), or any name, number, designation, packed designation or SPK id that resolves uniquely. An ambiguous name returns 300 with candidates. e.g. `20`

Responses

200 Object summary application/json
300 Error (ambiguous) application/json
400 Error (invalid_parameter, unknown_parameter, invalid_id) application/json
429 Error (rate_limited) application/json
503 Error (busy, dataset_unavailable, draining) application/json
404 Error (not_found) application/json

Example

Recorded response GET /v3/ss/objects/20

{
  "object_id": "5624785654134724447",
  "slug": "20",
  "name": "(20) Massalia",
  "kind": "asteroid",
  "number": 20,
  "designation": null,
  "packed": ["00020"],
  "orbit_class": "Inner main belt",
  "H": 6.54,
  "n_obs": 10027,
  "n_obs_g": 8095,
  "n_obs_V": 1932,
  "n_good_g": 2729,
  "n_good_V": 674,
  "n_good_conv": 3424,
  "n_good": 3424,
  "median_mag_g": 11.274,
  "brightest_mag_g": 9.141,
  "brightest_pred_mag": 8.531,
  "first_jd": 2456438.11812,
  "last_jd": 2461276.47466,
  "first_good_jd": 2456443.10236,
  "last_good_jd": 2461260.2397,
  "observations": {"g": {"red": 4425, "conv": 3670}, "V": {"red": 1006, "conv": 926}},
  "good": {"g": {"red": 2729, "conv": 2743}, "V": {"red": 674, "conv": 681}},
  "orbit": {
    "epoch_tdb_jd": 2461200.5,
/* … 88 more lines */

GET `/v3/ss/objects/{ref}/lc`#

Solar-system light curve

auth anonymouscache no-store

Photometry decoded with the SS-D1 rules (data-ss.html). Rows are sorted by (jd, image number). The header carries the object record and orbit block, so a page needs only this one request. jd is the observed UTC mid-exposure time; the light-time-corrected emission time (TDB) is jd + djd_emission. The decile bits 8-12 are computed on the full curve, before the rows, exclude_quality and max_blend filters, so filtering never changes which rows carry them.

Also available as GET /v3/r/{serve_id}/ss/objects/{ref}/lc, with the specified release (versioned URLs).

Parameters

Parameter	In	Type	Default	Description
`ref`required	path	string	—	Solar-system object reference: the decimal `object_id`, a slug (`20`, `2P`, `C_2020_F3`, `2019_AB1`, `id-<object_id>`), or any name, number, designation, packed designation or SPK id that resolves uniquely. An ambiguous name returns 300 with candidates. e.g. `20`
`bands`	query	string	`g,V`	Comma list of `g` and `V`.
`product`	query	string one of `auto`, `red`, `conv`	`auto`	`red` = reduced-image photometry, `conv` = difference-image photometry, `auto` = conv when the object's median recommended conv g magnitude is fainter than 13.5 (or it has no recommended red detection), else red.
`aperture`	query	number one of `0.75`, `1`, `1.25`, `1.5`, `2`, `3` ≥ 0.75, ≤ 3	`2`	Aperture radius in pixels (8.0 arcsec/px).
`error_floor`	query	number ≥ 0, ≤ 1 \| string one of `camera`, `none`	`camera`	`camera` (per-camera, date-ranged systematic floor; median 0.0137 mag), `none`, or a number in mag.
`deciles`	query	string one of `object_camera`, `object_field_camera`, `none`	`object_camera`	Population used for the decile bits 8-12: per (object, camera), per (object, field, camera), or no decile bits. Computed on the full curve before the row filters.
`max_blend`	query	number ≥ 0, ≤ 1000 \| string one of `none`	`0.05`	Largest \|blend_ratio\| a reduced-image row may have and still be recommended, or `none`.
`rows`	query	string one of `all`, `detected`, `recommended`	`all`	`all` every measurement, `detected` the > 5-sigma detections, `recommended` the rows that pass the recommended rule.
`exclude_quality`	query	integer ≥ 0, ≤ 65,535	`0`	Drop rows whose `quality` shares any bit with this mask (decimal or 0x hex). 0 keeps every row; the website's Recommended preset is 23 (0x17). See flags.html.
`cols`	query	string one of `web`, `full`	`web`	Column set.
`format`	query	string one of `sp3c`, `json`, `csv`, `ecsv`, `arrow`, `parquet`	`sp3c`	Response format. `sp3c` is the compact binary columnar format used by the website; the others carry the same values (text floats use the shortest round-trip decimal). Text and Parquet responses set `Content-Disposition`.

Responses

200 The light curve. n = 0 when the object has no photometry. application/vnd.asassn.sp3c, application/json, text/csv, text/x-ecsv, application/vnd.apache.arrow.stream, application/vnd.apache.parquet
304 Not modified (If-None-Match matched the ETag).
400 Error (invalid_parameter, unknown_parameter, invalid_id) application/json
429 Error (rate_limited) application/json
503 Error (busy, dataset_unavailable, draining) application/json
404 Error (not_found, release_not_served) application/json
413 Error (response_too_large) application/json
300 Error (ambiguous) application/json

GET `/v3/ss/objects/{ref}/orbit`#

Orbit polyline

auth anonymouscache no-store

Two-body orbit sampled at n points (heliocentric ecliptic J2000, AU, rounded to 1e-5). The website computes orbits in the browser from the elements block instead.

Also available as GET /v3/r/{serve_id}/ss/objects/{ref}/orbit, with the specified release (versioned URLs).

Parameters

Parameter	In	Type	Default	Description
`ref`required	path	string	—	Solar-system object reference: the decimal `object_id`, a slug (`20`, `2P`, `C_2020_F3`, `2019_AB1`, `id-<object_id>`), or any name, number, designation, packed designation or SPK id that resolves uniquely. An ambiguous name returns 300 with candidates. e.g. `20`
`n`	query	integer ≥ 2, ≤ 3601	`361`	Number of points.

Responses

200 {object, elements, orbit_xyz, frame} application/json
300 Error (ambiguous) application/json
400 Error (invalid_parameter, unknown_parameter, invalid_id) application/json
429 Error (rate_limited) application/json
503 Error (busy, dataset_unavailable, draining) application/json
404 Error (not_found) application/json

GET `/v3/ss/top-names.json`#

Top 5,000 names for instant autocomplete

auth anonymouscache no-store

Static file: [object_id, slug, name, kind, number, n_good] rows ranked by recommended detections.

Also available as GET /v3/r/{serve_id}/ss/top-names.json, with the specified release (versioned URLs).

Responses

200 Name list application/json

Bulk#

POST `/v3/stars/lc`#

Batch of star light curves (stream)

auth anonymous ≤ 3 ids; token ≤ 100cache no-store

Reads the stars in storage order and returns them in request order as an SP3F stream (one SP3C item per star, error items for failures, and a trailer). A stream without a trailer is incomplete.

Request body `application/json`

selection keys as the GET /lc parameters

Field	Type	Default	Description
`ids`required	array ≤ 100 items	—	At most 3 anonymously and 100 with a token.
`format`	string one of `sp3f`	—

Responses

200 SP3F stream application/vnd.asassn.sp3f
400 Error (invalid_json, invalid_parameter) application/json
413 Error (too_many_ids) application/json
429 Error (rate_limited) application/json

POST `/v3/ss/lc`#

Batch of solar-system light curves (stream)

auth anonymous ≤ 3 refs; token ≤ 100cache no-store

As POST /v3/stars/lc, with refs (object ids, slugs or names) and the SS parameters.

Request body `application/json`

selection keys as the GET /lc parameters

Field	Type	Default	Description
`refs`required	array ≤ 100 items	—	At most 3 anonymously and 100 with a token.
`format`	string one of `sp3f`	—

Responses

200 SP3F stream application/vnd.asassn.sp3f
400 Error (invalid_json, invalid_parameter) application/json
413 Error (too_many_ids) application/json
429 Error (rate_limited) application/json

Jobs#

POST `/v3/jobs` Coming soon#

Submit a bulk job

Coming soon: not available during the betaauth tokencache no-store

Queues a job that writes Parquet (or CSV) part files of at most 1 GB plus MANIFEST.json. One running job per token; files expire after 72 h.

Request body `application/json`

Plus the light-curve parameters of the dataset.

Field	Type	Default
`dataset`required	string one of `stars`, `ss`	—
`ids`	array of integer	—
`refs`	array of string	—
`format`	string one of `parquet`, `csv`	`parquet`

Responses

202 {job_id, status_url} application/json
401 Error (unauthorized) application/json
403 Error (forbidden) application/json
413 Error (too_many_ids) application/json
429 Error (rate_limited) application/json

GET `/v3/jobs/{id}` Coming soon#

Job status

Coming soon: not available during the betaauth tokencache no-store

queued, running, done, failed or expired, with progress and the output files (name, bytes, sha256, url).

Parameters

Parameter	In	Type	Default	Description
`id`required	path	string `^[A-Za-z0-9_-]{1,64}$`	—	Job id.

Responses

200 Job application/json
401 Error (unauthorized) application/json
404 Error (not_found) application/json

DELETE `/v3/jobs/{id}` Coming soon#

Cancel a job or delete its files

Coming soon: not available during the betaauth tokencache no-store

Parameters

Parameter	In	Type	Default	Description
`id`required	path	string `^[A-Za-z0-9_-]{1,64}$`	—	Job id.

Responses

200 Deleted
401 Error (unauthorized) application/json
404 Error (not_found) application/json

GET `/v3/jobs/{id}/files/{name}` Coming soon#

Download a job output file

Coming soon: not available during the betaauth tokencache no-store

Served with HTTP Range support, so interrupted downloads resume. Check each file against the sha256 in the job status.

Parameters

Parameter	In	Type	Default	Description
`id`required	path	string `^[A-Za-z0-9_-]{1,64}$`	—	Job id.
`name`required	path	string `^[A-Za-z0-9_.-]{1,128}$`	—	File name from the job status.

Responses

200 File bytes
206 Partial content
401 Error (unauthorized) application/json
404 Error (not_found) application/json

Legacy (rc1 client)#

POST `/v3/cone` Coming soon#

rc1 cone search

Coming soon: not available during the betaauth anonymouscache no-store

Body {ra, dec, radius_arcsec, limit}; response {release_id, stars, truncated} exactly as the rc1 skypatrol3 server returned it.

Request body `application/json`

Field	Type	Default
`ra`required	number	—
`dec`required	number	—
`radius_arcsec`required	number	—
`limit`	integer	—

Responses

200 rc1 cone result application/json
400 Error (invalid_json, invalid_parameter) application/json
409 Error (release_mismatch) application/json

POST `/v3/query` Coming soon#

rc1 native packet stream

Coming soon: not available during the betaauth tokencache no-store

rc1 validate_query semantics and the SP3\x01 frame protocol, for existing skypatrol3.Client users.

Request body `application/json`

Responses

200 SP3\x01 frames
401 Error (unauthorized) application/json
409 Error (release_mismatch) application/json
413 Error (query_too_large) application/json

The rc1 Python client#

The earlier skypatrol3 client (0.3.0rc1) talks to V3 through its own endpoints. /v3/health, /v3/release and /v3/status keep their rc1 keys, so the client can connect and read the release. Its cone search (POST /v3/cone) and light-curve stream (POST /v3/query) are Coming soon. New code should use the GET endpoints above.

HTTP API reference

Basics#

Launch status#

Identifiers#

Gaia lookups#

Versioned URLs and serve_id#

Formats#

Response headers#

Caching#

Rate limits and accounts

Access tokens

Errors#

Endpoints#

Meta#

GET /v3/health#

Responses

GET /v3/release#

Responses

Example

GET /v3/status#

Responses

Example

GET /v3/flags#

Responses

Resolution#

GET /v3/resolve#

Parameters

Responses

Example

Stars#

GET /v3/stars/cone#

Parameters

Responses

Example

GET /v3/stars/{ref}#

Parameters

Responses

GET /v3/stars/{ref}/lc#

Parameters

Responses

GET /v3/stars/gaia/{release}/{source_id}#

Parameters

Responses

POST /v3/stars/gaia/{release}#

Parameters

Request body application/json

Responses

Solar system#

GET /v3/ss/suggest#

Parameters

Responses

Example

GET /v3/ss/resolve#

Parameters

Responses

GET /v3/ss/objects/{ref}#

Parameters

Responses

Example

GET /v3/ss/objects/{ref}/lc#

Parameters

Responses

GET /v3/ss/objects/{ref}/orbit#

Parameters

Responses

GET /v3/ss/top-names.json#

Responses

Bulk#

POST /v3/stars/lc#

Request body application/json

Responses

POST /v3/ss/lc#

Request body application/json

Responses

Jobs#

POST /v3/jobs Coming soon#

Request body application/json

Responses

GET /v3/jobs/{id} Coming soon#

Parameters

Versioned URLs and `serve_id`#

GET `/v3/health`#

GET `/v3/release`#

GET `/v3/status`#

GET `/v3/flags`#

GET `/v3/resolve`#

GET `/v3/stars/cone`#

GET `/v3/stars/{ref}`#

GET `/v3/stars/{ref}/lc`#

GET `/v3/stars/gaia/{release}/{source_id}`#

POST `/v3/stars/gaia/{release}`#

Request body `application/json`

GET `/v3/ss/suggest`#

GET `/v3/ss/resolve`#

GET `/v3/ss/objects/{ref}`#

GET `/v3/ss/objects/{ref}/lc`#

GET `/v3/ss/objects/{ref}/orbit`#

GET `/v3/ss/top-names.json`#

POST `/v3/stars/lc`#

Request body `application/json`

POST `/v3/ss/lc`#

Request body `application/json`

POST `/v3/jobs` Coming soon#

Request body `application/json`

GET `/v3/jobs/{id}` Coming soon#

DELETE `/v3/jobs/{id}` Coming soon#

GET `/v3/jobs/{id}/files/{name}` Coming soon#

POST `/v3/cone` Coming soon#

Request body `application/json`

POST `/v3/query` Coming soon#

Request body `application/json`