Skip to content
RaltiDocsEARLY ACCESSWebsite ↗
Documentation/API explorer
THE CONTRACT, IN CONTEXT

Meet the API.

Browse every application endpoint. Inspect authentication, parameters, and synthetic examples without touching a live workspace.

Download the endpoint catalog ↓

150 operations

GET/api/sessionRead the current session
Link to this operation #

Read the current session

Returns user, workspace, access, workspaces, members, and capabilities. Paged mode uses a bounded session response.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.
X-Ralti-Workspace-ModeheaderNoSet to paged to receive workspace metadata and bounded initial data rather than assuming every sheet is fully loaded.
initialSheetqueryNoOptional initial sheet ID when X-Ralti-Workspace-Mode is paged.
view / query / q / archivedqueryNoInitial paged-sheet view, search (query or q), and archived=true options.

Behavior to know

  • In Clerk mode, an unsigned request returns 401 clerk_signin_required without creating a guest or setting a guest cookie.
  • Explicit local mode can bootstrap an empty guest workspace and session. x-atlas-client: native adds a token only during token-creating bootstrap; existing session reads do not return a new token.
  • Capabilities include cloudAI, storage, authProvider, and optional accountLinkAvailable.
POST/api/authAuthenticate locally or link an existing account
Link to this operation #

Authenticate locally or link an existing account

Clerk deployments accept only link and start_new after a verified Clerk identity. Explicit local mode accepts signup, signin, and signout.

Authentication & access

Clerk link/start_new requires a verified Clerk identity and any required legacy proof. Local signup/signin/signout use the local authentication boundary.

Parameters

NameLocationRequiredDescription
modebodyYesclerk: link | start_new; local: signup | signin | signout.
emailbodyNoRequired for local signin/signup or password-based legacy proof.
passwordbodyNo10–256 characters for local sign-in/signup and legacy proof.
namebodyNoRequired local signup name, nonempty and at most 100 characters.

Example request body

json
{
  "mode": "start_new"
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 8,192 bytes. Returns a session response; local native token-creating responses may also include token.
  • Local signout revokes the existing opaque session and creates a fresh guest. Clerk sign-in/sign-up/sign-out must use Clerk rather than these local modes.
  • Linking never establishes ownership from an email match alone. Password proof or a valid legacy session is required where applicable.
POST/api/mobile/auth/exchangeComplete an installed iOS sign-in handoff
Link to this operation #

Complete an installed iOS sign-in handoff

An app-managed step used by the installed iOS app’s shared finish page after explicit system authentication. It completes the configured website sign-in flow. This endpoint is documented for understanding the app lifecycle; it is not a supported third-party login integration.

Authentication & access

A valid, unexpired, single-use sign-in handoff code and its matching device verifier. An exact same-origin browser Origin header is required.

Parameters

NameLocationRequiredDescription
OriginheaderYesThe exact configured application origin, supplied by the shared finish page.
codebodyYesThe one-use code returned by the authorized system sign-in handoff.
verifierbodyYesThe matching private verifier retained by the initiating device.

Behavior to know

  • Call only through the normal Ralti sign-in flow. Native bearer exceptions do not remove the required Origin header.
  • Accepts a JSON object containing only code and verifier, with a 4,096-byte body limit. Expired, mismatched, or already consumed grants cannot be reused.
  • Successful completion lets the finish page activate the configured website session. It does not create a third-party API credential or grant additional workspace access.
  • Responses are not cacheable and suppress referrers. Never log handoff codes, verifiers, or returned tickets.
  • If the handoff fails, restart sign-in from the installed app instead of replaying credentials.
GET/api/workspacesList accessible workspaces
Link to this operation #

List accessible workspaces

Returns {workspaces:[...]}, limited to workspaces accessible to the actor.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Example response

json
{
  "workspaces": []
}
POST/api/workspacesCreate, switch, or rename a workspace
Link to this operation #

Create, switch, or rename a workspace

Applies action create, switch, or rename and returns the resulting session response.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions.

Parameters

NameLocationRequiredDescription
actionbodyYescreate | switch | rename.
namebodyNoName for create or rename.
workspaceIdbodyNoTarget workspace for switch; membership required.

Example request body

json
{
  "action": "create",
  "name": "Example projects"
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Rename is managed by the service permission boundary. Workspace selection does not bypass membership.
POST/api/actionsApply a validated operation batch
Link to this operation #

Apply a validated operation batch

Validates and atomically applies the operation array, checks the expected workspace revision, and returns the application result with authoritative workspace and runs.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions.

Parameters

NameLocationRequiredDescription
operationsbodyYesArray of supported Operation objects; at most 500 operations.
expectedRevisionbodyYesInteger workspace revision from the server-owned workspace or proposal being applied.
confirmedbodyNotrue when the reviewed operation batch requires explicit confirmation.
aiJobIdbodyNoOptional owned, completed saved job ID; its application receipt commits with the mutation.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.
X-Ralti-Workspace-ModeheaderNoSet to paged to receive workspace metadata and bounded initial data rather than assuming every sheet is fully loaded.

Example request body

json
{
  "operations": [
    {
      "action": "update_item",
      "spaceId": "sheet_projects",
      "itemId": "record_example",
      "notes": "Reviewed launch checklist."
    }
  ],
  "expectedRevision": 7
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • JSON body limit: 4 MiB. Operation validation, permissions, rules, and references apply to the whole batch.
  • Returns workspace, summary, historyId, and runs. In external-worker mode runs is empty because scheduling is handled outside the request.
  • Stale revisions return HTTP 409 revision_conflict. Do not replace the proposal revision with a newer value just to bypass a conflict.
  • Synthetic examples require IDs and revisions read from your own workspace.
POST/api/historyUndo or redo the current history entry
Link to this operation #

Undo or redo the current history entry

Applies an undo or redo with a revision check, then returns {workspace}.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions.

Parameters

NameLocationRequiredDescription
directionbodyYesundo | redo.
expectedRevisionbodyYesInteger workspace revision from the server-owned workspace or proposal being applied.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.
X-Ralti-Workspace-ModeheaderNoSet to paged to receive workspace metadata and bounded initial data rather than assuming every sheet is fully loaded.

Example request body

json
{
  "direction": "undo",
  "expectedRevision": 8
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 4,096 bytes. History advances the workspace revision; it does not return to an earlier revision number.
  • Top-of-history actor and permission checks apply. This is not selective conflict merging.
GET/api/record-versionsRead saved versions of a record
Link to this operation #

Read saved versions of a record

Returns {versions:[...]} for the authorized sheet and record.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
spaceIdqueryYesSheet identifier.
itemIdqueryYesRecord identifier.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Example response

json
{
  "versions": []
}

Behavior to know

  • Versions are governed record evidence, separate from workspace undo/redo.
GET/api/recordsPage workspace records
Link to this operation #

Page workspace records

Returns workspaceId, revision, records:[{spaceId,item}], total, nextCursor, labels, and counts for all/assigned/due records.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
scopequeryNoall (default), assigned, or due; other values normalize to all.
queryqueryNoOptional text search.
todayqueryNoDate used for due scope.
cursorqueryNoOpaque cursor from the previous response.
limitqueryNoInteger 1–100; default 100.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Cursor identity binds the query and workspace revision. HTTP 409 page_changed means reload from the first page.
  • nextCursor is null at the end. Treat returned record arrays as pages, not the whole workspace.
GET/api/sheets/{id}/itemsPage records in a sheet
Link to this operation #

Page records in a sheet

Returns a SheetPage: workspaceId, spaceId, revision, items, total, nextCursor, and labels.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
viewqueryNoSaved view identifier used for filtering/sorting.
queryqueryNoSearch text.
archivedqueryNoLiteral true selects archived records.
cursorqueryNoOpaque cursor from the previous response.
limitqueryNoInteger 1–100; default 100.
itemqueryNoFetch a specific item.
itemsqueryNoJSON-encoded array of record IDs.
exactqueryNoLiteral true selects exact-label matching.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • The server validates sheet/view/item scope and enforces access.
  • Cursor belongs to one query identity and revision; changing either requires starting again.
GET/api/sheets/{id}/exportDownload a sheet export
Link to this operation #

Download a sheet export

Exports the authorized sheet as CSV when format=csv, or JSON otherwise.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
formatqueryNocsv for text/csv; any other/omitted value gives application/json.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Successful response is a file download with Content-Disposition, not an API JSON envelope.
  • CSV resolves computed values and readable linked/member names and escapes formula-like text. Export operates on server-owned sheet data.
  • Errors use the normal JSON error response.
GET/api/search/statusRead permitted search-index status
Link to this operation #

Read permitted search-index status

Returns workspaceId, keywordSearch, semanticSearch configuration/model/dimensions/sources, and coverage.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Sources are limited by workspace and mailbox access. The response exposes counts/configuration, not indexed private content.
  • Semantic search dimensions are 512. coverage.attachments is false.
POST/api/interpretInterpret an immediate request
Link to this operation #

Interpret an immediate request

Produces a proposal without applying it. Supports JSON or a request-connected NDJSON stream.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
requestbodyYesNonempty instruction, at most 5,000 characters.
interpretationModebodyNoai (default) or explicit built_in.
intentbodyNoask (answer-only) or edit.
streambodyNotrue requests NDJSON progress events.
spaceId / workbookId / insightId / viewIdbodyNoOptional validated context identifiers.
selectedItemIdsbodyNoUp to 1,000 selected record IDs.
conversation / pendingDraft / draftJobIdbodyNoBounded prior conversation or owned saved-draft context.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Example request body

json
{
  "request": "Summarize the open projects.",
  "intent": "ask",
  "interpretationMode": "ai"
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 100,000 bytes. Viewers are answer-only. Generation does not mutate records.
  • JSON returns Proposal fields including operations, summary, risk, provider, and baseRevision; optional clarification, sources, deployment, and aiUnavailable depend on the outcome.
  • stream=true returns application/x-ndjson with status/text/activity/heartbeat/proposal/error events. Only a completed validated proposal is applicable.
  • A missing AI provider can return a successful availability proposal with no operations; check provider/aiUnavailable instead of treating HTTP 200 as an actionable edit.
  • For work that should survive a browser disconnect, use durable /api/ai-jobs.
POST/api/ai-jobsCreate a durable AI job
Link to this operation #

Create a durable AI job

Persists a private actor/workspace-scoped request and returns its public AiJob with HTTP 202.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
requestbodyYesNonempty instruction, at most 5,000 characters.
clientRequestIdbodyNoOptional retry deduplication identifier, 8–100 letters, digits, underscore or hyphen.
intentbodyNoask or edit.
spaceId / workbookId / insightId / viewId / selectedItemIdsbodyNoOptional validated context.
conversation / pendingDraft / draftJobIdbodyNoBounded conversation or owned saved-draft refinement context.
resumeJobIdbodyNoFailed, undismissed job to resume with exactly matching saved request/context.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Example request body

json
{
  "request": "Summarize the open projects.",
  "intent": "ask",
  "clientRequestId": "example_request_0001"
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 100,000 bytes. built_in is rejected here; use /api/interpret for built-in help.
  • Statuses: queued, running, completed, failed, cancelled. Public job fields include id, workspaceId, request, input, baseRevision, status, timestamps, progress, and optional proposal/error/failure.
  • Internal workspace snapshots and model checkpoints are not returned. A background worker must run to process saved jobs.
  • A resume requires the original request and context; changing them produces resume_context_changed.
GET/api/ai-jobsList saved AI jobs
Link to this operation #

List saved AI jobs

Returns {jobs:[...]} for the requesting actor in the selected workspace.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Example response

json
{
  "jobs": []
}

Behavior to know

  • The service lists up to 20 undismissed jobs, prioritizing active work. Membership is rechecked.
GET/api/ai-jobs/{id}Read an owned AI job
Link to this operation #

Read an owned AI job

Returns the public AiJob state and any completed proposal.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • A workspace teammate cannot read another actor’s private job merely by knowing its ID.
DELETE/api/ai-jobs/{id}Cancel or dismiss an AI job
Link to this operation #

Cancel or dismiss an AI job

Requests cancellation for active work or dismisses a finished request; returns the resulting public AiJob.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Cancellation/dismissal is separate from undoing an already applied workspace change. Inspect the returned status.
PATCH/api/ai-jobs/{id}Edit or refresh a saved draft
Link to this operation #

Edit or refresh a saved draft

For a completed, unapplied, undismissed job, accepts sheetNames, validated operations, or rebase:true and returns the updated public AiJob.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
sheetNamesbodyNoAlternative body: array of {spaceId,name}, 1–100 unique sheet IDs; names up to 200 characters.
operationsbodyNoAlternative body: nonempty validated Operation array for the draft.
rebasebodyNoAlternative body: true requests safe refresh against unchanged dependencies.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Example request body

json
{
  "rebase": true
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 512,000 bytes. Do not mix sheetNames with operations/rebase; unsupported keys are rejected.
  • Dependency changes produce 409 draft_dependencies_changed; invalid state produces invalid_draft_state. A safe refresh is not a way to overwrite changed source data.
  • This updates the saved proposal only; /api/actions performs an explicit reviewed apply.
POST/api/attachmentsUpload a private attachment
Link to this operation #

Upload a private attachment

Accepts multipart/form-data with a nonempty file field and returns {url,name} with HTTP 201.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions.

Parameters

NameLocationRequiredDescription
fileformDataYesNonempty file, at most 10 MiB.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Example response

json
{
  "url": "/api/attachments/00000000-0000-4000-8000-000000000001",
  "name": "example.pdf"
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • The multipart envelope is bounded to file maximum plus 65,536 bytes. Workspace file quota is enforced by the repository.
  • Uploading bytes does not insert an attachment reference into a record. Save the returned URL through the standard action contract.
GET/api/attachments/{id}Download or preview an attachment
Link to this operation #

Download or preview an attachment

Checks membership against the attachment’s actual workspace before returning private bytes.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
previewqueryNo1 permits inline rendering only for stored PNG/JPEG/WebP/GIF/AVIF MIME types.

Behavior to know

  • Success is a binary response with private,no-store; default MIME is application/octet-stream and disposition is attachment.
  • Preview remains sandboxed and nosniff. Other file types stay downloads. Errors use the normal JSON shape.
GET/api/dashboardRead a workbook overview
Link to this operation #

Read a workbook overview

Computes the authorized workbook dashboard from server-owned data.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
workbookIdqueryYesExisting workbook ID.
sheetIdqueryNoall (default) or a sheet belonging to this workbook.
todayqueryNoYYYY-MM-DD date; defaults to server UTC date.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • This workbook overview differs from saved insight document queries.
POST/api/insights/queryQuery a dashboard layout
Link to this operation #

Query a dashboard layout

Evaluates a validated InsightDocument against authorized server data without saving the layout.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
documentbodyYesInsightDocument validated by insightDocumentSchema.
blockIdbodyNoOptional block in that document.
groupKeybodyNoOptional group drilldown; requires blockId.
offsetbodyNoInteger 0–1,000,000.
limitbodyNoInteger 1–100.
todaybodyNoOptional ISO date.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 2 MiB. Returns queryInsights output for the requested layout or drilldown; this is read-only computation despite POST.
  • Financial and operational report definitions and versions use /api/reports.
POST/api/insights/previewPreview a proposed insight layout
Link to this operation #

Preview a proposed insight layout

Stages operations in memory against the exact expected revision, finds documentId in that preview, and computes its result without saving.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
operationsbodyYes1–500 operations to stage.
documentIdbodyYesInsight document present in the staged layout.
expectedRevisionbodyYesInteger workspace revision from the server-owned workspace or proposal being applied.
blockId / groupKey / offset / limit / todaybodyNoOptional drilldown fields; groupKey requires blockId, limit 1–100, offset 0–1,000,000.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 4 MiB. Defaults preview limit to 8. Returns query result plus revision, preview:true, baseRevision, and document.
  • No repository apply, persistence, history entry, job, or external call is performed.
GET/api/documentsRead document templates, drafts, and versions
Link to this operation #

Read document templates, drafts, and versions

With workbookId returns templates/documents; with documentId returns {document}; adding version returns {version,snapshot}; recordSpaceId+recordId returns sourceRecord/documents.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
workbookIdqueryNoWorkbook to list when other selectors are absent.
documentIdqueryNoExisting document to inspect.
versionqueryNoVersion selector when documentId is present; an empty selector requests service default.
recordSpaceIdqueryNoSheet of a related record; required together with recordId.
recordIdqueryNoRelated record; required together with recordSpaceId.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Record selectors take precedence over document/workbook selection. Access is enforced for every requested resource.
POST/api/documentsManage document templates and drafts
Link to this operation #

Manage document templates and drafts

Dispatches save_template, create_draft, create_batch, save_draft, preview, finalize, or revise through the document service.

Authentication & access

Clerk session cookie or bearer JWT, or an explicit local session. Current workspace membership required; mutation commands require editing permission. Preview reads authorized workspace data.

Parameters

NameLocationRequiredDescription
actionbodyYessave_template | create_draft | create_batch | save_draft | preview | finalize | revise.
templatebodyNoRequired for save_template and preview; validated document template.
templateIdbodyNoRequired for create_draft/create_batch.
sourceItemId / sourceSpaceId / namebodyNoOptional draft context; accepted fields vary by action.
sourceItemIdsbodyNo1–100 IDs for create_batch; duplicate IDs are deduplicated.
documentId / revisionbodyNoRequired for save_draft/finalize/revise; revision is a positive document revision, not workspace expectedRevision.
layoutbodyNoRequired for save_draft.

Example request body

json
{
  "action": "finalize",
  "documentId": "document_example",
  "revision": 1
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 8 MiB. Template saving and draft/finalize changes require editing permission; record-bound drafts must pass service checks.
  • Returns {template}, {snapshot}, {document}, or {documents} according to action. Draft/batch creation returns HTTP 201.
  • Preview is not finalization; finalization preserves the resolved version and PDF.
POST/api/documents/planPlan a document template
Link to this operation #

Plan a document template

Produces {template} from a prompt and workbook context without saving the result.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions.

Parameters

NameLocationRequiredDescription
workbookIdbodyYesWorkbook identifier, up to 160 characters.
promptbodyYesNonempty prompt, up to 5,000 characters.
sourceSpaceIdbodyNoOptional source sheet ID.
templatebodyNoOptional existing validated template to refine.

Example request body

json
{
  "workbookId": "workbook_projects",
  "prompt": "Create a clear project summary with client and due date."
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 4,000,000 bytes. Permission is rechecked after planning. Invalid generated bindings return 422 invalid_document_plan.
GET/api/documents/{id}/pdfDownload a saved document PDF
Link to this operation #

Download a saved document PDF

Reads the authorized finalized version and returns its PDF bytes.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
versionqueryNoOptional version selector; omitted uses the service default.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Successful response is application/pdf with attachment disposition and private,no-store.
  • The downloaded filename derives from the document number and version. Errors remain JSON.
GET/api/workbook-templatesList saved workbook templates
Link to this operation #

List saved workbook templates

Returns {templates:[...]} for the selected workspace.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Example response

json
{
  "templates": []
}
POST/api/workbook-templatesSave a reusable workbook template
Link to this operation #

Save a reusable workbook template

Captures an existing workbook structure and document layouts without its business records, returning {template}.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. Owner/admin management permission is required.

Parameters

NameLocationRequiredDescription
workbookIdbodyYesExisting workbook to capture.
namebodyYesTrimmed name, 1–100 characters.
descriptionbodyNoDescription up to 1,000 characters; defaults empty.

Example request body

json
{
  "workbookId": "workbook_projects",
  "name": "Project delivery",
  "description": "Reusable project structure."
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Strict schema rejects extra keys. Maximum 100 reusable templates per workspace.
POST/api/workbook-templates/installPreview or install a saved template
Link to this operation #

Preview or install a saved template

Instantiates a saved template with chosen name and reuse mapping; preview:true returns the staged plan instead of installing.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. Owner/admin management permission is required.

Parameters

NameLocationRequiredDescription
templateIdbodyYesSaved template ID.
namebodyYesNew workbook name, 1–100 characters.
expectedRevisionbodyYesInteger workspace revision from the server-owned workspace or proposal being applied.
reusebodyNoString-to-string mapping of template sheet IDs to existing sheets; defaults {}.
requestIdbodyNo8–100 character deduplication identifier; required when preview is false.
previewbodyNoBoolean, default false.

Example request body

json
{
  "templateId": "template_example",
  "name": "New delivery workbook",
  "expectedRevision": 7,
  "preview": true
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Preview returns {workbookId,operations,installed:false}. Successful install returns {workbookId,installed:true}.
POST/api/templates/installInstall a reviewed built-in template
Link to this operation #

Install a reviewed built-in template

Installs a recognized built-in template from a validated reviewed operation batch and matching workspace revision.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. Owner/admin management permission is required.

Parameters

NameLocationRequiredDescription
templateIdbodyYesID from WORKSPACE_TEMPLATES; not an arbitrary user-supplied template name.
operationsbodyYes1–500 validated template operations including create_workbook.
expectedRevisionbodyYesInteger workspace revision from the server-owned workspace or proposal being applied.

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 4 MiB. Returns {workbookId,documentCount}. Billing template can include starter invoice/quote layouts.
  • Helpers installed through the validated template plan remain subject to template safety rules.
GET/api/teamRead team state
Link to this operation #

Read team state

Returns members, permitted invitations, activity, notifications, and presence.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Invitations are returned only to members with management access.
POST/api/teamManage invitations, members, or notifications
Link to this operation #

Manage invitations, members, or notifications

Dispatches invite, accept_invite, revoke_invite, update_member, remove_member, or read_notifications.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
actionbodyYesinvite | accept_invite | revoke_invite | update_member | remove_member | read_notifications.
email / role / sendEmailbodyNoFor invite: email and invitable role; optional boolean sendEmail.
tokenbodyNoFor accept_invite.
invitationIdbodyNoFor revoke_invite.
userId / rolebodyNoFor update_member; userId alone for remove_member.
idsbodyNoFor read_notifications: up to 100 notification IDs; omitted marks all own unread notifications.

Example request body

json
{
  "action": "read_notifications"
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 12,000 bytes. Invite/member management requires owner/admin; another admin’s role and the immutable owner have additional restrictions.
  • Invitable roles are admin, editor, viewer. Clerk invite acceptance requires a verified matching email.
  • Invite returns invitation, inviteToken, inviteUrl and optional emailDelivery with HTTP 201; acceptance returns sessionResponse; other actions return team state.
  • sendEmail must be explicitly true to queue a configured invitation email.
GET/api/commentsRead a record discussion
Link to this operation #

Read a record discussion

Returns {comments:[...]} for an accessible record.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
spaceIdqueryYesRecord sheet.
itemIdqueryYesRecord ID.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Example response

json
{
  "comments": []
}
POST/api/commentsAdd or delete a comment
Link to this operation #

Add or delete a comment

Adds a record comment/reply or deletes an authorized comment; returns {comments}.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
actionbodyYesadd | delete.
spaceId / itemId / bodybodyNoRequired for add; body is nonempty, up to 5,000 characters.
mentionsbodyNoOptional up to 25 current member IDs.
parentIdbodyNoOptional original comment ID for a reply on the same record.
commentIdbodyNoRequired for delete.

Example request body

json
{
  "action": "add",
  "spaceId": "sheet_projects",
  "itemId": "record_example",
  "body": "The launch checklist is ready for review."
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 15,000 bytes. Membership permits discussion, including viewers; deletion enforces author/moderation rights.
  • Add returns HTTP 201. Replies must target an original comment, not another reply.
GET/api/eventsPoll revision and presence
Link to this operation #

Poll revision and presence

Returns workspaceId, revision, presence, and unreadCount.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • This is a JSON polling endpoint, not an SSE event stream.
POST/api/eventsUpdate presence and read events
Link to this operation #

Update presence and read events

Saves the actor’s presence (optional sheet) and returns the same event snapshot.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
spaceIdbodyNoOptional current sheet identifier.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Example request body

json
{}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 1,024 bytes. This does not establish realtime cursor coauthoring.
GET/api/workflowsRead helper runs and workspace
Link to this operation #

Read helper runs and workspace

Returns {runs,workspace} for the selected workspace.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.
X-Ralti-Workspace-ModeheaderNoSet to paged to receive workspace metadata and bounded initial data rather than assuming every sheet is fully loaded.
POST/api/workflowsRun or review a helper
Link to this operation #

Run or review a helper

Runs a saved workflow/agent or applies/dismisses an existing run.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions.

Parameters

NameLocationRequiredDescription
actionbodyYesrun | apply | dismiss.
workflowIdbodyNoRequired for run.
runIdbodyNoRequired for apply or dismiss.
expectedRevisionbodyNoWorkspace revision used by the reviewed/run request; repository checks govern the action.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.
retryRunIdbodyNoOptional prior failed or pending-review legacy run to retry/refresh. It must belong to workflowId and remain authorized. Direct message ID arrays are rejected.

Example request body

json
{
  "action": "run",
  "workflowId": "workflow_example",
  "expectedRevision": 7
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Returns the helper/run service result; run is not equivalent to unconditional application. Scope, review mode, revision and role checks still apply.
GET/api/workflows/{id}/email-sourceRead an agent’s email grant
Link to this operation #

Read an agent’s email grant

Returns {source:null} when absent, or source configuration, grant identity/time, ownership, validity, and optional reason.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Example response

json
{
  "source": null
}

Behavior to know

  • ID must identify a saved agent. A grant can be invalid after behavioral edits, mailbox disconnection, or loss of the grantor’s access.
PUT/api/workflows/{id}/email-sourceGrant a scoped email source to an agent
Link to this operation #

Grant a scoped email source to an agent

Grants access to a saved agent from a connected mailbox owned by the grantor, after revision and editing checks.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions. Connected-mailbox operations are restricted to its owner; shared threads expose only explicitly shared content.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
configbodyYes{connectionId,folder,days,limit,sender,subject,unreadOnly}; folder inbox|sent, days 1|7|30|90, limit 1–25, text filters max 200 characters.
expectedRevisionbodyYesInteger workspace revision from the server-owned workspace or proposal being applied.

Example request body

json
{
  "config": {
    "connectionId": "mailbox_example",
    "folder": "inbox",
    "days": 7,
    "limit": 10,
    "sender": "",
    "subject": "Project",
    "unreadOnly": true
  },
  "expectedRevision": 7
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Behavior-changing agent edits require a fresh grant. This is separate from workspace email-thread sharing.
DELETE/api/workflows/{id}/email-sourceRevoke an agent’s email source
Link to this operation #

Revoke an agent’s email source

Revokes the source under service ownership/management checks and returns {source:null}.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.

Example response

json
{
  "source": null
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
GET/api/emailRead the email dashboard
Link to this operation #

Read the email dashboard

Returns provider availability, categories/categoryRevision, connections, counts/metrics, visible threads, draft summaries, and bounded page data.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
connectionIdqueryNoLimit to one accessible mailbox.
folderqueryNoinbox | sent | awaiting_reply | drafts | unread | starred | archive | trash.
categoryqueryNoCategory ID or uncategorized; category filtering is owner-only.
spaceIdqueryNoLinked record sheet filter.
itemIdqueryNoLinked record filter.
queryqueryNoSearch matching latest-message subject/preview/participant text.
cursorqueryNoEmail page cursor.
limitqueryNoThread-page requested size; /threads clamps to 1–50, default 30.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Private mail remains owned by the connecting actor. Explicitly shared linked threads are visible to authorized workspace members.
  • Provider OAuth credentials and remote sync cursors are never returned.
GET/api/email/threadsPage visible email threads
Link to this operation #

Page visible email threads

Returns {threads,filteredCount?,nextCursor?}.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
connectionIdqueryNoLimit to one accessible mailbox.
folderqueryNoinbox | sent | awaiting_reply | drafts | unread | starred | archive | trash.
categoryqueryNoCategory ID or uncategorized; category filtering is owner-only.
spaceIdqueryNoLinked record sheet filter.
itemIdqueryNoLinked record filter.
queryqueryNoSearch matching latest-message subject/preview/participant text.
cursorqueryNoEmail page cursor.
limitqueryNoThread-page requested size; /threads clamps to 1–50, default 30.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Example response

json
{
  "threads": [],
  "filteredCount": 0
}

Behavior to know

  • Cursor is an offset string for email, unlike revision-bound record cursors; it must be an integer from 0 to 100,000.
  • folder=drafts returns an empty thread list; drafts have a separate endpoint.
GET/api/email/threads/{id}Read a conversation
Link to this operation #

Read a conversation

Returns {thread,messages,nextCursor?} after private/shared conversation authorization.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
cursorqueryNoOptional next message-page cursor.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Only synchronized, visible messages are included. A shared thread does not confer general mailbox access.
PATCH/api/email/threads/{id}Link or share a conversation
Link to this operation #

Link or share a conversation

Mailbox owner updates a record link and private/workspace visibility; returns the thread detail.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions. Connected-mailbox operations are restricted to its owner; shared threads expose only explicitly shared content.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
linkbodyNo{spaceId,itemId} or null; referenced record must be accessible.
visibilitybodyNoprivate | workspace.
sharedbodyNoLegacy boolean alternative when visibility is omitted.

Example request body

json
{
  "link": {
    "spaceId": "sheet_clients",
    "itemId": "record_example"
  },
  "visibility": "workspace"
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • A conversation must link to a CRM record before workspace sharing is allowed.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
PATCH/api/email/threads/{id}/actionsOrganize an email conversation
Link to this operation #

Organize an email conversation

Performs one supported owner action and returns updated thread detail.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions. Connected-mailbox operations are restricted to its owner; shared threads expose only explicitly shared content.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
actionbodyYesread | unread | star | unstar | archive | trash | restore | categorize.
categorybodyNoCategory ID or null; only accepted with categorize.

Example request body

json
{
  "action": "read"
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Provider capability checks can return 422 email_capability_unavailable. Mailbox sync contention can return 409 email_sync_busy.
  • categorize updates local classification; other actions require a connected capable mailbox.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
POST/api/email/syncSynchronize a connected mailbox
Link to this operation #

Synchronize a connected mailbox

Runs synchronization for the requested owned connection and returns its service result.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions. Connected-mailbox operations are restricted to its owner; shared threads expose only explicitly shared content.

Parameters

NameLocationRequiredDescription
connectionIdbodyYesConnected mailbox identifier.

Example request body

json
{
  "connectionId": "mailbox_example"
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Sync leases and provider capability/configuration apply; a request does not grant another actor access to the mailbox.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
DELETE/api/email/connections/{id}Disconnect a mailbox
Link to this operation #

Disconnect a mailbox

Disconnects an owned connection and returns {disconnected:true}.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions. Connected-mailbox operations are restricted to its owner; shared threads expose only explicitly shared content.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.

Example response

json
{
  "disconnected": true
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
PATCH/api/email/connections/{id}/sortingConfigure incoming email sorting
Link to this operation #

Configure incoming email sorting

Updates owned mailbox sorting and returns its public EmailConnection.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions. Connected-mailbox operations are restricted to its owner; shared threads expose only explicitly shared content.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
enabledbodyYesBoolean sorting state.
instructionsbodyNoOptional text up to 1,000 characters.

Example request body

json
{
  "enabled": true,
  "instructions": "Prioritize direct customer questions."
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Strict input accepts only enabled and instructions. Automatic classification still depends on a configured provider and background processing.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
POST/api/email/google/authorizeBegin Google authorization
Link to this operation #

Begin Google authorization

Creates a short-lived OAuth flow for an editing account and returns {url} for browser navigation.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions.

Example request body

json
{}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • The browser Origin must also match the configured provider callback origin; mismatch returns 409 email_origin_mismatch.
  • Google requires an empty JSON object. Microsoft optionally accepts sharedMailbox. Store provider consent state on the server; do not construct your own callback code/state.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
GET/api/email/google/callbackComplete Google authorization
Link to this operation #

Complete Google authorization

Consumes the provider code/state for the signed-in user and redirects back to the application email page.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
codequeryNoOAuth authorization code returned by the provider.
statequeryNoServer-issued OAuth state returned by the provider.
errorqueryNoProvider-declared consent failure/cancellation.

Behavior to know

  • Success and failure both return HTTP 303 redirects, not the normal JSON response.
  • The destination includes page=email, emailProvider, and either email=connected with workspace/emailConnection or email=error with a bounded error code.
  • This route is called by the provider authorization flow, not by an integration inventing codes.
POST/api/email/microsoft/authorizeBegin Microsoft authorization
Link to this operation #

Begin Microsoft authorization

Creates a short-lived OAuth flow for an editing account and returns {url} for browser navigation.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions.

Parameters

NameLocationRequiredDescription
sharedMailboxbodyNoOptional shared mailbox email address.

Example request body

json
{}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • The browser Origin must also match the configured provider callback origin; mismatch returns 409 email_origin_mismatch.
  • Google requires an empty JSON object. Microsoft optionally accepts sharedMailbox. Store provider consent state on the server; do not construct your own callback code/state.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
GET/api/email/microsoft/callbackComplete Microsoft authorization
Link to this operation #

Complete Microsoft authorization

Consumes the provider code/state for the signed-in user and redirects back to the application email page.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
codequeryNoOAuth authorization code returned by the provider.
statequeryNoServer-issued OAuth state returned by the provider.
errorqueryNoProvider-declared consent failure/cancellation.

Behavior to know

  • Success and failure both return HTTP 303 redirects, not the normal JSON response.
  • The destination includes page=email, emailProvider, and either email=connected with workspace/emailConnection or email=error with a bounded error code.
  • This route is called by the provider authorization flow, not by an integration inventing codes.
POST/api/email/imap/connectConnect an IMAP/SMTP mailbox
Link to this operation #

Connect an IMAP/SMTP mailbox

Validates mailbox credentials, verifies provider connectivity, and returns {connection,workspaceId}.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions.

Parameters

NameLocationRequiredDescription
addressbodyYesMailbox email address.
usernamebodyNoDefaults to address when omitted/empty.
passwordbodyYesMailbox app password; never log or return it.
displayNamebodyNoOptional name, at most 150 characters.
imapbodyYes{host,port,secure}: 993/true or 143/false (required STARTTLS).
smtpbodyYes{host,port,secure}: 465/true or 587/false (required STARTTLS).

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 20,000 bytes. Host/DNS network safeguards apply. Credentials are encrypted server-side; response settings omit the password.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
GET/api/email/categoriesRead personal mailbox categories
Link to this operation #

Read personal mailbox categories

Returns {categories,revision} for the actor in this workspace.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.
PUT/api/email/categoriesReplace personal mailbox categories
Link to this operation #

Replace personal mailbox categories

Saves the complete category list with its category-specific revision and returns categories, revision, and clearedThreads.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions.

Parameters

NameLocationRequiredDescription
categoriesbodyYesUp to 30 {id,name,color,description} objects; IDs/names unique, reserved uncategorized ID prohibited.
expectedRevisionbodyYesCurrent category revision (not the workspace revision).

Example request body

json
{
  "categories": [
    {
      "id": "client_requests",
      "name": "Client requests",
      "color": "blue",
      "description": "Questions and requests from current clients."
    }
  ],
  "expectedRevision": 0
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Category name max 48, description max 500; colors use the shared OptionColor enum.
  • Stale category revisions return 409 email_categories_conflict. Removed categories can clear existing thread classifications.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
POST/api/email/categories/planPlan a category setup
Link to this operation #

Plan a category setup

Builds a reviewed category proposal without changing saved categories or reading mailbox message content.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions.

Parameters

NameLocationRequiredDescription
requestbodyYesNonempty prompt, up to 4,000 characters.
baseRevisionbodyYesCurrent category revision.
conversationbodyNoUp to 10 {role:user|assistant,content} turns; content up to 6,000 chars.
draftbodyNoOptional existing category-array draft.

Example request body

json
{
  "request": "Separate client questions from newsletters.",
  "baseRevision": 0
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 90,000 bytes. Categories are checked again after planning; stale state returns email_categories_stale.
  • Applying a plan uses PUT /api/email/categories with the reviewed category revision.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
GET/api/email/preferencesRead notification preferences
Link to this operation #

Read notification preferences

Returns preferences, notificationSender, canManageNotifications, and delivery counts.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Preferences are per user/workspace. Sender and delivery visibility respect workspace management access.
PATCH/api/email/preferencesUpdate notification preferences or sender
Link to this operation #

Update notification preferences or sender

Updates personal boolean preferences and/or the workspace notification mailbox, then returns settings.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
preferencesbodyNoOptional subset of enabled, assignments, mentions, replies, salesReplies, workflows; every supplied value is boolean.
notificationSenderbodyNoOptional {connectionId:string|null}; owner/admin access and owned capable mailbox required.

Example request body

json
{
  "preferences": {
    "enabled": true,
    "mentions": true
  }
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 4,096 bytes. At least one supported top-level key is required.
  • Enabling notification email requires a verified recipient account email.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
GET/api/email/draftsList private email drafts
Link to this operation #

List private email drafts

Returns {drafts:[...]} for this actor/workspace.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Example response

json
{
  "drafts": []
}
POST/api/email/draftsCreate a private email draft
Link to this operation #

Create a private email draft

Creates or deduplicates a draft for an owned connected mailbox and returns EmailDraft with HTTP 201.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions. Connected-mailbox operations are restricted to its owner; shared threads expose only explicitly shared content.

Parameters

NameLocationRequiredDescription
connectionIdbodyYesOwned connected mailbox ID.
clientRequestIdbodyYesDeduplication ID used for draft creation.
tobodyYesArray of {address,name?} recipients.
cc / bccbodyNoOptional address arrays; total recipients at most 100.
subjectbodyYesPlain subject, max 998 characters, no newlines.
bodyTextbodyYesPlain text body, max 200,000 characters.
linkbodyNoOptional {spaceId,itemId} record link.
replyToMessageIdbodyNoOptional visible message ID from the same connection.

Example request body

json
{
  "connectionId": "mailbox_example",
  "clientRequestId": "example_draft_0001",
  "to": [
    {
      "address": "recipient@example.com"
    }
  ],
  "subject": "Project update",
  "bodyText": "Here is the update for your review."
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • This only saves a draft. Reusing the creation ID with different content returns a conflict.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
GET/api/email/drafts/{id}Read a private email draft
Link to this operation #

Read a private email draft

Returns EmailDraft for its creating actor in this workspace.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • EmailDraft fields include id, connectionId, recipients, subject, bodyText, status, createdAt, updatedAt, and optional sentAt/link/replyToMessageId/error.
PATCH/api/email/drafts/{id}Edit an unsent draft
Link to this operation #

Edit an unsent draft

Merges provided draft fields with the original and returns the updated EmailDraft.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions. Connected-mailbox operations are restricted to its owner; shared threads expose only explicitly shared content.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
to / cc / bcc / subject / bodyText / link / replyToMessageIdbodyNoOptional replacements using the same draft validation.

Example request body

json
{
  "bodyText": "Updated project summary for review."
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Only draft/failed statuses are editable. A draft cannot move to another mailbox.
  • Concurrent changes can return 409 email_draft_changed. Sending uses the latest returned updatedAt as explicit review proof.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
DELETE/api/email/drafts/{id}Discard an unsent draft
Link to this operation #

Discard an unsent draft

Deletes a draft or failed message and returns {deleted:true}.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions. Connected-mailbox operations are restricted to its owner; shared threads expose only explicitly shared content.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.

Example response

json
{
  "deleted": true
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Queued, sending, sent, or uncertain delivery states cannot be discarded with this endpoint.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
POST/api/email/drafts/{id}/sendQueue an explicitly reviewed message
Link to this operation #

Queue an explicitly reviewed message

Queues one reviewed draft for durable delivery and returns EmailDraft with HTTP 202.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions. Connected-mailbox operations are restricted to its owner; shared threads expose only explicitly shared content.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
confirmedbodyYesMust be true after reviewing actual recipients and content.
clientRequestIdbodyYesUnique send deduplication identifier.
expectedUpdatedAtbodyYesExact updatedAt of the draft that was reviewed.

Example request body

json
{
  "confirmed": true,
  "clientRequestId": "example_send_0001",
  "expectedUpdatedAt": "2026-01-01T12:00:00.000Z"
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • HTTP 202 is queued, not proof of delivery. Inspect status until sent/failed/unknown.
  • Same send ID is deduplicated. Stale draft versions return email_draft_changed; already queued/sent/uncertain messages are not automatically resent.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
POST/api/email/drafts/{id}/reconcileReconcile an uncertain delivery
Link to this operation #

Reconcile an uncertain delivery

Checks provider evidence for an owned draft whose delivery outcome needs resolution and returns the updated draft.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. The requested write must also pass editing and operation-specific permissions. Connected-mailbox operations are restricted to its owner; shared threads expose only explicitly shared content.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • No JSON request body is required. Reconciliation is not an instruction to send the message again.
  • Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.
GET/api/forms/{workspaceId}/{viewId}Read a published form
Link to this operation #

Read a published form

Returns {form} only when the supplied capability identifies a currently published form.

Authentication & access

Published-form capability in x-ralti-form-key. No signed-in account is required; the form must still be published and its capability valid.

Parameters

NameLocationRequiredDescription
workspaceIdpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
viewIdpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
x-ralti-form-keyheaderYes64 lowercase hexadecimal characters from the published form capability.

Behavior to know

  • Invalid/unpublished form capabilities return 404 without revealing the workspace.
  • Response includes no-store and Referrer-Policy:no-referrer. The capability must not be exposed in shared logs.
POST/api/forms/{workspaceId}/{viewId}Submit a published form
Link to this operation #

Submit a published form

Validates the form fields and creates its record atomically under the published-form capability.

Authentication & access

Published-form capability in x-ralti-form-key. No signed-in account is required; the form must still be published and its capability valid.

Parameters

NameLocationRequiredDescription
workspaceIdpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
viewIdpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.
x-ralti-form-keyheaderYesValid published-form capability.
submissionIdbodyYesUUID-shaped stable submission identifier; reusing it deduplicates a retry.
valuesbodyYesField-ID keyed values accepted by this published form.

Example request body

json
{
  "submissionId": "00000000-0000-4000-8000-000000000001",
  "values": {
    "field_name": "Example request"
  }
}

Example response

json
{
  "success": true,
  "message": "Thank you for your response."
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 128 KiB. First successful creation returns 201; an already recorded submission returns 200. Actual success message comes from the form definition.
  • Field validation failures return 422. The server retries up to three revision attempts; the caller does not supply workspace expectedRevision.
GET/api/mcp/connectionsList personal MCP connections
Link to this operation #

List personal MCP connections

Returns {connections:[...]} for this signed-in actor and workspace; token secret is never listed.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. A registered/non-guest account is required.

Parameters

NameLocationRequiredDescription
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Example response

json
{
  "connections": []
}
POST/api/mcp/connectionsIssue a scoped MCP connection
Link to this operation #

Issue a scoped MCP connection

Creates a personal connection and returns {connection,token} with HTTP 201. The token is shown only at creation.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. Registered account required; drafts:propose also requires editing permission.

Parameters

NameLocationRequiredDescription
namebodyYesTrimmed connection name, 1–80 characters.
scopesbodyYesNonempty array: records:read, email:read, drafts:propose.
daysbodyYesExpiration: 7, 30, or 90.

Example request body

json
{
  "name": "Example research connection",
  "scopes": [
    "records:read"
  ],
  "days": 7
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Body limit: 8,192 bytes. drafts:propose also requires records:read. Maximum 25 active connections per actor.
  • Store the returned token securely. Do not substitute a Clerk session token when calling /api/mcp.
DELETE/api/mcp/connections/{id}Revoke a personal MCP connection
Link to this operation #

Revoke a personal MCP connection

Revokes an actor-owned connection in the selected workspace and returns {revoked:true}.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. Registered/non-guest account required.

Parameters

NameLocationRequiredDescription
idpathYesIdentifier supplied by the corresponding Ralti resource; examples use synthetic IDs.

Example response

json
{
  "revoked": true
}

Behavior to know

  • Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
  • Revocation is checked before and after tool operations; it does not delete already saved workspace data.
POST/api/mcpUse the MCP protocol transport
Link to this operation #

Use the MCP protocol transport

Delegates to the MCP SDK transport with stateless and legacy-stateless protocol handling. Use an MCP client; this is not a conventional resource CRUD endpoint.

Authentication & access

Authorization: Bearer <Ralti MCP connection token>. This is a separately issued rlt_mcp_ credential bound to one actor/workspace and scopes, not a Clerk/local session.

Parameters

NameLocationRequiredDescription
AuthorizationheaderYesBearer credential returned once by POST /api/mcp/connections.

Behavior to know

  • The route explicitly exposes this HTTP method; the SDK decides which protocol requests are supported and may reject an incompatible method/request.
  • Maximum request body: 1 MiB. Host/origin validation and HTTPS for external origins are enforced before token use.
  • Responses follow MCP/JSON-RPC, with transport-negotiated response handling; do not assume the normal {error,code} envelope.
  • Authentication errors use JSON-RPC error code -32001 and 401 includes WWW-Authenticate. Earlier origin/host guards may return their own error shape.
  • records:read and email:read expose only the corresponding bounded tools. drafts:propose can validate/save reviewed drafts; no tool applies changes, sends email, or executes arbitrary SQL.
GET/api/mcpUse the MCP protocol transport
Link to this operation #

Use the MCP protocol transport

Delegates to the MCP SDK transport with stateless and legacy-stateless protocol handling. Use an MCP client; this is not a conventional resource CRUD endpoint.

Authentication & access

Authorization: Bearer <Ralti MCP connection token>. This is a separately issued rlt_mcp_ credential bound to one actor/workspace and scopes, not a Clerk/local session.

Parameters

NameLocationRequiredDescription
AuthorizationheaderYesBearer credential returned once by POST /api/mcp/connections.

Behavior to know

  • The route explicitly exposes this HTTP method; the SDK decides which protocol requests are supported and may reject an incompatible method/request.
  • Maximum request body: 1 MiB. Host/origin validation and HTTPS for external origins are enforced before token use.
  • Responses follow MCP/JSON-RPC, with transport-negotiated response handling; do not assume the normal {error,code} envelope.
  • Authentication errors use JSON-RPC error code -32001 and 401 includes WWW-Authenticate. Earlier origin/host guards may return their own error shape.
  • records:read and email:read expose only the corresponding bounded tools. drafts:propose can validate/save reviewed drafts; no tool applies changes, sends email, or executes arbitrary SQL.
DELETE/api/mcpUse the MCP protocol transport
Link to this operation #

Use the MCP protocol transport

Delegates to the MCP SDK transport with stateless and legacy-stateless protocol handling. Use an MCP client; this is not a conventional resource CRUD endpoint.

Authentication & access

Authorization: Bearer <Ralti MCP connection token>. This is a separately issued rlt_mcp_ credential bound to one actor/workspace and scopes, not a Clerk/local session.

Parameters

NameLocationRequiredDescription
AuthorizationheaderYesBearer credential returned once by POST /api/mcp/connections.

Behavior to know

  • The route explicitly exposes this HTTP method; the SDK decides which protocol requests are supported and may reject an incompatible method/request.
  • Maximum request body: 1 MiB. Host/origin validation and HTTPS for external origins are enforced before token use.
  • Responses follow MCP/JSON-RPC, with transport-negotiated response handling; do not assume the normal {error,code} envelope.
  • Authentication errors use JSON-RPC error code -32001 and 401 includes WWW-Authenticate. Earlier origin/host guards may return their own error shape.
  • records:read and email:read expose only the corresponding bounded tools. drafts:propose can validate/save reviewed drafts; no tool applies changes, sends email, or executes arbitrary SQL.
GET/api/healthCheck process liveness
Link to this operation #

Check process liveness

Returns {status:"ok"} without contacting the database or an external provider.

Authentication & access

Public; bypasses Clerk middleware.

Example response

json
{
  "status": "ok"
}

Behavior to know

  • Response is no-store and nosniff. HTTP 200 does not establish database, worker, OAuth, or provider readiness.
GET/api/flowsRead visual flows, published versions, and runs
Link to this operation #

Read visual flows, published versions, and runs

Without selectors returns {flows,runs,nextCursor,attentionRuns,attentionCount}. With flowId returns {flow,versions}; with runId returns {run,access}; with resources=1 returns document/report/helper/mailbox choices.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
workbookIdqueryNoOptional workbook scope for the collection.
beforequeryNoOpaque nextCursor from the previous run-history page; up to 100 runs per page.
flowId / versionIdqueryNoChoose a flow; optional versionId selects its immutable published definition.
runIdqueryNoSaved run including its pinned definition and per-node checkpoints, filtered by current permissions.
resourcesqueryNoSet to 1 for authorized editor resource metadata. Takes precedence over runId, then flowId, then collection.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Flow and run summaries omit full execution payloads. attentionRuns includes up to 100 review/failed runs independently of history pagination; attentionCount reports the total.
  • Private-source details and available approval/retry actions are checked against current permissions.
  • An installation missing report/flow tables returns 503 database_upgrade_required; an empty installed library succeeds.
POST/api/flowsSave, publish, preview, run, and review visual flows
Link to this operation #

Save, publish, preview, run, and review visual flows

Dispatches graph lifecycle and run-control actions. save/set_enabled/import_helper return {flow}; publish returns {flow,version}; preview returns {run,mode:"preview"}; run/approve/retry/cancel/dismiss return {run,access}; delete returns {deleted:true}.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. Mutation commands require editing permission and current source access; preview is read-only.

Parameters

NameLocationRequiredDescription
actionbodyYessave | publish | set_enabled | preview | run | approve | dismiss | cancel | retry | delete | import_helper.
definitionbodyNoFlowDefinition required for save or preview.
flowId / revisionbodyNoflowId for publish/set_enabled/run/delete; current flow revision required except run.
enabledbodyNoBoolean required for set_enabled.
inputbodyNoOptional run/preview trigger envelope. User JSON belongs under input, for example {event:"manual",input:{customerId:"record_id"}}.
runId / nodeId / revisionbodyNoRun controls require runId; approve also requires nodeId and current run revision; retry requires nodeId. dismiss with nodeId+revision rejects that review; otherwise dismiss cancels the run.
decisionbodyNoapprove accepts approved or rejected; defaults to approved.
workflowId / workbookIdbodyNoLegacy workflowId required for import_helper; workbookId optionally chooses its draft scope.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Browser POST requests require an exact matching Origin. Native bearer requests may omit Origin; a supplied mismatched Origin is rejected.
  • Body limit 4MiB. Editing commands check workspace access, archived scopes, and applicable definition/run revisions.
  • Publishing creates an immutable executable version and activates the configured trigger, including when republishing a paused flow. Editing its draft does not alter existing runs.
  • run returns 201 with a durable queued run; background execution may pause for approval or a deadline. import_helper returns 201 and creates only a draft.
  • Preview evaluates authorized data and proposed record changes in memory; it does not call AI, send webhooks, persist business changes, or claim unsupported downstream results.
  • Retry resumes an eligible failed step without rerunning completed steps. Completed effects are preserved when a run is cancelled. Uncertain webhook outcomes cannot be blindly retried.
POST/api/flows/draftDraft or revise a visual flow with AI
Link to this operation #

Draft or revise a visual flow with AI

Returns {definition,summary,issues} for review in the studio. The proposal does not save, publish, enable, or run the graph.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. Mutation commands require editing permission and current source access; preview is read-only.

Parameters

NameLocationRequiredDescription
promptbodyYesNonempty instructions, maximum8,000 characters.
workbookIdbodyNoOptional authorized workbook context.
definitionbodyNoOptional current FlowDefinition to revise; must agree with workbookId when both are supplied.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Browser POST requests require an exact matching Origin. Native bearer requests may omit Origin; a supplied mismatched Origin is rejected.
  • Requires editing permission and a configured AI provider. Body limit 4,000,000 bytes. Unknown request properties are rejected.
  • The draft uses actual accessible resource IDs and canonical node schemas; incomplete required setup is returned as issues.
GET/api/reportsRead business report definitions and saved versions
Link to this operation #

Read business report definitions and saved versions

Without selectors returns {reports,runs} summaries. reportId returns {report}; runId returns {run}, including the immutable report definition and result snapshot.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
workbookIdqueryNoOptional workbook scope for summary lists.
reportIdqueryNoSaved editable report definition.
runIdqueryNoSaved generated version; takes precedence over reportId.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Report summaries omit imported rows and notes. These business reports are separate from dashboard InsightDocuments.
POST/api/reportsPreview, save, generate, or delete a business report
Link to this operation #

Preview, save, generate, or delete a business report

preview returns {result,workspaceRevision}; save returns {report}; generate returns201 {run}; delete returns {deleted:true}.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. Mutation commands require editing permission and current source access; preview is read-only.

Parameters

NameLocationRequiredDescription
actionbodyYespreview | save | generate | delete.
definitionbodyNoReportDefinition required for preview/save; includes report kind, period, currency, source, notes, and current definition revision.
reportId / revisionbodyNoRequired for generate/delete; revision is the current report-definition revision.
expectedWorkspaceRevisionbodyNoRequired for generate; use the revision returned by the reviewed preview. Source changes invalidate generation.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Browser POST requests require an exact matching Origin. Native bearer requests may omit Origin; a supplied mismatched Origin is rejected.
  • Body limit 8MiB. Preview requires workspace membership; save/generate/delete require editing permission and an active source scope.
  • Generation computes from authorized server data and saves immutable definition/result/PDF snapshots. Deleting a definition preserves generated versions.
  • Financial statement imports retain explicit currency, accounting basis and reporting periods; invalid or inconsistent sources block generation.
GET/api/reports/exportDownload a saved report as PDF or CSV
Link to this operation #

Download a saved report as PDF or CSV

Returns the full saved report version as an attachment, preserving its definition, totals, and source snapshot.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
runIdqueryYesID of a generated report version.
formatqueryYespdf | csv.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • PDF exports paginate the complete report; CSV exports include report metadata, sections and totals. Exports require current workspace access and use private,no-store caching.
GET/api/workflows/historyBrowse existing helper history
Link to this operation #

Browse existing helper history

Returns {workspaceId,runs,total,filteredTotal,counts,summaries,nextCursor?} with authorized result projections and per-helper activity summaries.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
workbookId / workflowIdqueryNoOptional workbook/helper filters. workbookId defaults to all.
statusqueryNoOptional legacy run status: running | review | applied | no_changes | failed | dismissed.
qqueryNoSearch helper names and run IDs; excludes private result payloads.
from / toqueryNoOptional ISO timestamps or YYYY-MM-DD dates; calendar dates use UTC day boundaries.
limitqueryNoInteger1–50; defaults to30.
cursorqueryNoOpaque nextCursor tied to the same filters and workspace.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Uses cursor pagination rather than the bounded legacy /api/workflows list. Totals and pending-review summaries cover the entire selected workbook.
GET/api/workflows/runs/{runId}Inspect an existing helper run
Link to this operation #

Inspect an existing helper run

Returns {run} with recorded execution/review metadata, authorized result content, and access flags.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
runIdpathYesExisting legacy helper run ID.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Current source visibility is rechecked. Revoked private access hides derived summaries, proposals, errors, and citations while preserving safe status metadata.
GET/api/workflows/{id}/readinessCheck an existing helper’s setup
Link to this operation #

Check an existing helper’s setup

Returns {source,connections,readiness}; readiness includes ready and actionable issues.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.

Parameters

NameLocationRequiredDescription
idpathYesExisting legacy helper workflow ID.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Checks actual source configuration and authorization. No matching synchronized mail is distinguished from a disconnected or unapproved mailbox.
POST/api/workflows/configureSave an existing helper and optional mailbox grant
Link to this operation #

Save an existing helper and optional mailbox grant

Atomically validates and saves the helper and any explicit owner mailbox grant. Returns {workspace,source,connections,readiness}.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. Mutation commands require editing permission and current source access; preview is read-only.

Parameters

NameLocationRequiredDescription
expectedRevisionbodyYesCurrent nonnegative workspace revision.
workflowbodyYesComplete legacy Workflow configuration.
emailSourcebodyNoOptional {config,consent:true} for the connecting mailbox owner’s explicit grant; applies only to email-capable helpers.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Browser POST requests require an exact matching Origin. Native bearer requests may omit Origin; a supplied mismatched Origin is rejected.
  • Body limit 256KiB. Editing permission required. A saved helper cannot change kind or destination sheet; create a new helper instead.
  • Enabled helpers must pass readiness checks. Failed validation rolls back both configuration and grant.
POST/api/workflows/email-previewPreview a bounded mailbox selection for a helper
Link to this operation #

Preview a bounded mailbox selection for a helper

Returns matchedCount,truncated,lastSyncedAt,messages and limits for the proposed owner-authorized source.

Authentication & access

Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked. Mutation commands require editing permission and current source access; preview is read-only.

Parameters

NameLocationRequiredDescription
configbodyYesValidated AgentEmailSourceConfig selecting the owner’s mailbox and bounded filters.
X-Atlas-WorkspaceheaderNoOptional workspace ID. Selects scope; never grants access. Omit to use the account preference.

Behavior to know

  • Browser POST requests require an exact matching Origin. Native bearer requests may omit Origin; a supplied mismatched Origin is rejected.
  • Body limit 8KiB; config is the only accepted property. Requires a signed-in non-guest editor who owns the connected mailbox.
  • Returns at most 5 previews with subject/sender/date and at most 600 body characters each; does not send mail or persist a grant.
DELETE/api/apps/{workspaceId}/{appId}/files/{id}Delete a pending app upload
Link to this operation #

Delete a pending app upload

The shared app-file gateway checks the exact app, release, principal, and input/field scope before the operation.

Authentication & access

Signed-in app participant or a valid app-scoped embed session. Current app publication, grants, field scope, and record assignments are checked.

Parameters

NameLocationRequiredDescription
workspaceIdpathYesExact workspaceId from the authorized application context; it does not grant access.
appIdpathYesExact appId from the authorized application context; it does not grant access.
idpathYesExact id from the authorized application context; it does not grant access.

Behavior to know

  • Public file operations require the secure form session; pending uploads cannot be claimed by another participant.
DELETE/api/public/apps/{workspaceId}/{appId}/files/{id}Delete a pending app upload
Link to this operation #

Delete a pending app upload

The shared app-file gateway checks the exact app, release, principal, and input/field scope before the operation.

Authentication & access

Published public app policy and, where required, an app-bound resume or embed-exchange session. Public intake never grants workspace membership.

Parameters

NameLocationRequiredDescription
workspaceIdpathYesExact workspaceId from the authorized application context; it does not grant access.
appIdpathYesExact appId from the authorized application context; it does not grant access.
idpathYesExact id from the authorized application context; it does not grant access.

Behavior to know

  • Public file operations require the secure form session; pending uploads cannot be claimed by another participant.
GET/api/account/ai-permissionRead AI processing permissions
Link to this operation #

Read AI processing permissions

Reads or changes the account/workspace AI permission state through the account-principal boundary and current authorization.

Authentication & access

Authenticated account principal through the route-specific permission or deletion boundary; current action authorization applies.

Behavior to know

  • A permission decision is separate from app role membership, mailbox grants, and connection delegation.
GET/api/account/deletionRead the current account deletion status
Link to this operation #

Read the current account deletion status

Uses the authenticated deletion-principal boundary. POST validates a deletion request and returns202 after admission to the durable deletion process.

Authentication & access

Authenticated account principal through the route-specific permission or deletion boundary; current action authorization applies.

Behavior to know

  • A202 response is acceptance, not a claim that all provider work has already completed. Use the account UI and current status; do not replay destructive requests blindly.
GET/api/agentsList agent members or read an authorized profile
Link to this operation #

List agent members or read an authorized profile

GET returns the authorized directory, profile, run, or readiness information selected by the request. POST dispatches typed preview, create/update, lifecycle, ownership, responsibility, review, memory, mailbox-grant, or reconciliation actions.

Authentication & access

Authenticated application session. The handler and domain service enforce the current actor, workspace, role, source access, and action-specific requirements; writes retain origin validation.

Behavior to know

  • Human authority is required; this route does not give an agent an interactive login. Creation saves paused. Exact proposals and current-source checks still govern effects.
GET/api/ai-jobs/{id}/documentsRead a job’s document previews
Link to this operation #

Read a job’s document previews

Returns document previews attached to the authenticated actor’s saved AI job in the current workspace.

Authentication & access

Authenticated application session. The handler and domain service enforce the current actor, workspace, role, source access, and action-specific requirements; writes retain origin validation.

Parameters

NameLocationRequiredDescription
idpathYesExact id from the authorized application context; it does not grant access.

Behavior to know

  • A preview does not finalize or send a document.
GET/api/appsList apps or read an app definition
Link to this operation #

List apps or read an app definition

Builder operations include create/save, legacy-form adaptation, journey creation, publish/restore, enable/pause, invitation, and revocation. Management authority is required for publication and audience changes.

Authentication & access

Authenticated application session. The handler and domain service enforce the current actor, workspace, role, source access, and action-specific requirements; writes retain origin validation.

Behavior to know

  • Draft editing is separate from publication. A restore creates a validated release rather than undoing submitted records or completed actions.
GET/api/apps/groupsRead app audience groups
Link to this operation #

Read app audience groups

Manages group policy, membership, invitations, and invitation revocation for the selected app. Group access remains app-specific and does not create workspace membership.

Authentication & access

Authenticated application session. The handler and domain service enforce the current actor, workspace, role, source access, and action-specific requirements; writes retain origin validation.

Behavior to know

  • Current workspace management permission and the app policy govern group administration.
GET/api/apps/{workspaceId}/{appId}Read an authorized participant app
Link to this operation #

Read an authorized participant app

Returns the scoped published experience and allowed choices without a workspace snapshot.

Authentication & access

Signed-in app participant or a valid app-scoped embed session. Current app publication, grants, field scope, and record assignments are checked.

Parameters

NameLocationRequiredDescription
workspaceIdpathYesExact workspaceId from the authorized application context; it does not grant access.
appIdpathYesExact appId from the authorized application context; it does not grant access.

Behavior to know

  • Anonymous public access creates records only on final submission; existing-record updates and business-process tasks require the appropriate authenticated app authority.
GET/api/apps/{workspaceId}/{appId}/files/{id}Download an authorized app file
Link to this operation #

Download an authorized app file

The shared app-file gateway checks the exact app, release, principal, and input/field scope before the operation.

Authentication & access

Signed-in app participant or a valid app-scoped embed session. Current app publication, grants, field scope, and record assignments are checked.

Parameters

NameLocationRequiredDescription
workspaceIdpathYesExact workspaceId from the authorized application context; it does not grant access.
appIdpathYesExact appId from the authorized application context; it does not grant access.
idpathYesExact id from the authorized application context; it does not grant access.

Behavior to know

  • Public file operations require the secure form session; pending uploads cannot be claimed by another participant.
GET/api/integrationsRead integration connections and sources
Link to this operation #

Read integration connections and sources

Reads connections and sources and dispatches supported reviewed preparation, preview, pause, disconnect, synchronization, or reconciliation operations.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Source adapters and admitted transports determine availability. This does not promise universal sync support.
GET/api/integrations/accessRead integration access status
Link to this operation #

Read integration access status

Reports private-preview eligibility and current workspace admission. POST records the explicit permissions acknowledgment against the expected epoch.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Ordinary application access does not bypass integration admission.
GET/api/integrations/accountsList saved owned-account verification
Link to this operation #

List saved owned-account verification

GET reads the saved account inventory without provider requests. POST performs an explicit check or removal for an opaque accountAlias with confirmed:true.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • A check reads account metadata, not source records. Removal does not revoke provider authorization; linked-source dependencies must be resolved first.
GET/api/integrations/appsSearch public integration catalog metadata
Link to this operation #

Search public integration catalog metadata

Returns bundled public app metadata using q, category, appId, sort, page, and pageSize. It does not read account or workspace state.

Authentication & access

Public metadata route; no account, workspace, or provider credential is read.

Behavior to know

  • Catalog membership does not establish a supported adapter, account connection, working action, or synchronization.
GET/api/integrations/assistRead integration-assist state
Link to this operation #

Read integration-assist state

Provides admitted integration planning and reviewed acceptance of supported setup suggestions.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • AI-assisted planning does not bypass source setup, account authorization, or execution admission.
GET/api/integrations/catalogRead the admitted integration capability catalog
Link to this operation #

Read the admitted integration capability catalog

Returns the current integration capability catalog under the integration permission boundary.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Distinguish implemented setup routes and transports from broad public provider catalog metadata.
GET/api/integrations/operationsRead integration operation state
Link to this operation #

Read integration operation state

Prepares, applies, cancels, or reconciles supported integration operations under their current review and transport rules.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Simulation notification actions remain simulation-specific; an operation receipt is not evidence of an unperformed real provider action.
GET/api/integrations/pipedreamRead development connection state
Link to this operation #

Read development connection state

Supports reviewed development connection configuration, begin/finish, cancellation, and disconnect.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Account connection is separate from source reads and synchronization. It does not enable a paid plan or additional users.
GET/api/integrations/pipedream/platformRead integration platform setup status
Link to this operation #

Read integration platform setup status

Reads private platform setup status and handles explicit supported recovery actions.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Operator/development setup surface, not a general credential API. Recovery availability depends on the configured host and authority.
GET/api/integrations/pipedream/setupRead the shared account setup state
Link to this operation #

Read the shared account setup state

Supports connection review, existing-account selection, begin/finish, and cancellation in the shared connection journey.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Only an account verified for the current owner and context can be reused.
GET/api/integrations/postgresql-discoveryRead PostgreSQL discovery state
Link to this operation #

Read PostgreSQL discovery state

Runs the implemented PostgreSQL source discovery path after its exact setup review.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Discovery does not activate sync or import records. Database-provider permissions and setup admission remain separate from Ralti’s own internal restricted runtime role.
GET/api/integrations/postgresql-recordsRead PostgreSQL record-import state
Link to this operation #

Read PostgreSQL record-import state

Handles reviewed bounded reads, mapping-preview edits, import review/application, receipts, and cancellation.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • An import requires its current review. Previewing records is not activation of recurring synchronization.
GET/api/integrations/setupRead integration setup drafts
Link to this operation #

Read integration setup drafts

Creates, edits, refreshes, previews, reviews, applies, or discards supported source setup definitions.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Setup uses the selected current workspace and action-specific permissions; its request cannot choose a different integration identity.
GET/api/integrations/syncRead supported source-sync status
Link to this operation #

Read supported source-sync status

Supports reviewed activation, pause, conflict comparison, reconciliation, and resolution for implemented admitted sources.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • This route does not make every catalog app a sync adapter. Inspect the configured source’s transport and capabilities.
GET/api/integrations/toolsRead connected-tool resources
Link to this operation #

Read connected-tool resources

Lists, describes, configures, or reloads supported tools from an owned connected account.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • This setup route does not execute the selected business action. Execution belongs to the reviewed Flow or delegated agent path.
GET/api/integrations/two-wayRead supported two-way integration state
Link to this operation #

Read supported two-way integration state

Handles configuration previews, reviews, dispatch, conflicts, and reconciliation for the implemented transport; explicit fixture simulation remains labeled.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • This is not universal bidirectional synchronization. Private-preview admission and source/transport capabilities determine what can run.
GET/api/owner/early-accessRead the configured early-access dashboard
Link to this operation #

Read the configured early-access dashboard

Selects the configured connected dashboard or explicitly fictional mode. This is an owner administration surface, not a participant signup API.

Authentication & access

Configured owner or early-access administrator authority. This is not an ordinary workspace-member API.

Behavior to know

  • Fictional decisions do not prove real access approval. Connected access and the actual grant process remain explicit.
GET/api/owner/early-access/grantsRead early-access grants and audit state
Link to this operation #

Read early-access grants and audit state

Authorized early-access administrators can inspect grants, audit/outbox state, decide access, and explicitly queue supported invitations.

Authentication & access

Configured owner or early-access administrator authority. This is not an ordinary workspace-member API.

Behavior to know

  • Changing an external signup row alone is not a Ralti access grant. These operations require the administrator boundary.
GET/api/public/apps/{workspaceId}/{appId}Read a published public app
Link to this operation #

Read a published public app

Returns the scoped published experience and allowed choices without a workspace snapshot.

Authentication & access

Published public app policy and, where required, an app-bound resume or embed-exchange session. Public intake never grants workspace membership.

Parameters

NameLocationRequiredDescription
workspaceIdpathYesExact workspaceId from the authorized application context; it does not grant access.
appIdpathYesExact appId from the authorized application context; it does not grant access.

Behavior to know

  • Anonymous public access creates records only on final submission; existing-record updates and business-process tasks require the appropriate authenticated app authority.
GET/api/public/apps/{workspaceId}/{appId}/files/{id}Download an authorized app file
Link to this operation #

Download an authorized app file

The shared app-file gateway checks the exact app, release, principal, and input/field scope before the operation.

Authentication & access

Published public app policy and, where required, an app-bound resume or embed-exchange session. Public intake never grants workspace membership.

Parameters

NameLocationRequiredDescription
workspaceIdpathYesExact workspaceId from the authorized application context; it does not grant access.
appIdpathYesExact appId from the authorized application context; it does not grant access.
idpathYesExact id from the authorized application context; it does not grant access.

Behavior to know

  • Public file operations require the secure form session; pending uploads cannot be claimed by another participant.
POST/api/account/ai-permissionSet an AI processing permission
Link to this operation #

Set an AI processing permission

Reads or changes the account/workspace AI permission state through the account-principal boundary and current authorization.

Authentication & access

Authenticated account principal through the route-specific permission or deletion boundary; current action authorization applies.

Behavior to know

  • A permission decision is separate from app role membership, mailbox grants, and connection delegation.
POST/api/account/deletionRequest account deletion
Link to this operation #

Request account deletion

Uses the authenticated deletion-principal boundary. POST validates a deletion request and returns202 after admission to the durable deletion process.

Authentication & access

Authenticated account principal through the route-specific permission or deletion boundary; current action authorization applies.

Behavior to know

  • A202 response is acceptance, not a claim that all provider work has already completed. Use the account UI and current status; do not replay destructive requests blindly.
POST/api/agentsManage an agent member or its reviewed work
Link to this operation #

Manage an agent member or its reviewed work

GET returns the authorized directory, profile, run, or readiness information selected by the request. POST dispatches typed preview, create/update, lifecycle, ownership, responsibility, review, memory, mailbox-grant, or reconciliation actions.

Authentication & access

Authenticated application session. The handler and domain service enforce the current actor, workspace, role, source access, and action-specific requirements; writes retain origin validation.

Behavior to know

  • Human authority is required; this route does not give an agent an interactive login. Creation saves paused. Exact proposals and current-source checks still govern effects.
POST/api/ai-jobs/{id}/native-commandsApply reviewed native service commands
Link to this operation #

Apply reviewed native service commands

Applies selected command IDs from a saved AI job using the exact displayed native-review bindings and matching workspace.

Authentication & access

Authenticated application session. The handler and domain service enforce the current actor, workspace, role, source access, and action-specific requirements; writes retain origin validation.

Parameters

NameLocationRequiredDescription
idpathYesExact id from the authorized application context; it does not grant access.

Behavior to know

  • The server validates the review schema and current authority; this is not an arbitrary command execution endpoint.
POST/api/ai-jobs/{id}/native-commands/refreshRefresh a native-service proposal
Link to this operation #

Refresh a native-service proposal

Refreshes the saved AI job’s native review through the actor/workspace-scoped service.

Authentication & access

Authenticated application session. The handler and domain service enforce the current actor, workspace, role, source access, and action-specific requirements; writes retain origin validation.

Parameters

NameLocationRequiredDescription
idpathYesExact id from the authorized application context; it does not grant access.

Behavior to know

  • Review the refreshed output before applying. Refresh is not permission to reuse a stale approval.
POST/api/appsManage an app draft, publication, or access
Link to this operation #

Manage an app draft, publication, or access

Builder operations include create/save, legacy-form adaptation, journey creation, publish/restore, enable/pause, invitation, and revocation. Management authority is required for publication and audience changes.

Authentication & access

Authenticated application session. The handler and domain service enforce the current actor, workspace, role, source access, and action-specific requirements; writes retain origin validation.

Behavior to know

  • Draft editing is separate from publication. A restore creates a validated release rather than undoing submitted records or completed actions.
POST/api/apps/groupsManage an app audience group
Link to this operation #

Manage an app audience group

Manages group policy, membership, invitations, and invitation revocation for the selected app. Group access remains app-specific and does not create workspace membership.

Authentication & access

Authenticated application session. The handler and domain service enforce the current actor, workspace, role, source access, and action-specific requirements; writes retain origin validation.

Behavior to know

  • Current workspace management permission and the app policy govern group administration.
POST/api/apps/planPropose an app design
Link to this operation #

Propose an app design

Uses the configured AI and processing permission to propose changes to the selected app draft. Selected field metadata and the draft inform design; participant answers are excluded.

Authentication & access

Authenticated application session. The handler and domain service enforce the current actor, workspace, role, source access, and action-specific requirements; writes retain origin validation.

Behavior to know

  • Does not publish, invite users, broaden bindings, or change app access policy.
POST/api/apps/{workspaceId}/{appId}Act on an authorized app task or response
Link to this operation #

Act on an authorized app task or response

Handles invitation acceptance, authorized journey/task operations, and submissions with current app authority.

Authentication & access

Signed-in app participant or a valid app-scoped embed session. Current app publication, grants, field scope, and record assignments are checked.

Parameters

NameLocationRequiredDescription
workspaceIdpathYesExact workspaceId from the authorized application context; it does not grant access.
appIdpathYesExact appId from the authorized application context; it does not grant access.

Behavior to know

  • Anonymous public access creates records only on final submission; existing-record updates and business-process tasks require the appropriate authenticated app authority.
POST/api/apps/{workspaceId}/{appId}/filesUpload a file for an app input
Link to this operation #

Upload a file for an app input

Accepts a bounded multipart upload through the app-specific upload-intent and private-storage path.

Authentication & access

Signed-in app participant or a valid app-scoped embed session. Current app publication, grants, field scope, and record assignments are checked.

Parameters

NameLocationRequiredDescription
workspaceIdpathYesExact workspaceId from the authorized application context; it does not grant access.
appIdpathYesExact appId from the authorized application context; it does not grant access.

Behavior to know

  • Current session, release, input binding, content checks, and file/count/byte quotas apply. Uploading alone does not submit the form.
POST/api/apps/{workspaceId}/{appId}/sessionAuthorize an authenticated embed session
Link to this operation #

Authorize an authenticated embed session

Supports authorized embed-session setup and revocation through the app’s current access policy.

Authentication & access

Signed-in app participant or a valid app-scoped embed session. Current app publication, grants, field scope, and record assignments are checked.

Parameters

NameLocationRequiredDescription
workspaceIdpathYesExact workspaceId from the authorized application context; it does not grant access.
appIdpathYesExact appId from the authorized application context; it does not grant access.

Behavior to know

  • Embed origins are exact HTTPS origins; return links and session tokens are credentials. No third-party-cookie dependency is implied.
POST/api/integrationsManage an admitted integration source
Link to this operation #

Manage an admitted integration source

Reads connections and sources and dispatches supported reviewed preparation, preview, pause, disconnect, synchronization, or reconciliation operations.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Source adapters and admitted transports determine availability. This does not promise universal sync support.
POST/api/integrations/accessAcknowledge workspace integration access
Link to this operation #

Acknowledge workspace integration access

Reports private-preview eligibility and current workspace admission. POST records the explicit permissions acknowledgment against the expected epoch.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Ordinary application access does not bypass integration admission.
POST/api/integrations/accountsCheck or remove a saved account link
Link to this operation #

Check or remove a saved account link

GET reads the saved account inventory without provider requests. POST performs an explicit check or removal for an opaque accountAlias with confirmed:true.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • A check reads account metadata, not source records. Removal does not revoke provider authorization; linked-source dependencies must be resolved first.
POST/api/integrations/assistSuggest or accept an integration setup plan
Link to this operation #

Suggest or accept an integration setup plan

Provides admitted integration planning and reviewed acceptance of supported setup suggestions.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • AI-assisted planning does not bypass source setup, account authorization, or execution admission.
POST/api/integrations/operationsReview and manage integration operations
Link to this operation #

Review and manage integration operations

Prepares, applies, cancels, or reconciles supported integration operations under their current review and transport rules.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Simulation notification actions remain simulation-specific; an operation receipt is not evidence of an unperformed real provider action.
POST/api/integrations/pipedreamManage a development connection attempt
Link to this operation #

Manage a development connection attempt

Supports reviewed development connection configuration, begin/finish, cancellation, and disconnect.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Account connection is separate from source reads and synchronization. It does not enable a paid plan or additional users.
POST/api/integrations/pipedream/platformReview a supported platform recovery action
Link to this operation #

Review a supported platform recovery action

Reads private platform setup status and handles explicit supported recovery actions.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Operator/development setup surface, not a general credential API. Recovery availability depends on the configured host and authority.
POST/api/integrations/pipedream/setupReview or advance account setup
Link to this operation #

Review or advance account setup

Supports connection review, existing-account selection, begin/finish, and cancellation in the shared connection journey.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Only an account verified for the current owner and context can be reused.
POST/api/integrations/postgresql-discoveryReview or discover PostgreSQL tables
Link to this operation #

Review or discover PostgreSQL tables

Runs the implemented PostgreSQL source discovery path after its exact setup review.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Discovery does not activate sync or import records. Database-provider permissions and setup admission remain separate from Ralti’s own internal restricted runtime role.
POST/api/integrations/postgresql-recordsPreview or import PostgreSQL records
Link to this operation #

Preview or import PostgreSQL records

Handles reviewed bounded reads, mapping-preview edits, import review/application, receipts, and cancellation.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • An import requires its current review. Previewing records is not activation of recurring synchronization.
POST/api/integrations/setupCreate or review an integration setup
Link to this operation #

Create or review an integration setup

Creates, edits, refreshes, previews, reviews, applies, or discards supported source setup definitions.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • Setup uses the selected current workspace and action-specific permissions; its request cannot choose a different integration identity.
POST/api/integrations/syncReview or manage a supported source sync
Link to this operation #

Review or manage a supported source sync

Supports reviewed activation, pause, conflict comparison, reconciliation, and resolution for implemented admitted sources.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • This route does not make every catalog app a sync adapter. Inspect the configured source’s transport and capabilities.
POST/api/integrations/toolsDiscover or configure an available tool
Link to this operation #

Discover or configure an available tool

Lists, describes, configures, or reloads supported tools from an owned connected account.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • This setup route does not execute the selected business action. Execution belongs to the reviewed Flow or delegated agent path.
POST/api/integrations/two-wayReview supported two-way operations
Link to this operation #

Review supported two-way operations

Handles configuration previews, reviews, dispatch, conflicts, and reconciliation for the implemented transport; explicit fixture simulation remains labeled.

Authentication & access

Authenticated application session plus the configured integration admission for this actor, workspace, origin, and environment. A catalog listing or ordinary early access does not satisfy this separate permission.

Behavior to know

  • This is not universal bidirectional synchronization. Private-preview admission and source/transport capabilities determine what can run.
POST/api/mcp/oauth/consentRecord MCP OAuth consent
Link to this operation #

Record MCP OAuth consent

Validates the configured OAuth client and authenticated user before exposing or saving consent.

Authentication & access

Authenticated application session. The handler and domain service enforce the current actor, workspace, role, source access, and action-specific requirements; writes retain origin validation.

Behavior to know

  • MCP authorization is separate from ordinary app sessions and is bound to its reviewed client and scope.
POST/api/owner/early-accessSubmit an owner dashboard decision
Link to this operation #

Submit an owner dashboard decision

Selects the configured connected dashboard or explicitly fictional mode. This is an owner administration surface, not a participant signup API.

Authentication & access

Configured owner or early-access administrator authority. This is not an ordinary workspace-member API.

Behavior to know

  • Fictional decisions do not prove real access approval. Connected access and the actual grant process remain explicit.
POST/api/owner/early-access/grantsDecide access or queue an invitation
Link to this operation #

Decide access or queue an invitation

Authorized early-access administrators can inspect grants, audit/outbox state, decide access, and explicitly queue supported invitations.

Authentication & access

Configured owner or early-access administrator authority. This is not an ordinary workspace-member API.

Behavior to know

  • Changing an external signup row alone is not a Ralti access grant. These operations require the administrator boundary.
POST/api/public/apps/{workspaceId}/{appId}Submit a public app response
Link to this operation #

Submit a public app response

Validates final answers and commits an accepted public submission through its idempotent app service.

Authentication & access

Published public app policy and, where required, an app-bound resume or embed-exchange session. Public intake never grants workspace membership.

Parameters

NameLocationRequiredDescription
workspaceIdpathYesExact workspaceId from the authorized application context; it does not grant access.
appIdpathYesExact appId from the authorized application context; it does not grant access.

Behavior to know

  • Anonymous public access creates records only on final submission; existing-record updates and business-process tasks require the appropriate authenticated app authority.
POST/api/public/apps/{workspaceId}/{appId}/filesUpload a file for an app input
Link to this operation #

Upload a file for an app input

Accepts a bounded multipart upload through the app-specific upload-intent and private-storage path.

Authentication & access

Published public app policy and, where required, an app-bound resume or embed-exchange session. Public intake never grants workspace membership.

Parameters

NameLocationRequiredDescription
workspaceIdpathYesExact workspaceId from the authorized application context; it does not grant access.
appIdpathYesExact appId from the authorized application context; it does not grant access.

Behavior to know

  • Current session, release, input binding, content checks, and file/count/byte quotas apply. Uploading alone does not submit the form.
POST/api/public/apps/{workspaceId}/{appId}/sessionManage a public-app resume or embed exchange
Link to this operation #

Manage a public-app resume or embed exchange

Supports explicit create/read/save/resume/revoke progress actions and the approved embed-code exchange.

Authentication & access

Published public app policy and, where required, an app-bound resume or embed-exchange session. Public intake never grants workspace membership.

Parameters

NameLocationRequiredDescription
workspaceIdpathYesExact workspaceId from the authorized application context; it does not grant access.
appIdpathYesExact appId from the authorized application context; it does not grant access.

Behavior to know

  • Embed origins are exact HTTPS origins; return links and session tokens are credentials. No third-party-cookie dependency is implied.
POST/api/webhooks/clerkReceive a Clerk deletion webhook
Link to this operation #

Receive a Clerk deletion webhook

Receives the provider-verified Clerk deletion event through the durable account-deletion integration.

Authentication & access

Verified Clerk webhook request using the configured server-side verification boundary.

Behavior to know

  • Requires the configured webhook verification contract; an ordinary user session or unsigned JSON is not provider authority.

Find your next answer.

Start with a question or a feature name.

↑ ↓ NavigateEnter OpenEsc Close