# impartire API — Reference: EPG formats

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/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_after` (query, string (date-time)) — Only formats changed strictly after this instant (ISO 8601 with offset), compared to the millisecond.
- `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 — `FormatList`

- `data` (array of Format, required) — By name, then id.
  - `id` (string (uuid), required)
  - `name` (string, required)
  - `description` (string or null, required)
  - `elements` (array of FormatElement, required) — 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_ms` (integer, required) — How long the element runs, in milliseconds.
  - `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 `updated_after`, `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/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:

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

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

- `id` (string (uuid), required)
- `name` (string, required)
- `description` (string or null, required)
- `elements` (array of FormatElement, required) — 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_ms` (integer, required) — How long the element runs, in milliseconds.
- `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.