# impartire API — Reference: EPG services

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/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_after` (query, 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 200 — `ServiceList`

- `data` (array of Service, required) — By sort_order, then creation, as the app lists them. Returned whole, at most 1000.
  - `id` (string (uuid), required)
  - `name` (string, required)
  - `description` (string or null, required)
  - `number` (integer or null, required) — The channel number viewers know it by, when it has one.
  - `color` (string, required) — The colour the app shows the service in (a CSS hex colour).
  - `sort_order` (integer, required) — Its place in the app's list of services (ascending).
  - `spec_profile` (SpecProfileRef or null, required) — The transmission spec its programmes are judged against (GET /api/v1/spec-profiles/{id}); null when none is set.
    - `id` (string (uuid), required)
    - `name` (string, required)
    - `revision` (integer, required) — The spec's revision: a published spec changes only by a new revision, which supersedes this one.
  - `default_format` (object or null, required) — The fallback clock (GET /api/v1/formats/{id}) for a day no bound format covers; null when none is set.
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `formats` (array of object, required) — The formats bound to the service, each with the days it applies, by `starts_on` (unbounded first), then format name.
    - `format` (object, required) — A clock the service may use (GET /api/v1/formats/{id}).
      - `id` (string (uuid), required)
      - `name` (string, required)
    - `starts_on` (string (date) or null, required) — The first broadcast day it applies (YYYY-MM-DD); null — no start bound.
    - `ends_on` (string (date) or null, required) — The last broadcast day it applies (YYYY-MM-DD); null — no end bound.
  - `created_at` (string (date-time), required)
  - `updated_at` (string (date-time), required)
- `next_cursor` (string or null, required) — Always null: the list is returned whole.

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

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

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

- `id` (string (uuid), required)
- `name` (string, required)
- `description` (string or null, required)
- `number` (integer or null, required) — The channel number viewers know it by, when it has one.
- `color` (string, required) — The colour the app shows the service in (a CSS hex colour).
- `sort_order` (integer, required) — Its place in the app's list of services (ascending).
- `spec_profile` (SpecProfileRef or null, required) — The transmission spec its programmes are judged against (GET /api/v1/spec-profiles/{id}); null when none is set.
  - `id` (string (uuid), required)
  - `name` (string, required)
  - `revision` (integer, required) — The spec's revision: a published spec changes only by a new revision, which supersedes this one.
- `default_format` (object or null, required) — The fallback clock (GET /api/v1/formats/{id}) for a day no bound format covers; null when none is set.
  - `id` (string (uuid), required)
  - `name` (string, required)
- `formats` (array of object, required) — The formats bound to the service, each with the days it applies, by `starts_on` (unbounded first), then format name.
  - `format` (object, required) — A clock the service may use (GET /api/v1/formats/{id}).
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `starts_on` (string (date) or null, required) — The first broadcast day it applies (YYYY-MM-DD); null — no start bound.
  - `ends_on` (string (date) or null, required) — The last broadcast day it applies (YYYY-MM-DD); null — no end bound.
- `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.