API reference

Playout channels

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

List the org's playout channels

The org's playout channels as the DAM stores them — mode, the service each airs, whether it records and where — by name. Never a stream key, an ingest key or a destination, for any credential. Not the live on-air state: reading never calls the playout engine; that status is served once the orchestration tier owns the channel's convergence loop. 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 playout, and for an OAuth token whose person is not a member of the org.

Scopes: channels:read

Parameters

updated_afterquery · string (date-time)
Only channels 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 200ChannelList

dataarray of Channelrequired
By name, then id.
- idstring (uuid)required
- namestringrequired
- mode"strict" | "relay"required
  strict — a scheduled playlist the playout engine plays out; relay — a live feed restreamed to platforms.
- serviceobject or nullrequired
  The broadcast service (EPG channel, GET /api/v1/services/{id}) the channel airs; null when none is linked.
  - idstring (uuid)required
  - namestringrequired
- recordingobject or nullrequired
  Whether the channel records, and where the recordings go; null when it does not record.
  - kind"live_input"required
    What is recorded: live_input — a relay channel's incoming live feed, kept as a lossless master and registered as an asset.
  - projectobject or nullrequired
    The project recordings are filed into; null when none is set or it is no longer a live project of the org (they file into the org's Unfiled project).
    - idstring (uuid)required
    - namestring or nullrequired
      Null — for an OAuth token — when its person may not read the project.
- 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/channels/{id}

Get one playout channel

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

Scopes: channels:read

Parameters

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

Response 200Channel

A playout channel's configuration as the DAM stores it — not its live on-air state, never a stream key or destination.

idstring (uuid)required
namestringrequired
mode"strict" | "relay"required
strict — a scheduled playlist the playout engine plays out; relay — a live feed restreamed to platforms.
serviceobject or nullrequired
The broadcast service (EPG channel, GET /api/v1/services/{id}) the channel airs; null when none is linked.
- idstring (uuid)required
- namestringrequired
recordingobject or nullrequired
Whether the channel records, and where the recordings go; null when it does not record.
- kind"live_input"required
  What is recorded: live_input — a relay channel's incoming live feed, kept as a lossless master and registered as an asset.
- projectobject or nullrequired
  The project recordings are filed into; null when none is set or it is no longer a live project of the org (they file into the org's Unfiled project).
  - idstring (uuid)required
  - namestring or nullrequired
    Null — for an OAuth token — when its person may not read the project.
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.

POST/api/v1/channels/{id}/start

Start a playout channel (guarded)

A guarded action (ADR 0081): it puts a service on air. The app's own start runs through the playout engine: the stored configuration is pushed, the channel started, then the on-air graphic's schedule pushed (a graphic that fails leaves the channel on air without it). Only a strict channel starts through the engine; a relay channel is 409. **An API key's start happens at once**: 200 with the Channel — as the DAM stores it: the answer carries no engine status (read the audit entry, or the app). **An OAuth token's does not**: 202 with a Confirmation naming the channel and the service; once its person confirms it in impartire it runs as them. Its person must be an org admin (the app's verb; no platform-admin bypass). Audited: a channel.started event with the engine's state after the call. 404 when the org does not have playout, and for an OAuth token whose person is not a member of the org.

Scopes: channels:control

Parameters

idpath · string (uuid)required
The channel's id, from GET /api/v1/channels.
Idempotency-Keyheader · string
Makes a retry safe: the same key and request within 24 hours replays the first response. 1–255 characters.

Response 200Channel

A playout channel's configuration as the DAM stores it — not its live on-air state, never a stream key or destination.

idstring (uuid)required
namestringrequired
mode"strict" | "relay"required
strict — a scheduled playlist the playout engine plays out; relay — a live feed restreamed to platforms.
serviceobject or nullrequired
The broadcast service (EPG channel, GET /api/v1/services/{id}) the channel airs; null when none is linked.
- idstring (uuid)required
- namestringrequired
recordingobject or nullrequired
Whether the channel records, and where the recordings go; null when it does not record.
- kind"live_input"required
  What is recorded: live_input — a relay channel's incoming live feed, kept as a lossless master and registered as an asset.
- projectobject or nullrequired
  The project recordings are filed into; null when none is set or it is no longer a live project of the org (they file into the org's Unfiled project).
  - idstring (uuid)required
  - namestring or nullrequired
    Null — for an OAuth token — when its person may not read the project.
created_atstring (date-time)required
updated_atstring (date-time)required

Response 202Confirmation

A guarded action an OAuth token asked for, waiting for its person to confirm it in impartire (ADR 0081). A guarded endpoint answers 202 with this and a Location; poll it until status is executed, declined or expired.

idstring (uuid)required
status"pending" | "confirmed" | "declined" | "expired" | "executed"required
pending: waiting for the person to confirm or decline it in impartire (at confirm_url). confirmed: they confirmed and the action is running — poll again. executed: it ran; result holds its answer, or problem why it failed. declined: they said no; it will never run. expired: nobody decided within 15 minutes; it will never run (GET /api/v1/confirmations/{id} answers 410 confirmation-expired instead of this body; the person still sees it in impartire).
actionstringrequired
The guarded action, e.g. run.signal.
resourceobjectrequired
- typestringrequired
  The kind of resource the action is on, e.g. run.
- idstring (uuid) or nullrequired
- namestringrequired
  The resource as the person was shown it when the action was asked for.
summarystringrequired
The action in words, as the person reads it on the confirmation page.
client_idstringrequired
The OAuth client that asked.
confirm_urlstringrequired
Where the person confirms or declines it. Show it to them; the API cannot confirm.
created_atstring (date-time)required
expires_atstring (date-time)required
15 minutes after it was asked for. A pending confirmation past it is expired.
decided_atstring (date-time) or nullrequired
When the person confirmed or declined it, or when it expired; null while pending.
resultanyrequired
When executed and the action succeeded: the action's answer (what the endpoint would have returned with a key). Null otherwise.
problemProblem or nullrequired
When executed and the action failed: the Problem it failed with. Null otherwise.
- typestringrequired
  A stable URL naming the problem: https://impartire.com/problems/<code>. Branch on this.
- titlestringrequired
- statusintegerrequired
- detailstringrequired
  What went wrong and what to do about it, written for the caller.
- instancestringrequired
  The request path.
- request_idstringrequired
  Also sent as the Request-Id header. Quote it when reporting a problem.
- errorsarray of object
  On 422 validation: one entry per invalid field.
  - pathstringrequired
    The field or parameter, as a dotted path.
  - messagestringrequired
- edit_seqinteger
  On 412 precondition-failed: the resource's current edit_seq.
- etagstring
  On 412 precondition-failed for a project, a collection, a playlist or a schedule slot: its current ETag.
- item_idstring
  On 409 already-member: the existing item's id (in the collection or playlist).
- schema_versioninteger
  On 409 type-changed: the asset type's current schema_version.
- confirmation_idstring
  On 409 confirmation-pending: the confirmation already waiting for its person (GET /api/v1/confirmations/{id}).
- confirm_urlstring
  On 409 confirmation-pending: where the person confirms or declines it, in impartire.

Other responses

401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope, or insufficient-permission — the token's person is not an org admin.
404 not-found.
409 conflict — a relay channel; confirmation-pending; or idempotency-in-flight.
422 idempotency-mismatch (an OAuth token may not send Idempotency-Key).
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.
502 playout-unavailable — the engine did not start the channel; nothing changed on air.

POST/api/v1/channels/{id}/stop

Stop a playout channel (guarded)

A guarded action (ADR 0081): it takes a service off air. The app's own stop runs through the playout engine. Only a strict channel stops through the engine; a relay channel is 409. **An API key's stop happens at once**: 200 with the Channel — as the DAM stores it: the answer carries no engine status (read the audit entry, or the app). **An OAuth token's does not**: 202 with a Confirmation naming the channel and the service; once its person confirms it in impartire it runs as them. Its person must be an org admin (the app's verb; no platform-admin bypass). Audited: a channel.stopped event with the engine's state after the call. 404 when the org does not have playout, and for an OAuth token whose person is not a member of the org.

Scopes: channels:control

Parameters

idpath · string (uuid)required
The channel's id, from GET /api/v1/channels.
Idempotency-Keyheader · string
Makes a retry safe: the same key and request within 24 hours replays the first response. 1–255 characters.

Response 200Channel

A playout channel's configuration as the DAM stores it — not its live on-air state, never a stream key or destination.

idstring (uuid)required
namestringrequired
mode"strict" | "relay"required
strict — a scheduled playlist the playout engine plays out; relay — a live feed restreamed to platforms.
serviceobject or nullrequired
The broadcast service (EPG channel, GET /api/v1/services/{id}) the channel airs; null when none is linked.
- idstring (uuid)required
- namestringrequired
recordingobject or nullrequired
Whether the channel records, and where the recordings go; null when it does not record.
- kind"live_input"required
  What is recorded: live_input — a relay channel's incoming live feed, kept as a lossless master and registered as an asset.
- projectobject or nullrequired
  The project recordings are filed into; null when none is set or it is no longer a live project of the org (they file into the org's Unfiled project).
  - idstring (uuid)required
  - namestring or nullrequired
    Null — for an OAuth token — when its person may not read the project.
created_atstring (date-time)required
updated_atstring (date-time)required

Response 202Confirmation

idstring (uuid)required
status"pending" | "confirmed" | "declined" | "expired" | "executed"required
pending: waiting for the person to confirm or decline it in impartire (at confirm_url). confirmed: they confirmed and the action is running — poll again. executed: it ran; result holds its answer, or problem why it failed. declined: they said no; it will never run. expired: nobody decided within 15 minutes; it will never run (GET /api/v1/confirmations/{id} answers 410 confirmation-expired instead of this body; the person still sees it in impartire).
actionstringrequired
The guarded action, e.g. run.signal.
resourceobjectrequired
- typestringrequired
  The kind of resource the action is on, e.g. run.
- idstring (uuid) or nullrequired
- namestringrequired
  The resource as the person was shown it when the action was asked for.
summarystringrequired
The action in words, as the person reads it on the confirmation page.
client_idstringrequired
The OAuth client that asked.
confirm_urlstringrequired
Where the person confirms or declines it. Show it to them; the API cannot confirm.
created_atstring (date-time)required
expires_atstring (date-time)required
15 minutes after it was asked for. A pending confirmation past it is expired.
decided_atstring (date-time) or nullrequired
When the person confirmed or declined it, or when it expired; null while pending.
resultanyrequired
When executed and the action succeeded: the action's answer (what the endpoint would have returned with a key). Null otherwise.
problemProblem or nullrequired
When executed and the action failed: the Problem it failed with. Null otherwise.
- typestringrequired
  A stable URL naming the problem: https://impartire.com/problems/<code>. Branch on this.
- titlestringrequired
- statusintegerrequired
- detailstringrequired
  What went wrong and what to do about it, written for the caller.
- instancestringrequired
  The request path.
- request_idstringrequired
  Also sent as the Request-Id header. Quote it when reporting a problem.
- errorsarray of object
  On 422 validation: one entry per invalid field.
  - pathstringrequired
    The field or parameter, as a dotted path.
  - messagestringrequired
- edit_seqinteger
  On 412 precondition-failed: the resource's current edit_seq.
- etagstring
  On 412 precondition-failed for a project, a collection, a playlist or a schedule slot: its current ETag.
- item_idstring
  On 409 already-member: the existing item's id (in the collection or playlist).
- schema_versioninteger
  On 409 type-changed: the asset type's current schema_version.
- confirmation_idstring
  On 409 confirmation-pending: the confirmation already waiting for its person (GET /api/v1/confirmations/{id}).
- confirm_urlstring
  On 409 confirmation-pending: where the person confirms or declines it, in impartire.

Other responses

401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope, or insufficient-permission — the token's person is not an org admin.
404 not-found.
409 conflict — a relay channel; confirmation-pending; or idempotency-in-flight.
422 idempotency-mismatch (an OAuth token may not send Idempotency-Key).
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.
502 playout-unavailable — the engine did not stop the channel; nothing changed on air.