# impartire API — Reference: Spec profiles

Every path is under `https://impartire.com/api/v1`. The machine-readable contract is https://impartire.com/api/v1/openapi.json (OpenAPI 3.1).

#### GET /api/v1/spec-profiles

List the spec profiles the org may read

Every technical delivery spec revision your org may read: its own, those another org published to it, and those its requirements pin. Who a spec is published to is not shown. For an OAuth token, its person needs the read-delivery permission (no platform-admin bypass); a key reads the whole org. 404 when the org does not have delivery, and for an OAuth token whose person may not read it.

Scopes: `delivery:read`

Parameters:

- `updated_after` (query, string (date-time)) — Only specs changed strictly after this instant (ISO 8601 with offset), compared to the millisecond.
- `sort` (query, "name" | "-updated_at" | "updated_at") — Sort key; a leading `-` is descending. Default `name`. Ties break on id.
- `limit` (query, integer) — Page size, default 50. Values above 100 are treated as 100.
- `cursor` (query, string) — next_cursor from the previous page, with the other parameters unchanged.

Response 200 — `SpecProfileList`

- `data` (array of SpecProfile, required) — In the requested sort (default `name`), ties broken by id.
  - `id` (string (uuid), required)
  - `name` (string, required)
  - `revision` (integer, required)
  - `owner_org` (object, required) — The org that wrote the spec.
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `mine` (boolean, required) — True when your org owns it.
  - `status` ("private" | "published" | "retired", required) — `private` — the owner's own, editable; `published` — offered to suppliers, immutable (it changes by a new revision); `retired` — still readable, no longer accepted for new requirements.
  - `supersedes_id` (string (uuid) or null, required) — The revision this one replaced.
  - `superseded_by_id` (string (uuid) or null, required) — The revision that replaced this one, when you can read it.
  - `effective_from` (string (date-time) or null, required)
  - `accepts_until` (string (date-time) or null, required) — After this instant the spec is no longer accepted for new requirements.
  - `frame_rate` (string, required)
  - `drop_frame` (boolean, required)
  - `resolution` (string or null, required)
  - `aspect_ratio` (string or null, required)
  - `audio_config` (string or null, required)
  - `color_space` (string or null, required)
  - `hdr` (string or null, required)
  - `closed_captions` (boolean or null, required)
  - `description` (string or null, required)
  - `created_at` (string (date-time), required)
  - `updated_at` (string (date-time), required)
- `next_cursor` (string or null, required) — Pass as `cursor` to get the next page; null means this is the last page.

Other responses:

- 401 (Problem) — unauthenticated — no key, or an unknown, revoked or expired one.
- 403 (Problem) — insufficient-scope — the key lacks a required scope.
- 404 (Problem) — not-found.
- 422 (Problem) — validation — a bad filter, `sort`, `limit` or `cursor` (`errors[].path` names it).
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.

#### GET /api/v1/spec-profiles/{id}

Get one spec profile

One spec revision, in the list's shape; 404 for one your org may not read. 404 when the org does not have delivery, and for an OAuth token whose person may not read it.

Scopes: `delivery:read`

Parameters:

- `id` (path, string (uuid), required) — The spec profile revision's id, from GET /api/v1/spec-profiles.
- `If-None-Match` (header, string) — An ETag from a previous response; 304 if unchanged.

Response 200 — `SpecProfile`: A technical delivery spec your org may read: its own, one another org published to it, or one a requirement of yours pins.

- `id` (string (uuid), required)
- `name` (string, required)
- `revision` (integer, required)
- `owner_org` (object, required) — The org that wrote the spec.
  - `id` (string (uuid), required)
  - `name` (string, required)
- `mine` (boolean, required) — True when your org owns it.
- `status` ("private" | "published" | "retired", required) — `private` — the owner's own, editable; `published` — offered to suppliers, immutable (it changes by a new revision); `retired` — still readable, no longer accepted for new requirements.
- `supersedes_id` (string (uuid) or null, required) — The revision this one replaced.
- `superseded_by_id` (string (uuid) or null, required) — The revision that replaced this one, when you can read it.
- `effective_from` (string (date-time) or null, required)
- `accepts_until` (string (date-time) or null, required) — After this instant the spec is no longer accepted for new requirements.
- `frame_rate` (string, required)
- `drop_frame` (boolean, required)
- `resolution` (string or null, required)
- `aspect_ratio` (string or null, required)
- `audio_config` (string or null, required)
- `color_space` (string or null, required)
- `hdr` (string or null, required)
- `closed_captions` (boolean or null, required)
- `description` (string or null, required)
- `created_at` (string (date-time), required)
- `updated_at` (string (date-time), required)

Other responses:

- 304 — Not modified — the ETag in If-None-Match is current.
- 401 (Problem) — unauthenticated — no key, or an unknown, revoked or expired one.
- 403 (Problem) — insufficient-scope — the key lacks a required scope.
- 404 (Problem) — not-found.
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.