Create an organization presentation | Bibleit API Reference

curl -X POST https://api.bibleit.app/v1/organizations/organization_id/presentations \
     -H "Idempotency-Key: integration-7c642889-60eb-47ed-a16c-13e290e3f054" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Sunday"
}'

{
  "id": "string",
  "organization_id": "string",
  "revision": 1,
  "document": {
    "version": 1,
    "name": "Sunday",
    "slides": [
      {
        "id": "opening",
        "elements": [
          {
            "height": 560,
            "id": "heading",
            "text": "Welcome",
            "type": null,
            "width": 1120,
            "x": 80,
            "y": 80
          }
        ],
        "background": "#ffffff"
      }
    ]
  }
}

Required scopes: presentation.create.

Creates an empty version-1 presentation at saved revision 0 with the supplied name. Enforces existing organization deck allocation quotas; quota exhaustion returns 409. Service tokens create organization-owned decks without a human creator or member seat. Returns the document and strong ETag even if the creator scope does not include presentation.get. Does not publish to a Live. 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.

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

AuthorizationBearer

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

organization_idstringRequiredformat: "uuid"

Immutable organization UUID bound to the service token.

Headers

Idempotency-KeystringOptionalformat: "^[A-Za-z0-9._:-]{1,128}$"1-128 characters

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

This endpoint expects an object.

namestringRequired1-200 characters

UTF-8 text, at most 200 bytes; NUL is rejected.

Response headers

X-Request-IdstringOptional

ETagstringOptionalformat: "^"presentation-[a-f0-9]{64}"$"

Strong validator covering presentation ID, organization, revision and rights-normalized document. Browser/editor saves and changed effective rights notices invalidate it.

LocationstringOptional

Relative presentation resource URL.

Response

Successful operation

idstringformat: "uuid"

organization_idstringformat: "uuid"

revisioninteger>=0

documentobject

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.

Errors

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

503

Service Unavailable Error