Skip to main content
For the complete documentation index, see llms.txt.
Every VALAR API endpoint that acts on a spacecraft identifies it by its VALAR id — a UUID assigned when the spacecraft is created. This page explains how to find that id from an identifier you already hold — a NORAD number, a COSPAR designator, a name, or your own external key — how to reference a spacecraft once you have its id, and the two errors you meet when a reference is wrong.

​
Finding a spacecraft

To resolve an identifier to a spacecraft id, call GET /operations/spacecraft with one or more lookup filters. Each filter matches a single spacecraft attribute, and the endpoint returns the spacecraft that match every filter you supply. The filters combine with AND — supplying more than one narrows the result to spacecraft that match all of them at once. Supplying none returns your full spacecraft list. name is the only case-insensitive filter; noradId, cosparId, and externalKey are case-sensitive exact matches. For example, to resolve the NORAD id 25544 to a spacecraft:
The response is your standard paginated spacecraft list, filtered to the matches. Read the id of the returned spacecraft and use it for every subsequent call.

​
Resolve once, then reference by id

A lookup gives you the spacecraft’s id — a UUID. Use that id for every other call that targets the spacecraft: fetching it, importing state vectors, planning maneuvers, and so on. Resolve once and reuse the id; you do not repeat the lookup on every request.

​
Path parameters accept only a UUID

Wherever an endpoint names a spacecraft id in its path — for example GET /operations/spacecraft/{id} — that path parameter accepts only a VALAR UUID. Supplying a NORAD id, a COSPAR id, or a spacecraft name in that position is a malformed request and returns 400, not 404:
A non-UUID in a spacecraft-id path is a 400 (a malformed request), not a 404 (a missing resource). If you hold a NORAD id, COSPAR id, name, or external key, resolve it to the id with the lookup above first, then call the id-keyed endpoint.

​
When a reference cannot be resolved

When you supply a spacecraft reference that VALAR cannot resolve to a spacecraft in your organization, the endpoint returns a uniform 404 body with three fixed fields:
The status is always 404, the error code is always SC-4040, and the message echoes back the reference you supplied — and nothing else.
A reference that names a spacecraft in another organization returns exactly the same 404 as a reference that names nothing at all. The two are indistinguishable by design: VALAR never confirms the existence of anything outside your organization, so the response cannot be used to probe another organization’s fleet.

​
Operations versus multi-spacecraft reads

The 404 above is how a single-spacecraft operation reports an unresolvable reference — the whole request fails. A multi-spacecraft read handles the same condition differently: rather than failing, it returns 200 and names each unresolvable reference in an unresolvedSpacecraftReferences array, returning the results for the references that did resolve. Same underlying condition, deliberately different contract. For the multi-spacecraft read behavior, see State Vectors and Viewing Measurements.
  • Spacecraft: Manage your fleet and assign the external key you can look a spacecraft up by.
  • State Vectors: Read orbit solutions, including the unresolved-reference report on multi-spacecraft requests.
  • Viewing Measurements: Read measurement data, including the unresolved-reference report on multi-spacecraft requests.
  • API Keys: Create the keys that authenticate these API requests.