API reference

Collections

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

List the org's collections

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 constraints change, not when items do. A deleted collection leaves the list. For an OAuth token, the collections filed in a project its person can open.

Scopes: collections:read

Parameters

project_idquery · string (uuid)
Only collections filed in this project (GET /api/v1/projects). Not its sub-projects.
parent_idquery · string (uuid)
Only the collections nested directly in this one.
root_onlyquery · "true" | "false"
true: only collections not nested in another. Default false.
qquery · string
Case-insensitive substring of the collection's name. Characters are matched literally.
updated_afterquery · string (date-time)
Only collections changed strictly after this instant (ISO 8601 with offset), compared to the millisecond — poll with the newest updated_at you have seen (that collection does not come back), sorted -updated_at or updated_at.
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 200CollectionList

dataarray of Collectionrequired
- idstring (uuid)required
- namestringrequired
- descriptionstring or nullrequired
- projectProjectRef or nullrequired
  The project the collection is filed in — its permission parent: who may open the project may open the collection. Null only for an OAuth token whose person owns the collection but cannot open its project.
  - idstring (uuid)required
  - namestringrequired
- parent_idstring (uuid) or nullrequired
  The collection this one is nested in (GET /collections/{id}/children lists a parent's children), or null for a top-level collection.
- status"draft" | "published"required
  draft until published to consumers. Publishing and archiving are done in the app.
- allowed_type_idsarray of string (uuid) or nullrequired
  When set, only assets of these asset types (GET /api/v1/asset-types) may be added. Null or empty: any type.
- allowed_category_idsarray of string (uuid) or nullrequired
  When set, only assets assigned at least one of these org categories may be added. Null or empty: any.
- item_countintegerrequired
  How many items the collection holds (GET /collections/{id}/items lists them).
- created_atstring (date-time)required
- updated_atstring (date-time)required
  When its name, description or constraints 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 bad limit, project_id, parent_id, root_only, updated_after, sort or cursor.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

POST/api/v1/collections

Create a collection, filed in a project and optionally nested in another

Born a draft. project_id is its permission parent (omitted: the org's Unfiled project); parent_id nests it for browsing only. The credential is the collection's owner: for an API key, the key's service principal. An OAuth token's person needs create_collection in the org, contribute on a named project, and update on a named parent collection.

Scopes: collections: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 bodyCreateCollectionRequest

namestringrequired
descriptionstring or null
project_idstring (uuid)
The project to file it in (GET /api/v1/projects) — its permission parent. Omit to file it in the org's Unfiled project, which every member can open.
parent_idstring (uuid)
Nest it in this collection (GET /api/v1/collections). The nesting is for browsing only: who may open it is decided by its own project.
allowed_type_idsarray of string (uuid)
Only assets of these types may be added (GET /api/v1/asset-types).
allowed_category_idsarray of string (uuid)
Only assets assigned at least one of these org categories may be added.

Response 201Collection

A curated, ordered set of assets.

idstring (uuid)required
namestringrequired
descriptionstring or nullrequired
projectProjectRef or nullrequired
The project the collection is filed in — its permission parent: who may open the project may open the collection. Null only for an OAuth token whose person owns the collection but cannot open its project.
- idstring (uuid)required
- namestringrequired
parent_idstring (uuid) or nullrequired
The collection this one is nested in (GET /collections/{id}/children lists a parent's children), or null for a top-level collection.
status"draft" | "published"required
draft until published to consumers. Publishing and archiving are done in the app.
allowed_type_idsarray of string (uuid) or nullrequired
When set, only assets of these asset types (GET /api/v1/asset-types) may be added. Null or empty: any type.
allowed_category_idsarray of string (uuid) or nullrequired
When set, only assets assigned at least one of these org categories may be added. Null or empty: any.
item_countintegerrequired
How many items the collection holds (GET /collections/{id}/items lists them).
created_atstring (date-time)required
updated_atstring (date-time)required
When its name, description or constraints 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 not create collections, add to that project, or nest in that collection.
404 not-found.
409 idempotency-in-flight.
422 validation (name, description, project_id, parent_id, allowed_type_ids, allowed_category_ids), or idempotency-mismatch.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 authorization-write-failed — the collection's permissions could not be written, so it was rolled back; or internal.

GET/api/v1/collections/{id}

Get one collection

Scopes: collections:read

Parameters

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

Response 200Collection

A curated, ordered set of assets.

idstring (uuid)required
namestringrequired
descriptionstring or nullrequired
projectProjectRef or nullrequired
The project the collection is filed in — its permission parent: who may open the project may open the collection. Null only for an OAuth token whose person owns the collection but cannot open its project.
- idstring (uuid)required
- namestringrequired
parent_idstring (uuid) or nullrequired
The collection this one is nested in (GET /collections/{id}/children lists a parent's children), or null for a top-level collection.
status"draft" | "published"required
draft until published to consumers. Publishing and archiving are done in the app.
allowed_type_idsarray of string (uuid) or nullrequired
When set, only assets of these asset types (GET /api/v1/asset-types) may be added. Null or empty: any type.
allowed_category_idsarray of string (uuid) or nullrequired
When set, only assets assigned at least one of these org categories may be added. Null or empty: any.
item_countintegerrequired
How many items the collection holds (GET /collections/{id}/items lists them).
created_atstring (date-time)required
updated_atstring (date-time)required
When its name, description or constraints 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/collections/{id}

Rename or describe a collection, or change its constraints

If-Match is required: send the ETag from the last GET (or from the create). Changing a constraint does not remove items already in the collection. status is not settable — publishing and archiving are lifecycle acts done in the app — and an unknown field is a 422. An OAuth token's person needs update on the collection.

Scopes: collections:write

Parameters

idpath · string (uuid)required
The collection's id, from GET /api/v1/collections.
If-Matchheader · stringrequired
The collection's ETag.

Request bodyUpdateCollectionRequest

At least one of name, description, allowed_type_ids, allowed_category_ids. status is not settable: publishing and archiving are lifecycle acts done in the app. Moving a collection is not in v1.

namestring
descriptionstring or null
null clears it.
allowed_type_idsarray of string (uuid) or null
null or [] lifts the constraint. Items already in the collection stay.
allowed_category_idsarray of string (uuid) or null
null or [] lifts the constraint. Items already in the collection stay.

Response 200Collection

A curated, ordered set of assets.

idstring (uuid)required
namestringrequired
descriptionstring or nullrequired
projectProjectRef or nullrequired
The project the collection is filed in — its permission parent: who may open the project may open the collection. Null only for an OAuth token whose person owns the collection but cannot open its project.
- idstring (uuid)required
- namestringrequired
parent_idstring (uuid) or nullrequired
The collection this one is nested in (GET /collections/{id}/children lists a parent's children), or null for a top-level collection.
status"draft" | "published"required
draft until published to consumers. Publishing and archiving are done in the app.
allowed_type_idsarray of string (uuid) or nullrequired
When set, only assets of these asset types (GET /api/v1/asset-types) may be added. Null or empty: any type.
allowed_category_idsarray of string (uuid) or nullrequired
When set, only assets assigned at least one of these org categories may be added. Null or empty: any.
item_countintegerrequired
How many items the collection holds (GET /collections/{id}/items lists them).
created_atstring (date-time)required
updated_atstring (date-time)required
When its name, description or constraints 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 collection but not change 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 such as status, name, description, allowed_type_ids, allowed_category_ids).
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/collections/{id}

Delete a collection

Soft-deletes the collection; 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 delete on the collection.

Scopes: collections:write

Parameters

idpath · string (uuid)required
The collection's id, from GET /api/v1/collections.

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

GET/api/v1/collections/{id}/children

List the collections nested in a collection

The collections nested directly in this one, by name. For an OAuth token, only those its person can open.

Scopes: collections:read

Parameters

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

Response 200CollectionList

dataarray of Collectionrequired
- idstring (uuid)required
- namestringrequired
- descriptionstring or nullrequired
- projectProjectRef or nullrequired
  The project the collection is filed in — its permission parent: who may open the project may open the collection. Null only for an OAuth token whose person owns the collection but cannot open its project.
  - idstring (uuid)required
  - namestringrequired
- parent_idstring (uuid) or nullrequired
  The collection this one is nested in (GET /collections/{id}/children lists a parent's children), or null for a top-level collection.
- status"draft" | "published"required
  draft until published to consumers. Publishing and archiving are done in the app.
- allowed_type_idsarray of string (uuid) or nullrequired
  When set, only assets of these asset types (GET /api/v1/asset-types) may be added. Null or empty: any type.
- allowed_category_idsarray of string (uuid) or nullrequired
  When set, only assets assigned at least one of these org categories may be added. Null or empty: any.
- item_countintegerrequired
  How many items the collection holds (GET /collections/{id}/items lists them).
- created_atstring (date-time)required
- updated_atstring (date-time)required
  When its name, description or constraints 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 bad limit or cursor.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

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

List a collection's items in order

Ordered by sort_order, then by when each was added. Paginated: the list is bounded by the collection, 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: collections:read

Parameters

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

Response 200CollectionItemList

dataarray of CollectionItemrequired
- 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: the item keeps its place and id (a curator can still move or remove it) but not the asset's identity. Always false for an API key.
- sort_orderintegerrequired
  The item's position key; items are listed by it, ascending.
- 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/collections/{id}/items

Add an asset to a collection

Pins the asset's current version. Without sort_order the item goes after the last one. The collection's constraints apply: a type not in allowed_type_ids, an asset with none of allowed_category_ids, or an unpublished asset in a published collection is 422 collection-constraint, errors[].path naming the rule. An asset already in the collection (any version of it) is 409 already-member. An OAuth token's person needs update on the collection and read on the asset.

Scopes: collections:write

Parameters

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

Request bodyAddCollectionItemRequest

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.
sort_orderinteger
Its position key. Omit to append after the last item.

Response 201CollectionItem

One item of a collection: an asset at a position.

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: the item keeps its place and id (a curator can still move or remove it) but not the asset's identity. Always false for an API key.
sort_orderintegerrequired
The item's position key; items are listed by it, ascending.
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 collection but not change it.
404 not-found.
409 already-member — the asset is already in the collection (item_id in the body); or idempotency-in-flight.
422 collection-constraint, unknown-asset, validation (asset_id, sort_order), or idempotency-mismatch.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

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

Remove an item from a collection

The asset itself is untouched. A second DELETE is a 404. An OAuth token's person needs update on the collection.

Scopes: collections:write

Parameters

idpath · string (uuid)required
The collection's id, from GET /api/v1/collections.
item_idpath · string (uuid)required
The item's id, from GET /api/v1/collections/{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 collection but not change it.
404 not-found.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

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

Put a collection's items in a new order

item_ids is every item of the collection, each exactly once, in the new order; their sort_order becomes 0, 1, 2… Anything else (a missing, repeated or foreign id) is a 422. A collection 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 collection.

Scopes: collections:write

Parameters

idpath · string (uuid)required
The collection's id, from GET /api/v1/collections.

Request bodyReorderCollectionItemsRequest

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

Response 200CollectionItemList

dataarray of CollectionItemrequired
- 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: the item keeps its place and id (a curator can still move or remove it) but not the asset's identity. Always false for an API key.
- sort_orderintegerrequired
  The item's position key; items are listed by it, ascending.
- 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 collection but not change it.
404 not-found.
409 conflict — the collection's items changed while it was being reordered; nothing moved.
422 validation — item_ids is not every item exactly once, or the collection is too large to reorder here.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.