API reference

Spec profiles

Every path is under https://impartire.com/api/v1. Generated from the API’s own contract, openapi.json (OpenAPI 3.1), which you can load into any OpenAPI tool. Errors are Problems — see Conventions.

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_afterquery · string (date-time)
Only specs changed strictly after this instant (ISO 8601 with offset), compared to the millisecond.
sortquery · "name" | "-updated_at" | "updated_at"
Sort key; a leading - is descending. Default name. Ties break on id.
limitquery · integer
Page size, default 50. Values above 100 are treated as 100.
cursorquery · string
next_cursor from the previous page, with the other parameters unchanged.

Response 200SpecProfileList

dataarray of SpecProfilerequired
In the requested sort (default name), ties broken by id.
- idstring (uuid)required
- namestringrequired
- revisionintegerrequired
- owner_orgobjectrequired
  The org that wrote the spec.
  - idstring (uuid)required
  - namestringrequired
- minebooleanrequired
  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_idstring (uuid) or nullrequired
  The revision this one replaced.
- superseded_by_idstring (uuid) or nullrequired
  The revision that replaced this one, when you can read it.
- effective_fromstring (date-time) or nullrequired
- accepts_untilstring (date-time) or nullrequired
  After this instant the spec is no longer accepted for new requirements.
- frame_ratestringrequired
- drop_framebooleanrequired
- resolutionstring or nullrequired
- aspect_ratiostring or nullrequired
- audio_configstring or nullrequired
- color_spacestring or nullrequired
- hdrstring or nullrequired
- closed_captionsboolean or nullrequired
- descriptionstring or nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
next_cursorstring or nullrequired
Pass as cursor to get the next page; null means this is the last page.

Other responses

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

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

Response 200SpecProfile

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

idstring (uuid)required
namestringrequired
revisionintegerrequired
owner_orgobjectrequired
The org that wrote the spec.
- idstring (uuid)required
- namestringrequired
minebooleanrequired
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_idstring (uuid) or nullrequired
The revision this one replaced.
superseded_by_idstring (uuid) or nullrequired
The revision that replaced this one, when you can read it.
effective_fromstring (date-time) or nullrequired
accepts_untilstring (date-time) or nullrequired
After this instant the spec is no longer accepted for new requirements.
frame_ratestringrequired
drop_framebooleanrequired
resolutionstring or nullrequired
aspect_ratiostring or nullrequired
audio_configstring or nullrequired
color_spacestring or nullrequired
hdrstring or nullrequired
closed_captionsboolean or nullrequired
descriptionstring or nullrequired
created_atstring (date-time)required
updated_atstring (date-time)required

Other responses

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