API reference

EPG services

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

List the org's broadcast services

The org's linear broadcast services (EPG channels) — each with its transmission spec, its fallback format and the formats bound to it — by sort_order, as the app lists them. Returned whole, at most 1000. 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 services changed strictly after this instant (ISO 8601 with offset), compared to the millisecond. A format binding added or removed does not change a service's updated_at; its ETag moves.

Response 200ServiceList

dataarray of Servicerequired
By sort_order, then creation, as the app lists them. Returned whole, at most 1000.
- idstring (uuid)required
- namestringrequired
- descriptionstring or nullrequired
- numberinteger or nullrequired
  The channel number viewers know it by, when it has one.
- colorstringrequired
  The colour the app shows the service in (a CSS hex colour).
- sort_orderintegerrequired
  Its place in the app's list of services (ascending).
- spec_profileSpecProfileRef or nullrequired
  The transmission spec its programmes are judged against (GET /api/v1/spec-profiles/{id}); null when none is set.
  - idstring (uuid)required
  - namestringrequired
  - revisionintegerrequired
    The spec's revision: a published spec changes only by a new revision, which supersedes this one.
- default_formatobject or nullrequired
  The fallback clock (GET /api/v1/formats/{id}) for a day no bound format covers; null when none is set.
  - idstring (uuid)required
  - namestringrequired
- formatsarray of objectrequired
  The formats bound to the service, each with the days it applies, by starts_on (unbounded first), then format name.
  - formatobjectrequired
    A clock the service may use (GET /api/v1/formats/{id}).
    - idstring (uuid)required
    - namestringrequired
  - starts_onstring (date) or nullrequired
    The first broadcast day it applies (YYYY-MM-DD); null — no start bound.
  - ends_onstring (date) or nullrequired
    The last broadcast day it applies (YYYY-MM-DD); null — no end bound.
- created_atstring (date-time)required
- updated_atstring (date-time)required
next_cursorstring or nullrequired
Always null: the list is returned whole.

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.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

GET/api/v1/services/{id}

Get one broadcast service

One service, 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 service's id, from GET /api/v1/services.
If-None-Matchheader · string
An ETag from a previous response; 304 if unchanged.

Response 200Service

A linear broadcast service (an EPG channel): its brand, transmission spec and the clocks its schedule is built on.

idstring (uuid)required
namestringrequired
descriptionstring or nullrequired
numberinteger or nullrequired
The channel number viewers know it by, when it has one.
colorstringrequired
The colour the app shows the service in (a CSS hex colour).
sort_orderintegerrequired
Its place in the app's list of services (ascending).
spec_profileSpecProfileRef or nullrequired
The transmission spec its programmes are judged against (GET /api/v1/spec-profiles/{id}); null when none is set.
- idstring (uuid)required
- namestringrequired
- revisionintegerrequired
  The spec's revision: a published spec changes only by a new revision, which supersedes this one.
default_formatobject or nullrequired
The fallback clock (GET /api/v1/formats/{id}) for a day no bound format covers; null when none is set.
- idstring (uuid)required
- namestringrequired
formatsarray of objectrequired
The formats bound to the service, each with the days it applies, by starts_on (unbounded first), then format name.
- formatobjectrequired
  A clock the service may use (GET /api/v1/formats/{id}).
  - idstring (uuid)required
  - namestringrequired
- starts_onstring (date) or nullrequired
  The first broadcast day it applies (YYYY-MM-DD); null — no start bound.
- ends_onstring (date) or nullrequired
  The last broadcast day it applies (YYYY-MM-DD); null — no end bound.
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.