API reference

EPG formats

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/formats

List the org's broadcast formats

The org's clocks — the structure of a programme slot as segments, breaks and IDs with their durations — by name. Poll with updated_after (exclusive, millisecond). For an OAuth token, its person needs membership of the org (no platform-admin bypass); a key reads the whole org. 404 when the org does not have the EPG, and for an OAuth token whose person is not a member of the org.

Scopes: epg:read

Parameters

updated_afterquery · string (date-time)
Only formats changed strictly after this instant (ISO 8601 with offset), compared to the millisecond.
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 200FormatList

dataarray of Formatrequired
By name, then id.
- idstring (uuid)required
- namestringrequired
- descriptionstring or nullrequired
- elementsarray of FormatElementrequired
  The clock, in running order, as stored: elements run back to back from a slot's start, and the slot's length is their sum. In the transmission log a slot's breaks and IDs are these elements offset from its start (cut at its end).
  - type"segment" | "break" | "noncommercial_break" | "id"required
    segment — programme content; break — a commercial break; noncommercial_break — a promo or PSA break; id — a station ID.
  - duration_msintegerrequired
    How long the element runs, in milliseconds.
- 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 updated_after, 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/formats/{id}

Get one broadcast format

One format, in the list's shape. 404 when the org does not have the EPG, and for an OAuth token whose person is not a member of the org.

Scopes: epg:read

Parameters

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

Response 200Format

A broadcast format (a clock): the structure of a programme slot — its segments, breaks and IDs.

idstring (uuid)required
namestringrequired
descriptionstring or nullrequired
elementsarray of FormatElementrequired
The clock, in running order, as stored: elements run back to back from a slot's start, and the slot's length is their sum. In the transmission log a slot's breaks and IDs are these elements offset from its start (cut at its end).
- type"segment" | "break" | "noncommercial_break" | "id"required
  segment — programme content; break — a commercial break; noncommercial_break — a promo or PSA break; id — a station ID.
- duration_msintegerrequired
  How long the element runs, in milliseconds.
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.