API reference

Asset share links

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/assets/{id}/share-links

List an asset's public share links

Newest first: whether each has a password, its expiry, clip and download setting, how often it was opened, who made it. Never a link's URL or token — those are returned once, when the link is made — and never its password. For an OAuth token, its person must be able to share the asset (asset share), as in the app (403 otherwise; 404 when they cannot open it).

Scopes: assets:read

Parameters

idpath · string (uuid)required
The asset's id: its current version's id or its root id (an older version's id is not found).
limitquery · integer
Page size, default 50. Values above 100 are treated as 100.
cursorquery · string
next_cursor from the previous page.

Response 200ShareLinkList

A page of an asset's share links, newest first.

dataarray of ShareLinkrequired
- idstring (uuid)required
- assetobjectrequired
  The asset it shares (its current version's id and name).
  - idstring (uuid)required
  - namestringrequired
- has_passwordbooleanrequired
- expires_atstring (date-time) or nullrequired
  When it stops working; null: never.
- expiredbooleanrequired
- allow_downloadbooleanrequired
- clip_start_secondsnumber or nullrequired
- clip_end_secondsnumber or nullrequired
- view_countintegerrequired
  How many times it was opened.
- created_byobject or nullrequired
  Who made it: a member, or API for a link made with an org API key. Null if their account is gone.
  - idstring (uuid)required
  - namestringrequired
- created_atstring (date-time)required
next_cursorstring or nullrequired

Other responses

401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope, or insufficient-permission — the token's person cannot share the asset.
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/assets/{id}/share-links

Make a public share link to an asset (guarded)

A guarded action (ADR 0081): anyone holding the link can watch the asset without signing in. The app's own write runs: a password is stored salted and hashed (the viewer enters it on the link's page; it is never sent in a URL); a clip pins the link to a cut; an asset under legal hold is 409 legal-hold. **An API key's link is made at once**: 201 with the link and its url — the ONLY time the URL is returned; keep it as you would a password. **An OAuth token's is not**: 202 with a Confirmation naming the asset, the expiry, download and password; once its person confirms it in impartire the link is made as them, and the confirmation's result is the CreatedShareLink with its url (readable only by the app and person that asked). Its person must be able to share the asset (no platform-admin bypass). Audited: a share_link.created event and the row's capture.

Scopes: sharing:write

Parameters

idpath · string (uuid)required
The asset's id: its current version's id or its root id (an older version's id is not found).
Idempotency-Keyheader · string
Makes a retry safe: the same key and request within 24 hours replays the first response. 1–255 characters.

Request bodyCreateShareLinkRequest

expires_in_daysinteger or null
The link stops working this many days from now (1–365). Null or omitted: it never expires.
passwordstring or null
A password the viewer must enter. Stored salted and hashed, never readable again. Null or omitted: none.
allow_downloadboolean
Whether the viewer may download the video. Default false.
clip_start_secondsnumber or null
Pin the link to a cut: its start, in seconds. Set with clip_end_seconds.
clip_end_secondsnumber or null
The cut's end, in seconds; after clip_start_seconds.

Response 201CreatedShareLink

A share link just created, with its URL — the only time the URL is returned.

idstring (uuid)required
assetobjectrequired
The asset it shares (its current version's id and name).
- idstring (uuid)required
- namestringrequired
has_passwordbooleanrequired
expires_atstring (date-time) or nullrequired
When it stops working; null: never.
expiredbooleanrequired
allow_downloadbooleanrequired
clip_start_secondsnumber or nullrequired
clip_end_secondsnumber or nullrequired
view_countintegerrequired
How many times it was opened.
created_byobject or nullrequired
Who made it: a member, or API for a link made with an org API key. Null if their account is gone.
- idstring (uuid)required
- namestringrequired
created_atstring (date-time)required
urlstringrequired
The public URL — the token in it is the link's whole authority. Returned ONCE, here (and in the confirmation's result for an OAuth token); never listed again. Keep it as you would a password.

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 cannot share the asset.
404 not-found.
409 legal-hold — the asset is held; confirmation-pending; or idempotency-in-flight.
422 validation (a bad field; a clip with one end, or an end not after its start), or idempotency-mismatch.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.

DELETE/api/v1/assets/{id}/share-links/{link_id}

Revoke a public share link (guarded)

A guarded action (ADR 0081): the link stops working for everyone who has it, at once. For an OAuth token, the link's creator or a person who can share the asset, as in the app. **An API key's revoke happens at once** (204). **An OAuth token's does not**: 202 with a Confirmation; once its person confirms it in impartire the link is revoked as them. Audited: a share_link.revoked event and the row's capture.

Scopes: sharing:write

Parameters

idpath · string (uuid)required
The asset's id: its current version's id or its root id (an older version's id is not found).
link_idpath · string (uuid)required
The link's id, from GET /api/v1/assets/{id}/share-links or its create.

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

204 An API key's revoke: the link is gone.
401 unauthenticated — no key, or an unknown, revoked or expired one.
403 insufficient-scope, or insufficient-permission — neither its creator nor someone who can share the asset.
404 not-found.
409 confirmation-pending.
429 rate-limited — the key's request budget is spent; wait Retry-After seconds.
500 internal.