Import a portable presentation bundle
Required scopes: presentation.import, presentation.create, presentation.update, asset.create.
Synchronous atomic import of an existing self-contained .bibleit ZIP bundle. All four scopes are required even without media. At most 512 MiB compressed, 400 MiB expanded, 513 entries including up to 512 assets and a 6 MB manifest. Rejects traversal, duplicate or unlisted entries, invalid manifest/document, checksum mismatch and invalid media. Uses existing portable bundle validation and quotas; malformed bundles return 422, duplicate organization fingerprint or quota exhaustion 409. Preflight scope/ownership/processing checks precede body read; capacity is checked after retry lookup before new writes; current authorization is rechecked under the commit lock. Failed imports roll back database records and newly written files. Allocates fresh deck, slide, element and media IDs, normalizes rights, and returns the saved presentation with Location and ETag. No URL fetching or Live publication. Content-Encoding must be identity; body read budget 60 seconds. 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:
ETag(201): Strong validator covering presentation ID, organization, revision and rights-normalized document. Browser/editor saves and changed effective rights notices invalidate it.Location(201): Relative presentation 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.
Request
Response headers
Strong validator covering presentation ID, organization, revision and rights-normalized document. Browser/editor saves and changed effective rights notices invalidate it.
Response
Version-1 document, at most 2,000,000 encoded JSON bytes. Slide IDs are unique across the deck, element IDs within each slide. Omitted slide background is preserved as omitted. Save retains caller slide/element IDs; no automatic publishing. Existing same-workspace ready media references are checked by the domain; upload and portable import endpoints provide ready media. Uploading alone never modifies the saved document.