---
title: "Colour Passport Endpoint"
method: POST
path: "/colour/passport"
---

# Colour Passport Endpoint

`POST /colour/passport`

## Request

- Base URL: `https://api.colourmemory.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.colourmemory.com/colour/passport`
- Auth: none declared

Canonical colour truth object. Accepts a single hex or a list of hexes.
For a single hex, returns one passport. For multiple hexes, returns a batch.

principal_archive/principal_name (single-hex mode only): "pick the
story" -- return a SPECIFIC named record's full passport data instead
of the ranking algorithm's own pick, restricted to that hex's real
exact-hex ties (see hex_collision/additional_matches on a prior
call). Not supported in batch (hexes) mode.

Batch mode accepts at most 20 unique valid hexes; more is refused with
400 TOO_MANY_UNIQUE_COLOURS rather than silently truncated.

Metering: one unit per unique colour returned, identical to
/colour/passports and identical for keyed and keyless callers. Keyless
callers draw on the plugin trial; the sections a single selection draws
ride that selection's charge (see _check_key_or_trial).

## Headers

- `x-api-key` string, nullable
- `origin` string, nullable

## Request body

- ColourPassportRequest
  - `hex` string, nullable
  - `hexes` unknown[], nullable
    - unknown
  - `n_archive` integer
  - `include_physics` boolean
  - `include_cultural` boolean
  - `principal_archive` string, nullable
  - `principal_name` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/colourmemory/apis/colour-memory-api.md) · [All operations](https://skmtc.dev/colourmemory/apis/colour-memory-api/llms.txt) · [OpenAPI document](https://skmtc.dev/colourmemory/apis/colour-memory-api/revisions/4ba028f64042?raw)