> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valar.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Spacecraft Lookup

> Find a spacecraft by NORAD, COSPAR, name, or external key, then reference it by id everywhere else in the API

> For the complete documentation index, see [llms.txt](/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.

| Filter            | Matches                                                                           | Matching rule                                                                   |
| ----------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **`noradId`**     | The spacecraft's NORAD catalog number                                             | Exact string match. Not numerically normalised — leading zeros are significant. |
| **`cosparId`**    | The COSPAR international designator                                               | Exact string match.                                                             |
| **`name`**        | The spacecraft's display name                                                     | Exact match, but **case-insensitive**.                                          |
| **`externalKey`** | Your caller-assigned [external key](/features/spacecraft-management#external-key) | Exact string match.                                                             |

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:

```
GET /operations/spacecraft?noradId=25544
```

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:

```json theme={null}
{
  "status": 400,
  "error": "VALIDATION_ERROR",
  "message": "Invalid spacecraft ID format"
}
```

<Note>
  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](#finding-a-spacecraft) above first, then call the id-keyed endpoint.
</Note>

## 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:

```json theme={null}
{
  "status": 404,
  "error": "SC-4040",
  "message": "Spacecraft with identifier 'PARTNER-SAT-001' not found"
}
```

The `status` is always `404`, the `error` code is always `SC-4040`, and the `message` echoes back the reference you supplied — and nothing else.

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

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

| Request kind                                                                                | An unresolvable reference produces                                                                             |
| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Single-spacecraft operation** (for example `GET /operations/spacecraft/{id}`)             | **404** with the uniform body above — the request fails                                                        |
| **Multi-spacecraft read** (`GET /operations/state-vectors`, `GET /operations/measurements`) | **200** — the reference is named in `unresolvedSpacecraftReferences`, and the rest of the results are returned |

Same underlying condition, deliberately different contract. For the multi-spacecraft read behavior, see [State Vectors](/features/state-vectors#unresolved-spacecraft-references) and [Viewing Measurements](/features/measurements-data#unresolved-spacecraft-references).

## Related Pages

* [Spacecraft](/features/spacecraft-management): Manage your fleet and assign the external key you can look a spacecraft up by.
* [State Vectors](/features/state-vectors): Read orbit solutions, including the unresolved-reference report on multi-spacecraft requests.
* [Viewing Measurements](/features/measurements-data): Read measurement data, including the unresolved-reference report on multi-spacecraft requests.
* [API Keys](/features/api-keys): Create the keys that authenticate these API requests.