Ralti’s application API lives under the app host at /api. The public marketing website is separate. The endpoint catalog enumerates exported HTTP handlers from the current application source, including Apps, agent members, and restricted integration setup. This is the application contract, not a separate versioned public developer platform or a new API-key system.

Visual workflows use /api/flows and /api/flows/draft. /api/workflows remains the older helper contract. Persistent teammate management uses /api/agents. /api/apps manages builder definitions and releases; participant routes under /api/apps/{workspaceId}/{appId} and /api/public/apps/{workspaceId}/{appId} enforce app-specific access rather than exposing a workspace snapshot. Integration routes retain separate rollout admission.

Choose the correct identity#

ClientCredentialImportant distinction
Web and installed iPhone/iPad app with ClerkClerk session cookie managed by ClerkUse the shared Clerk website sign-in flow. Explicit iOS provider actions return through the native session handoff; POST /api/auth is not a replacement for Clerk sign-in.
Earlier Android client or direct API client with ClerkAuthorization: Bearer <current Clerk session JWT>Obtain a current token through the client SDK; never embed Clerk server secrets.
Explicit local developmentRalti session cookie or opaque native bearer tokenLocal signup/signin/signout are development flows, without Clerk’s recovery or email-verification guarantees.
External AI/MCPA scoped Ralti MCP connection tokenIssued separately, bound to one workspace, and accepted at /api/mcp. It is not a normal app session.
Published formx-ralti-form-key capabilityAuthorizes only the published form; it is not workspace membership.

GET /api/session is the bootstrap for ordinary app clients. In Clerk mode an unsigned request receives 401 clerk_signin_required and does not create a guest. In explicit local mode it can create an empty guest workspace. A local native bootstrap identifies itself with x-atlas-client: native and receives an opaque token only when the response creates that session. Existing session reads do not continuously return or rotate a token.

Keep workspace scope explicit#

Send X-Atlas-Workspace when a request belongs to a selected workspace. If omitted, the server resolves the account’s saved preference. The header selects a resource boundary; it never proves membership or changes the permissions attached to the identity. Keep it tied to the screen, draft, or asynchronous action that initiated the request so a workspace switch cannot redirect in-flight work.

http
GET /api/session HTTP/1.1
Host: app.your-domain.example
Authorization: Bearer <current-session-jwt>
X-Atlas-Workspace: workspace_example
X-Ralti-Workspace-Mode: paged

The session response includes the public user, workspace, access, workspace list, member directory, and capabilities. Request paged mode for a bounded workspace representation, then use the record page endpoints. Capabilities tell the client whether cloud AI is configured and which storage/auth mode the server reports; they do not replace feature-specific permission checks.

Browser writes and native requests#

Browser mutations require an Origin that exactly matches the application’s configured public origin. A different scheme, host, or port is a different origin. Requests with a supplied mismatched Origin are rejected even when they also carry a bearer token. Native bearer requests can omit Origin when they are not identified as cross-site browser requests. Ralti does not grant blanket cross-origin browser access to its API.

For JSON endpoints send Content-Type: application/json and an object body. Limits vary by endpoint. File uploads use multipart/form-data; let the client library generate its boundary. Keep authentication tokens and mailbox passwords out of logs, screenshots, URLs, and exported examples.

Read the response type before parsing#

  • Normal JSON responses use no-store and nosniff headers; failures usually contain error and code.
  • Attachment, CSV/JSON sheet export, and document PDF routes return download bytes on success.
  • Email OAuth callback routes redirect with HTTP 303 on both success and failure.
  • Immediate interpretation can return NDJSON when stream:true.
  • MCP uses the SDK’s JSON-RPC/protocol transport and its own error behavior.
  • GET /api/health is public liveness only and does not prove database, authentication, provider, or worker readiness.