API reference

Playlists

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

List a project's playlists

project_id is required: playlists are listed one project at a time. Ordered by name unless sort says otherwise. To poll for changes, pass updated_after with the newest updated_at you have seen and sort=-updated_at (or updated_at); updated_at moves when the name, description or target_count change, not when items do. A deleted playlist leaves the list. An OAuth token's person needs read on the project (a project they cannot open is a 422 like a missing one).

Scopes: projects:read

Parameters

project_idquery · string (uuid)required
Required: the project whose playlists to list (GET /api/v1/projects). Not its sub-projects.
updated_afterquery · string (date-time)
Only playlists changed strictly after this instant (ISO 8601 with offset), compared to the millisecond — pass the newest updated_at you have seen and that playlist is not returned again.
sortquery · "name" | "-name" | "updated_at" | "-updated_at"
Sort key; a leading - is descending. Default name. Ties break on id.
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 200PlaylistList

dataarray of Playlistrequired
- idstring (uuid)required
- projectProjectRefrequired
  The project the playlist belongs to — its permission parent: who may open the project may open the playlist, who may update the project may change it.
  - idstring (uuid)required
  - namestringrequired
- namestringrequired
- descriptionstring or nullrequired
- target_countinteger or nullrequired
  How many items the playlist is meant to hold (e.g. a season's episode count), or null. Advisory: nothing refuses an item past it.
- item_countintegerrequired
  How many items it holds (GET /playlists/{id}/items lists them).
- created_atstring (date-time)required
- updated_atstring (date-time)required
  When its name, description or target_count last changed. Adding, removing or reordering items does not move it (the ETag moves instead).
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 missing or unknown project_id, or a bad limit, updated_after, sort or cursor.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

POST/api/v1/playlists

Create a playlist in a project

A typed project's type must allow playlists (an untyped project always does); otherwise 422 project-type-disallows. An OAuth token's person needs update on the project.

Scopes: projects:write

Parameters

Idempotency-Keyheader · string
Makes a retry safe: the same key and request within 24 hours replays the first response. 1–255 characters.

Request bodyCreatePlaylistRequest

project_idstring (uuid)required
The project it belongs to (GET /api/v1/projects). A typed project's type must allow playlists.
namestringrequired
descriptionstring or null
target_countinteger or null
How many items it is meant to hold; advisory.

Response 201Playlist

An ordered, count-aware sequence of assets belonging to a project (e.g. a season's episodes).

idstring (uuid)required
projectProjectRefrequired
The project the playlist belongs to — its permission parent: who may open the project may open the playlist, who may update the project may change it.
- idstring (uuid)required
- namestringrequired
namestringrequired
descriptionstring or nullrequired
target_countinteger or nullrequired
How many items the playlist is meant to hold (e.g. a season's episode count), or null. Advisory: nothing refuses an item past it.
item_countintegerrequired
How many items it holds (GET /playlists/{id}/items lists them).
created_atstring (date-time)required
updated_atstring (date-time)required
When its name, description or target_count last changed. Adding, removing or reordering items does not move it (the ETag moves instead).

Other responses

401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope, or insufficient-permission — an OAuth token's person may open the project but not update it.
404 not-found.
409 idempotency-in-flight.
422 project-type-disallows, validation (project_id, name, description, target_count), or idempotency-mismatch.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

GET/api/v1/playlists/{id}

Get one playlist

Scopes: projects:read

Parameters

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

Response 200Playlist

An ordered, count-aware sequence of assets belonging to a project (e.g. a season's episodes).

idstring (uuid)required
projectProjectRefrequired
The project the playlist belongs to — its permission parent: who may open the project may open the playlist, who may update the project may change it.
- idstring (uuid)required
- namestringrequired
namestringrequired
descriptionstring or nullrequired
target_countinteger or nullrequired
How many items the playlist is meant to hold (e.g. a season's episode count), or null. Advisory: nothing refuses an item past it.
item_countintegerrequired
How many items it holds (GET /playlists/{id}/items lists them).
created_atstring (date-time)required
updated_atstring (date-time)required
When its name, description or target_count last changed. Adding, removing or reordering items does not move it (the ETag moves instead).

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.

PATCH/api/v1/playlists/{id}

Rename or describe a playlist, or change its target count

If-Match is required: send the ETag from the last GET (or from the create). An unknown field is a 422; moving a playlist to another project is not in v1. An OAuth token's person needs update on the playlist's project.

Scopes: projects:write

Parameters

idpath · string (uuid)required
The playlist's id, from GET /api/v1/playlists?project_id=.
If-Matchheader · stringrequired
The playlist's ETag.

Request bodyUpdatePlaylistRequest

At least one of name, description, target_count. Moving a playlist to another project is not in v1; an unknown field is a 422.

namestring
descriptionstring or null
null clears it.
target_countinteger or null
null clears it.

Response 200Playlist

An ordered, count-aware sequence of assets belonging to a project (e.g. a season's episodes).

idstring (uuid)required
projectProjectRefrequired
The project the playlist belongs to — its permission parent: who may open the project may open the playlist, who may update the project may change it.
- idstring (uuid)required
- namestringrequired
namestringrequired
descriptionstring or nullrequired
target_countinteger or nullrequired
How many items the playlist is meant to hold (e.g. a season's episode count), or null. Advisory: nothing refuses an item past it.
item_countintegerrequired
How many items it holds (GET /playlists/{id}/items lists them).
created_atstring (date-time)required
updated_atstring (date-time)required
When its name, description or target_count last changed. Adding, removing or reordering items does not move it (the ETag moves instead).

Other responses

401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope, or insufficient-permission — an OAuth token's person may open the project but not update it.
404 not-found.
412 precondition-failed — If-Match is stale; etag in the body is the current one.
422 validation (empty body, an unknown field, name, description, target_count).
428 precondition-required — no If-Match.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

DELETE/api/v1/playlists/{id}

Delete a playlist

Soft-deletes the playlist; it no longer appears in reads or lists. Its assets are untouched. No If-Match: a second DELETE is a 404. An OAuth token's person needs update on the playlist's project.

Scopes: projects:write

Parameters

idpath · string (uuid)required
The playlist's id, from GET /api/v1/playlists?project_id=.

Other responses

204 Deleted.
401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope, or insufficient-permission — an OAuth token's person may open the project but not update it.
404 not-found.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

GET/api/v1/playlists/{id}/items

List a playlist's items in order

Ordered by sort_order, then by when each was added. Paginated: the list is bounded by the playlist, a page at a time. Each item names its asset's current version. For an OAuth token, an item whose asset its person may not read keeps its place and id but is restricted with asset: null.

Scopes: projects:read

Parameters

idpath · string (uuid)required
The playlist's id, from GET /api/v1/playlists?project_id=.
limitquery · integer
Page size, default 50. Values above 100 are treated as 100.
cursorquery · string
next_cursor from the previous page.

Response 200PlaylistItemList

dataarray of PlaylistItemrequired
- idstring (uuid)required
  The item's id — what DELETE …/items/{item_id} and PUT …/items/order take.
- assetobject or nullrequired
  The asset (its current version). Null when restricted.
  - idstring (uuid)required
  - namestringrequired
  - typeobjectrequired
    - idstring (uuid)required
    - namestringrequired
- restrictedbooleanrequired
  True for an OAuth token whose person may not read the asset (a playlist in an open project may hold material from a private one): the item keeps its place and id but not the asset's identity. Always false for an API key.
- sort_orderintegerrequired
  The item's place in the list; items are listed by it, ascending.
- positioninteger or nullrequired
  An optional editorial slot number (e.g. episode 3), independent of the list order.
- added_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 limit or cursor.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

POST/api/v1/playlists/{id}/items

Append an asset to a playlist

Pins the asset's current version and appends it after the last item; position is an optional editorial slot number, independent of the order. An asset already in the playlist (any version of it) is 409 already-member. An OAuth token's person needs update on the playlist's project and read on the asset.

Scopes: projects:write

Parameters

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

Request bodyAddPlaylistItemRequest

asset_idstring (uuid)required
The asset to add (its current version's id or its root id; the item pins the current version). GET /api/v1/assets lists them.
positioninteger or null
An editorial slot number (e.g. episode 3). The item is appended to the list whatever its position.

Response 201PlaylistItem

One item of a playlist: an asset at a place in the list.

idstring (uuid)required
The item's id — what DELETE …/items/{item_id} and PUT …/items/order take.
assetobject or nullrequired
The asset (its current version). Null when restricted.
- idstring (uuid)required
- namestringrequired
- typeobjectrequired
  - idstring (uuid)required
  - namestringrequired
restrictedbooleanrequired
True for an OAuth token whose person may not read the asset (a playlist in an open project may hold material from a private one): the item keeps its place and id but not the asset's identity. Always false for an API key.
sort_orderintegerrequired
The item's place in the list; items are listed by it, ascending.
positioninteger or nullrequired
An optional editorial slot number (e.g. episode 3), independent of the list order.
added_atstring (date-time)required

Other responses

401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope, or insufficient-permission — an OAuth token's person may open the project but not update it.
404 not-found.
409 already-member — the asset is already in the playlist (item_id in the body); or idempotency-in-flight.
422 unknown-asset, validation (asset_id, position), or idempotency-mismatch.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

DELETE/api/v1/playlists/{id}/items/{item_id}

Remove an item from a playlist

The asset itself is untouched; the other items keep their sort_order. A second DELETE is a 404. An OAuth token's person needs update on the playlist's project.

Scopes: projects:write

Parameters

idpath · string (uuid)required
The playlist's id, from GET /api/v1/playlists?project_id=.
item_idpath · string (uuid)required
The item's id, from GET /api/v1/playlists/{id}/items.

Other responses

204 Removed.
401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope, or insufficient-permission — an OAuth token's person may open the project but not update it.
404 not-found.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

PUT/api/v1/playlists/{id}/items/order

Put a playlist's items in a new order

item_ids is every item of the playlist, each exactly once, in the new order; their sort_order becomes 0, 1, 2… (position is untouched). Anything else (a missing, repeated or foreign id) is a 422. A playlist of more than 1000 items is reordered in the app. Answers the whole list after. If an item was added or removed meanwhile, nothing moves and the answer is 409 conflict: read the items and send the order again. Safe to repeat: no Idempotency-Key, no If-Match. An OAuth token's person needs update on the playlist's project.

Scopes: projects:write

Parameters

idpath · string (uuid)required
The playlist's id, from GET /api/v1/playlists?project_id=.

Request bodyReorderPlaylistItemsRequest

item_idsarray of string (uuid)required
Every item id of the playlist, each exactly once, in the new order (at most 1000). The items' sort_order becomes 0, 1, 2… in this order; position is untouched.

Response 200PlaylistItemList

dataarray of PlaylistItemrequired
- idstring (uuid)required
  The item's id — what DELETE …/items/{item_id} and PUT …/items/order take.
- assetobject or nullrequired
  The asset (its current version). Null when restricted.
  - idstring (uuid)required
  - namestringrequired
  - typeobjectrequired
    - idstring (uuid)required
    - namestringrequired
- restrictedbooleanrequired
  True for an OAuth token whose person may not read the asset (a playlist in an open project may hold material from a private one): the item keeps its place and id but not the asset's identity. Always false for an API key.
- sort_orderintegerrequired
  The item's place in the list; items are listed by it, ascending.
- positioninteger or nullrequired
  An optional editorial slot number (e.g. episode 3), independent of the list order.
- added_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, or insufficient-permission — an OAuth token's person may open the project but not update it.
404 not-found.
409 conflict — the playlist's items changed while it was being reordered; nothing moved.
422 validation — item_ids is not every item exactly once, or the playlist is too large to reorder here.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.