Browse documentation
HTTP API reference
Public configuration, scoped SDK requests and app setup endpoints.
Use the actual origin and the right credential
Routes start at /v1 on the configured hej origin; do not add an /api prefix. Public configuration needs no secret. SDK routes use a customer-scoped bearer created for one app/environment, while operator routes use the authenticated workspace session and current role/app grants. These credentials are not interchangeable. Never place operator/provider credentials in a native app, public config or copied setup prompt. This is an early-pilot contract reference, not a promise that every adapter is configured.
Public configuration and guest sessions
GET /v1/public/apps/{configId}/configuration returns schema, environment, appearance and advertised capabilities. POST /v1/sdk/sessions accepts configId and installationId, with optional displayName/device, and returns scoped token/refreshToken/session/customer/app data. A claimed installation label never recovers history. POST /v1/sdk/sessions/refresh rotates the refresh credential; DELETE /v1/sdk/sessions/current revokes the credential family. The Swift SDK manages these credentials in Keychain.
GET /v1/public/apps/YOUR_PUBLIC_CONFIGURATION_ID/configuration
POST /v1/sdk/sessions
Content-Type: application/json
{
"configId": "YOUR_PUBLIC_CONFIGURATION_ID",
"installationId": "A_RANDOM_INSTALLATION_LABEL"
}Conversations, messages and receipts
GET/POST /v1/sdk/threads lists or creates customer-visible conversations. GET /v1/sdk/threads/{threadId}/messages uses afterPublicSequence, beforePublicSequence and limit for authoritative pagination. POST to that messages route accepts text and optional completed attachmentIds. Public sends use Idempotency-Key and the exact attempted body on retry. PUT /v1/sdk/threads/{threadId}/receipts separates fetchedPublicSequence, readPublicSequence and displayedPublicSequence. GET /v1/sdk/unread returns counts without fetching content or advancing cursors when unread_summary_v1 is advertised. SSE changes are hints; HTTP remains authoritative.
Revisioned profile and action capability updates
customer_profile_v1 enables GET/PUT /v1/sdk/profile. GET returns the profile revision; PUT requires If-Match (starting at 1) and Idempotency-Key. Metadata/device/reported-provider maps replace completely when present; omitted maps stay unchanged. registered_actions_v1 enables GET/PUT /v1/sdk/action-capabilities, whose initial revision is 0. Registry PUT also requires If-Match and a request key. Retain exact body/key/revision after a lost response. A definite revision conflict requires reviewing/reloading current data, not changing an ambiguous request’s body.
Identity and explicit action execution
Host identity uses POST /v1/sdk/identity/challenges followed by exchanges or links, with the same current guest proof, fresh purpose-bound assertion and request key. No label matching merges history. Action execution uses POST /v1/sdk/threads/{threadId}/actions/{messageId}/tickets with observedCapabilityRevision and userInitiated: true, then receipts with ticketId, nonce and requested/opened/cancelled/failed. Exact-session authorization, live registry checks and short expiry apply. Confirm requested before a local handler; StoreKit review reports requested only, because prompt display is unobservable.
Private image uploads
With private_photos_v1, POST /v1/sdk/uploads reserves {threadId, contentType, bytes}; PUT the returned same-origin uploadPath with exact raw bytes and declared type; POST /v1/sdk/uploads/{id}/complete returns normalized attachment metadata. Claim completed IDs only through an accepted message, at most five attachments. Raw JPEG/PNG/WebP is bounded to 2,000,000 bytes; the service normalizes WebP to at most 1 MiB/2,048 pixels. GET /v1/sdk/media/{id}/content reauthorizes the current customer on every fetch. DELETE an unattached upload to cancel it. There is no public media URL.
Operator app setup and App Store metadata
Owner/admin GET /v1/operator/app-store?q=NAME_OR_ID_OR_APPLE_URL&country=us returns up to ten Apple catalog results with appStoreId, name, appStoreUrl, iconUrl and developer. POST /v1/operator/apps requires name/supportEmail and accepts those optional flat listing fields. GET/PUT /v1/operator/apps/{appId}/settings edits an existing app; PUT requires If-Match settingsRevision and Idempotency-Key. Omitted listing metadata is preserved; appStoreId: null with all listing fields null clears it. A save does not change configId. Capture X-Lobby-Workspace and the full attempted body before a mutation. These onboarding write/replay contracts currently require the MongoDB hosting profile.
Diagnostics, errors and provider boundaries
GET /v1/operator/apps/{appId}/diagnostics reports six independent actual conversation observations for an authorized app/environment. It is not a test app, a simulated send or proof of push/purchase delivery. Read safe error codes/request IDs without logging credentials or message bodies. A public capability means the protocol is supported, not that a host/provider is configured or its delivery was observed. Use the workspace’s actual readiness and release evidence for that distinction.