Upload a staged presentation asset
Required scopes: asset.create, presentation.update.
Send raw bytes, not multipart or JSON. Images are bounded to 10 MiB, dimensions 8192 per side and 40 million pixels; videos to 64 MiB and 4096 per side. Actual bytes, media format and existing codec/container constraints are inspected, regardless of claimed Content-Type. Content-Encoding must be identity. Body reading has a 60-second budget. Existing organization media quotas and upload reservations apply; definitive rejections release reservations and bytes; an ambiguous keyed completion retains its bounded lease until retry/reconciliation or normal expiry. Keyed uploads read and hash the bounded body after authorization, before quota reservation, so full quotas cannot block replay. Fresh scopes and ownership are checked before reservation and completion. Returns safe metadata and a protected asset Location, never a storage key/path. Ready assets are staged for 24 hours; attach through conditional presentation PUT to retain them. Uploading does not change document revision/ETag or publish. Optional Idempotency-Key atomically records a successful creation for 24-hour replay; current authorization is rechecked. Changed payload or original If-Match returns 409 idempotency_conflict. Replay precedes stale-version and quota evaluation.
Additional request headers:
Content-Length(required): Required exact raw body byte count. Missing returns 411, excessive returns 413. Chunked-only requests are unsupported.Idempotency-Key(optional): Optional case-sensitive retry key, retained 24 hours from successful commit. Scoped to credential principal (stable service-token ID; personal bt_ credential; delegated OAuth grant), account and concrete method/path. Payload, If-Match, query string and Content-Type must match. JSON object key order is ignored; queue reference casing/defaults are normalized; raw upload/import bytes are hashed. Replays retain original success body, Location and ETag with a fresh X-Request-Id, after current authority/ownership/processing/library checks. Same scope/key with changed input:409 idempotency_conflict. Concurrent requests serialize; a contended retry lock can return 409 idempotency_in_progress; bounded database waits can return 503. Errors are not recorded. After expiry, a key is treated as new; original resource/job lifetime is unchanged. No key means no retry guarantee.
Response headers:
Cache-Control(201).Location(201): Bearer-protected asset resource URL.
Authentication
Organization-owned service token. Issue the initial token in organization credential settings. Scopes are documented per operation via x-required-scopes; they are not OAuth scopes.
Path parameters
Headers
Optional case-sensitive retry key, retained 24 hours from successful commit. Scoped to credential principal (stable service-token ID; personal bt_ credential; delegated OAuth grant), account and concrete method/path. Payload, If-Match, query string and Content-Type must match. JSON object key order is ignored; queue reference casing/defaults are normalized; raw upload/import bytes are hashed. Replays retain original success body, Location and ETag with a fresh X-Request-Id, after current authority/ownership/processing/library checks. Same scope/key with changed input:409 idempotency_conflict. Concurrent requests serialize; a contended retry lock can return 409 idempotency_in_progress; bounded database waits can return 503. Errors are not recorded. After expiry, a key is treated as new; original resource/job lifetime is unchanged. No key means no retry guarantee.
Query parameters
Image: up to 10 MiB. Video: up to 64 MiB.
Request
Response headers
Bearer-protected asset resource URL.