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
Read the current session
Returns user, workspace, access, workspaces, members, and capabilities. Paged mode uses a bounded session response.
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
| Name | Location | Required | Description |
|---|---|---|---|
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
| X-Ralti-Workspace-Mode | header | No | Set to paged to receive workspace metadata and bounded initial data rather than assuming every sheet is fully loaded. |
| initialSheet | query | No | Optional initial sheet ID when X-Ralti-Workspace-Mode is paged. |
| view / query / q / archived | query | No | Initial 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
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.
Clerk link/start_new requires a verified Clerk identity and any required legacy proof. Local signup/signin/signout use the local authentication boundary.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
| mode | body | Yes | clerk: link | start_new; local: signup | signin | signout. |
| body | No | Required for local signin/signup or password-based legacy proof. | |
| password | body | No | 10–256 characters for local sign-in/signup and legacy proof. |
| name | body | No | Required local signup name, nonempty and at most 100 characters. |
Example request body
{
"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
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.
A valid, unexpired, single-use sign-in handoff code and its matching device verifier. An exact same-origin browser Origin header is required.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
| Origin | header | Yes | The exact configured application origin, supplied by the shared finish page. |
| code | body | Yes | The one-use code returned by the authorized system sign-in handoff. |
| verifier | body | Yes | The 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
List accessible workspaces
Returns {workspaces:[...]}, limited to workspaces accessible to the actor.
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
{
"workspaces": []
}POST/api/workspacesCreate, switch, or rename a workspace
Create, switch, or rename a workspace
Applies action create, switch, or rename and returns the resulting session response.
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
| Name | Location | Required | Description |
|---|---|---|---|
| action | body | Yes | create | switch | rename. |
| name | body | No | Name for create or rename. |
| workspaceId | body | No | Target workspace for switch; membership required. |
Example request body
{
"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
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.
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
| Name | Location | Required | Description |
|---|---|---|---|
| operations | body | Yes | Array of supported Operation objects; at most 500 operations. |
| expectedRevision | body | Yes | Integer workspace revision from the server-owned workspace or proposal being applied. |
| confirmed | body | No | true when the reviewed operation batch requires explicit confirmation. |
| aiJobId | body | No | Optional owned, completed saved job ID; its application receipt commits with the mutation. |
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
| X-Ralti-Workspace-Mode | header | No | Set to paged to receive workspace metadata and bounded initial data rather than assuming every sheet is fully loaded. |
Example request body
{
"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
Undo or redo the current history entry
Applies an undo or redo with a revision check, then returns {workspace}.
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
| Name | Location | Required | Description |
|---|---|---|---|
| direction | body | Yes | undo | redo. |
| expectedRevision | body | Yes | Integer workspace revision from the server-owned workspace or proposal being applied. |
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
| X-Ralti-Workspace-Mode | header | No | Set to paged to receive workspace metadata and bounded initial data rather than assuming every sheet is fully loaded. |
Example request body
{
"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
Read saved versions of a record
Returns {versions:[...]} for the authorized sheet and record.
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
| Name | Location | Required | Description |
|---|---|---|---|
| spaceId | query | Yes | Sheet identifier. |
| itemId | query | Yes | Record identifier. |
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
Example response
{
"versions": []
}Behavior to know
- Versions are governed record evidence, separate from workspace undo/redo.
GET/api/recordsPage workspace records
Page workspace records
Returns workspaceId, revision, records:[{spaceId,item}], total, nextCursor, labels, and counts for all/assigned/due records.
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
| Name | Location | Required | Description |
|---|---|---|---|
| scope | query | No | all (default), assigned, or due; other values normalize to all. |
| query | query | No | Optional text search. |
| today | query | No | Date used for due scope. |
| cursor | query | No | Opaque cursor from the previous response. |
| limit | query | No | Integer 1–100; default 100. |
| X-Atlas-Workspace | header | No | Optional 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
Page records in a sheet
Returns a SheetPage: workspaceId, spaceId, revision, items, total, nextCursor, and labels.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| view | query | No | Saved view identifier used for filtering/sorting. |
| query | query | No | Search text. |
| archived | query | No | Literal true selects archived records. |
| cursor | query | No | Opaque cursor from the previous response. |
| limit | query | No | Integer 1–100; default 100. |
| item | query | No | Fetch a specific item. |
| items | query | No | JSON-encoded array of record IDs. |
| exact | query | No | Literal true selects exact-label matching. |
| X-Atlas-Workspace | header | No | Optional 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
Download a sheet export
Exports the authorized sheet as CSV when format=csv, or JSON otherwise.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| format | query | No | csv for text/csv; any other/omitted value gives application/json. |
| X-Atlas-Workspace | header | No | Optional 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
Read permitted search-index status
Returns workspaceId, keywordSearch, semanticSearch configuration/model/dimensions/sources, and coverage.
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
| Name | Location | Required | Description |
|---|---|---|---|
| X-Atlas-Workspace | header | No | Optional 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
Interpret an immediate request
Produces a proposal without applying it. Supports JSON or a request-connected NDJSON stream.
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
| Name | Location | Required | Description |
|---|---|---|---|
| request | body | Yes | Nonempty instruction, at most 5,000 characters. |
| interpretationMode | body | No | ai (default) or explicit built_in. |
| intent | body | No | ask (answer-only) or edit. |
| stream | body | No | true requests NDJSON progress events. |
| spaceId / workbookId / insightId / viewId | body | No | Optional validated context identifiers. |
| selectedItemIds | body | No | Up to 1,000 selected record IDs. |
| conversation / pendingDraft / draftJobId | body | No | Bounded prior conversation or owned saved-draft context. |
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
Example request body
{
"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
Create a durable AI job
Persists a private actor/workspace-scoped request and returns its public AiJob with HTTP 202.
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
| Name | Location | Required | Description |
|---|---|---|---|
| request | body | Yes | Nonempty instruction, at most 5,000 characters. |
| clientRequestId | body | No | Optional retry deduplication identifier, 8–100 letters, digits, underscore or hyphen. |
| intent | body | No | ask or edit. |
| spaceId / workbookId / insightId / viewId / selectedItemIds | body | No | Optional validated context. |
| conversation / pendingDraft / draftJobId | body | No | Bounded conversation or owned saved-draft refinement context. |
| resumeJobId | body | No | Failed, undismissed job to resume with exactly matching saved request/context. |
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
Example request body
{
"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
List saved AI jobs
Returns {jobs:[...]} for the requesting actor in the selected workspace.
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
| Name | Location | Required | Description |
|---|---|---|---|
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
Example response
{
"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
Read an owned AI job
Returns the public AiJob state and any completed proposal.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| X-Atlas-Workspace | header | No | Optional 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
Cancel or dismiss an AI job
Requests cancellation for active work or dismisses a finished request; returns the resulting public AiJob.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| X-Atlas-Workspace | header | No | Optional 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
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.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| sheetNames | body | No | Alternative body: array of {spaceId,name}, 1–100 unique sheet IDs; names up to 200 characters. |
| operations | body | No | Alternative body: nonempty validated Operation array for the draft. |
| rebase | body | No | Alternative body: true requests safe refresh against unchanged dependencies. |
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
Example request body
{
"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
Upload a private attachment
Accepts multipart/form-data with a nonempty file field and returns {url,name} with HTTP 201.
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
| Name | Location | Required | Description |
|---|---|---|---|
| file | formData | Yes | Nonempty file, at most 10 MiB. |
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
Example response
{
"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
Download or preview an attachment
Checks membership against the attachment’s actual workspace before returning private bytes.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| preview | query | No | 1 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
Read a workbook overview
Computes the authorized workbook dashboard from server-owned data.
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
| Name | Location | Required | Description |
|---|---|---|---|
| workbookId | query | Yes | Existing workbook ID. |
| sheetId | query | No | all (default) or a sheet belonging to this workbook. |
| today | query | No | YYYY-MM-DD date; defaults to server UTC date. |
| X-Atlas-Workspace | header | No | Optional 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
Query a dashboard layout
Evaluates a validated InsightDocument against authorized server data without saving the layout.
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
| Name | Location | Required | Description |
|---|---|---|---|
| document | body | Yes | InsightDocument validated by insightDocumentSchema. |
| blockId | body | No | Optional block in that document. |
| groupKey | body | No | Optional group drilldown; requires blockId. |
| offset | body | No | Integer 0–1,000,000. |
| limit | body | No | Integer 1–100. |
| today | body | No | Optional ISO date. |
| X-Atlas-Workspace | header | No | Optional 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
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.
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
| Name | Location | Required | Description |
|---|---|---|---|
| operations | body | Yes | 1–500 operations to stage. |
| documentId | body | Yes | Insight document present in the staged layout. |
| expectedRevision | body | Yes | Integer workspace revision from the server-owned workspace or proposal being applied. |
| blockId / groupKey / offset / limit / today | body | No | Optional drilldown fields; groupKey requires blockId, limit 1–100, offset 0–1,000,000. |
| X-Atlas-Workspace | header | No | Optional 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
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.
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
| Name | Location | Required | Description |
|---|---|---|---|
| workbookId | query | No | Workbook to list when other selectors are absent. |
| documentId | query | No | Existing document to inspect. |
| version | query | No | Version selector when documentId is present; an empty selector requests service default. |
| recordSpaceId | query | No | Sheet of a related record; required together with recordId. |
| recordId | query | No | Related record; required together with recordSpaceId. |
| X-Atlas-Workspace | header | No | Optional 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
Manage document templates and drafts
Dispatches save_template, create_draft, create_batch, save_draft, preview, finalize, or revise through the document service.
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
| Name | Location | Required | Description |
|---|---|---|---|
| action | body | Yes | save_template | create_draft | create_batch | save_draft | preview | finalize | revise. |
| template | body | No | Required for save_template and preview; validated document template. |
| templateId | body | No | Required for create_draft/create_batch. |
| sourceItemId / sourceSpaceId / name | body | No | Optional draft context; accepted fields vary by action. |
| sourceItemIds | body | No | 1–100 IDs for create_batch; duplicate IDs are deduplicated. |
| documentId / revision | body | No | Required for save_draft/finalize/revise; revision is a positive document revision, not workspace expectedRevision. |
| layout | body | No | Required for save_draft. |
Example request body
{
"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
Plan a document template
Produces {template} from a prompt and workbook context without saving the result.
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
| Name | Location | Required | Description |
|---|---|---|---|
| workbookId | body | Yes | Workbook identifier, up to 160 characters. |
| prompt | body | Yes | Nonempty prompt, up to 5,000 characters. |
| sourceSpaceId | body | No | Optional source sheet ID. |
| template | body | No | Optional existing validated template to refine. |
Example request body
{
"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
Download a saved document PDF
Reads the authorized finalized version and returns its PDF bytes.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| version | query | No | Optional version selector; omitted uses the service default. |
| X-Atlas-Workspace | header | No | Optional 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
List saved workbook templates
Returns {templates:[...]} for the selected workspace.
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
| Name | Location | Required | Description |
|---|---|---|---|
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
Example response
{
"templates": []
}POST/api/workbook-templatesSave a reusable workbook template
Save a reusable workbook template
Captures an existing workbook structure and document layouts without its business records, returning {template}.
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
| Name | Location | Required | Description |
|---|---|---|---|
| workbookId | body | Yes | Existing workbook to capture. |
| name | body | Yes | Trimmed name, 1–100 characters. |
| description | body | No | Description up to 1,000 characters; defaults empty. |
Example request body
{
"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
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.
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
| Name | Location | Required | Description |
|---|---|---|---|
| templateId | body | Yes | Saved template ID. |
| name | body | Yes | New workbook name, 1–100 characters. |
| expectedRevision | body | Yes | Integer workspace revision from the server-owned workspace or proposal being applied. |
| reuse | body | No | String-to-string mapping of template sheet IDs to existing sheets; defaults {}. |
| requestId | body | No | 8–100 character deduplication identifier; required when preview is false. |
| preview | body | No | Boolean, default false. |
Example request body
{
"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
Install a reviewed built-in template
Installs a recognized built-in template from a validated reviewed operation batch and matching workspace revision.
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
| Name | Location | Required | Description |
|---|---|---|---|
| templateId | body | Yes | ID from WORKSPACE_TEMPLATES; not an arbitrary user-supplied template name. |
| operations | body | Yes | 1–500 validated template operations including create_workbook. |
| expectedRevision | body | Yes | Integer 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
Read team state
Returns members, permitted invitations, activity, notifications, and presence.
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
| Name | Location | Required | Description |
|---|---|---|---|
| X-Atlas-Workspace | header | No | Optional 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
Manage invitations, members, or notifications
Dispatches invite, accept_invite, revoke_invite, update_member, remove_member, or read_notifications.
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
| Name | Location | Required | Description |
|---|---|---|---|
| action | body | Yes | invite | accept_invite | revoke_invite | update_member | remove_member | read_notifications. |
| email / role / sendEmail | body | No | For invite: email and invitable role; optional boolean sendEmail. |
| token | body | No | For accept_invite. |
| invitationId | body | No | For revoke_invite. |
| userId / role | body | No | For update_member; userId alone for remove_member. |
| ids | body | No | For read_notifications: up to 100 notification IDs; omitted marks all own unread notifications. |
Example request body
{
"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
Read a record discussion
Returns {comments:[...]} for an accessible record.
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
| Name | Location | Required | Description |
|---|---|---|---|
| spaceId | query | Yes | Record sheet. |
| itemId | query | Yes | Record ID. |
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
Example response
{
"comments": []
}POST/api/commentsAdd or delete a comment
Add or delete a comment
Adds a record comment/reply or deletes an authorized comment; returns {comments}.
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
| Name | Location | Required | Description |
|---|---|---|---|
| action | body | Yes | add | delete. |
| spaceId / itemId / body | body | No | Required for add; body is nonempty, up to 5,000 characters. |
| mentions | body | No | Optional up to 25 current member IDs. |
| parentId | body | No | Optional original comment ID for a reply on the same record. |
| commentId | body | No | Required for delete. |
Example request body
{
"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
Poll revision and presence
Returns workspaceId, revision, presence, and unreadCount.
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
| Name | Location | Required | Description |
|---|---|---|---|
| X-Atlas-Workspace | header | No | Optional 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
Update presence and read events
Saves the actor’s presence (optional sheet) and returns the same event snapshot.
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
| Name | Location | Required | Description |
|---|---|---|---|
| spaceId | body | No | Optional current sheet identifier. |
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
Example request body
{}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
Read helper runs and workspace
Returns {runs,workspace} for the selected workspace.
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
| Name | Location | Required | Description |
|---|---|---|---|
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
| X-Ralti-Workspace-Mode | header | No | Set 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
Run or review a helper
Runs a saved workflow/agent or applies/dismisses an existing run.
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
| Name | Location | Required | Description |
|---|---|---|---|
| action | body | Yes | run | apply | dismiss. |
| workflowId | body | No | Required for run. |
| runId | body | No | Required for apply or dismiss. |
| expectedRevision | body | No | Workspace revision used by the reviewed/run request; repository checks govern the action. |
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
| retryRunId | body | No | Optional 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
{
"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
Read an agent’s email grant
Returns {source:null} when absent, or source configuration, grant identity/time, ownership, validity, and optional reason.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
Example response
{
"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
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.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| config | body | Yes | {connectionId,folder,days,limit,sender,subject,unreadOnly}; folder inbox|sent, days 1|7|30|90, limit 1–25, text filters max 200 characters. |
| expectedRevision | body | Yes | Integer workspace revision from the server-owned workspace or proposal being applied. |
Example request body
{
"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
Revoke an agent’s email source
Revokes the source under service ownership/management checks and returns {source:null}.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
Example response
{
"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
Read the email dashboard
Returns provider availability, categories/categoryRevision, connections, counts/metrics, visible threads, draft summaries, and bounded page data.
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
| Name | Location | Required | Description |
|---|---|---|---|
| connectionId | query | No | Limit to one accessible mailbox. |
| folder | query | No | inbox | sent | awaiting_reply | drafts | unread | starred | archive | trash. |
| category | query | No | Category ID or uncategorized; category filtering is owner-only. |
| spaceId | query | No | Linked record sheet filter. |
| itemId | query | No | Linked record filter. |
| query | query | No | Search matching latest-message subject/preview/participant text. |
| cursor | query | No | Email page cursor. |
| limit | query | No | Thread-page requested size; /threads clamps to 1–50, default 30. |
| X-Atlas-Workspace | header | No | Optional 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
Page visible email threads
Returns {threads,filteredCount?,nextCursor?}.
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
| Name | Location | Required | Description |
|---|---|---|---|
| connectionId | query | No | Limit to one accessible mailbox. |
| folder | query | No | inbox | sent | awaiting_reply | drafts | unread | starred | archive | trash. |
| category | query | No | Category ID or uncategorized; category filtering is owner-only. |
| spaceId | query | No | Linked record sheet filter. |
| itemId | query | No | Linked record filter. |
| query | query | No | Search matching latest-message subject/preview/participant text. |
| cursor | query | No | Email page cursor. |
| limit | query | No | Thread-page requested size; /threads clamps to 1–50, default 30. |
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
Example response
{
"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
Read a conversation
Returns {thread,messages,nextCursor?} after private/shared conversation authorization.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| cursor | query | No | Optional next message-page cursor. |
| X-Atlas-Workspace | header | No | Optional 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 or share a conversation
Mailbox owner updates a record link and private/workspace visibility; returns the thread detail.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| link | body | No | {spaceId,itemId} or null; referenced record must be accessible. |
| visibility | body | No | private | workspace. |
| shared | body | No | Legacy boolean alternative when visibility is omitted. |
Example request body
{
"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
Organize an email conversation
Performs one supported owner action and returns updated thread detail.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| action | body | Yes | read | unread | star | unstar | archive | trash | restore | categorize. |
| category | body | No | Category ID or null; only accepted with categorize. |
Example request body
{
"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
Synchronize a connected mailbox
Runs synchronization for the requested owned connection and returns its service result.
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
| Name | Location | Required | Description |
|---|---|---|---|
| connectionId | body | Yes | Connected mailbox identifier. |
Example request body
{
"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
Disconnect a mailbox
Disconnects an owned connection and returns {disconnected:true}.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
Example response
{
"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
Configure incoming email sorting
Updates owned mailbox sorting and returns its public EmailConnection.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| enabled | body | Yes | Boolean sorting state. |
| instructions | body | No | Optional text up to 1,000 characters. |
Example request body
{
"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
Begin Google authorization
Creates a short-lived OAuth flow for an editing account and returns {url} for browser navigation.
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
{}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
Complete Google authorization
Consumes the provider code/state for the signed-in user and redirects back to the application email page.
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
| Name | Location | Required | Description |
|---|---|---|---|
| code | query | No | OAuth authorization code returned by the provider. |
| state | query | No | Server-issued OAuth state returned by the provider. |
| error | query | No | Provider-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
Begin Microsoft authorization
Creates a short-lived OAuth flow for an editing account and returns {url} for browser navigation.
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
| Name | Location | Required | Description |
|---|---|---|---|
| sharedMailbox | body | No | Optional shared mailbox email address. |
Example request body
{}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
Complete Microsoft authorization
Consumes the provider code/state for the signed-in user and redirects back to the application email page.
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
| Name | Location | Required | Description |
|---|---|---|---|
| code | query | No | OAuth authorization code returned by the provider. |
| state | query | No | Server-issued OAuth state returned by the provider. |
| error | query | No | Provider-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
Connect an IMAP/SMTP mailbox
Validates mailbox credentials, verifies provider connectivity, and returns {connection,workspaceId}.
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
| Name | Location | Required | Description |
|---|---|---|---|
| address | body | Yes | Mailbox email address. |
| username | body | No | Defaults to address when omitted/empty. |
| password | body | Yes | Mailbox app password; never log or return it. |
| displayName | body | No | Optional name, at most 150 characters. |
| imap | body | Yes | {host,port,secure}: 993/true or 143/false (required STARTTLS). |
| smtp | body | Yes | {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
Read personal mailbox categories
Returns {categories,revision} for the actor in this workspace.
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
| Name | Location | Required | Description |
|---|---|---|---|
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
PUT/api/email/categoriesReplace personal mailbox categories
Replace personal mailbox categories
Saves the complete category list with its category-specific revision and returns categories, revision, and clearedThreads.
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
| Name | Location | Required | Description |
|---|---|---|---|
| categories | body | Yes | Up to 30 {id,name,color,description} objects; IDs/names unique, reserved uncategorized ID prohibited. |
| expectedRevision | body | Yes | Current category revision (not the workspace revision). |
Example request body
{
"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
Plan a category setup
Builds a reviewed category proposal without changing saved categories or reading mailbox message content.
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
| Name | Location | Required | Description |
|---|---|---|---|
| request | body | Yes | Nonempty prompt, up to 4,000 characters. |
| baseRevision | body | Yes | Current category revision. |
| conversation | body | No | Up to 10 {role:user|assistant,content} turns; content up to 6,000 chars. |
| draft | body | No | Optional existing category-array draft. |
Example request body
{
"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
Read notification preferences
Returns preferences, notificationSender, canManageNotifications, and delivery counts.
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
| Name | Location | Required | Description |
|---|---|---|---|
| X-Atlas-Workspace | header | No | Optional 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
Update notification preferences or sender
Updates personal boolean preferences and/or the workspace notification mailbox, then returns settings.
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
| Name | Location | Required | Description |
|---|---|---|---|
| preferences | body | No | Optional subset of enabled, assignments, mentions, replies, salesReplies, workflows; every supplied value is boolean. |
| notificationSender | body | No | Optional {connectionId:string|null}; owner/admin access and owned capable mailbox required. |
Example request body
{
"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
List private email drafts
Returns {drafts:[...]} for this actor/workspace.
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
| Name | Location | Required | Description |
|---|---|---|---|
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
Example response
{
"drafts": []
}POST/api/email/draftsCreate a private email draft
Create a private email draft
Creates or deduplicates a draft for an owned connected mailbox and returns EmailDraft with HTTP 201.
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
| Name | Location | Required | Description |
|---|---|---|---|
| connectionId | body | Yes | Owned connected mailbox ID. |
| clientRequestId | body | Yes | Deduplication ID used for draft creation. |
| to | body | Yes | Array of {address,name?} recipients. |
| cc / bcc | body | No | Optional address arrays; total recipients at most 100. |
| subject | body | Yes | Plain subject, max 998 characters, no newlines. |
| bodyText | body | Yes | Plain text body, max 200,000 characters. |
| link | body | No | Optional {spaceId,itemId} record link. |
| replyToMessageId | body | No | Optional visible message ID from the same connection. |
Example request body
{
"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
Read a private email draft
Returns EmailDraft for its creating actor in this workspace.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| X-Atlas-Workspace | header | No | Optional 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
Edit an unsent draft
Merges provided draft fields with the original and returns the updated EmailDraft.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| to / cc / bcc / subject / bodyText / link / replyToMessageId | body | No | Optional replacements using the same draft validation. |
Example request body
{
"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
Discard an unsent draft
Deletes a draft or failed message and returns {deleted:true}.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
Example response
{
"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
Queue an explicitly reviewed message
Queues one reviewed draft for durable delivery and returns EmailDraft with HTTP 202.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| confirmed | body | Yes | Must be true after reviewing actual recipients and content. |
| clientRequestId | body | Yes | Unique send deduplication identifier. |
| expectedUpdatedAt | body | Yes | Exact updatedAt of the draft that was reviewed. |
Example request body
{
"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
Reconcile an uncertain delivery
Checks provider evidence for an owned draft whose delivery outcome needs resolution and returns the updated draft.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier 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
Read a published form
Returns {form} only when the supplied capability identifies a currently published form.
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
| Name | Location | Required | Description |
|---|---|---|---|
| workspaceId | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| viewId | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| x-ralti-form-key | header | Yes | 64 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
Submit a published form
Validates the form fields and creates its record atomically under the published-form capability.
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
| Name | Location | Required | Description |
|---|---|---|---|
| workspaceId | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| viewId | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
| x-ralti-form-key | header | Yes | Valid published-form capability. |
| submissionId | body | Yes | UUID-shaped stable submission identifier; reusing it deduplicates a retry. |
| values | body | Yes | Field-ID keyed values accepted by this published form. |
Example request body
{
"submissionId": "00000000-0000-4000-8000-000000000001",
"values": {
"field_name": "Example request"
}
}Example response
{
"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
List personal MCP connections
Returns {connections:[...]} for this signed-in actor and workspace; token secret is never listed.
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
| Name | Location | Required | Description |
|---|---|---|---|
| X-Atlas-Workspace | header | No | Optional workspace ID. Selects scope; never grants access. Omit to use the account preference. |
Example response
{
"connections": []
}POST/api/mcp/connectionsIssue a scoped MCP connection
Issue a scoped MCP connection
Creates a personal connection and returns {connection,token} with HTTP 201. The token is shown only at creation.
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
| Name | Location | Required | Description |
|---|---|---|---|
| name | body | Yes | Trimmed connection name, 1–80 characters. |
| scopes | body | Yes | Nonempty array: records:read, email:read, drafts:propose. |
| days | body | Yes | Expiration: 7, 30, or 90. |
Example request body
{
"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
Revoke a personal MCP connection
Revokes an actor-owned connection in the selected workspace and returns {revoked:true}.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs. |
Example response
{
"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
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.
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
| Name | Location | Required | Description |
|---|---|---|---|
| Authorization | header | Yes | Bearer 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
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.
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
| Name | Location | Required | Description |
|---|---|---|---|
| Authorization | header | Yes | Bearer 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
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.
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
| Name | Location | Required | Description |
|---|---|---|---|
| Authorization | header | Yes | Bearer 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
Check process liveness
Returns {status:"ok"} without contacting the database or an external provider.
Public; bypasses Clerk middleware.
Example response
{
"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
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.
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
| Name | Location | Required | Description |
|---|---|---|---|
| workbookId | query | No | Optional workbook scope for the collection. |
| before | query | No | Opaque nextCursor from the previous run-history page; up to 100 runs per page. |
| flowId / versionId | query | No | Choose a flow; optional versionId selects its immutable published definition. |
| runId | query | No | Saved run including its pinned definition and per-node checkpoints, filtered by current permissions. |
| resources | query | No | Set to 1 for authorized editor resource metadata. Takes precedence over runId, then flowId, then collection. |
| X-Atlas-Workspace | header | No | Optional 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
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}.
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
| Name | Location | Required | Description |
|---|---|---|---|
| action | body | Yes | save | publish | set_enabled | preview | run | approve | dismiss | cancel | retry | delete | import_helper. |
| definition | body | No | FlowDefinition required for save or preview. |
| flowId / revision | body | No | flowId for publish/set_enabled/run/delete; current flow revision required except run. |
| enabled | body | No | Boolean required for set_enabled. |
| input | body | No | Optional run/preview trigger envelope. User JSON belongs under input, for example {event:"manual",input:{customerId:"record_id"}}. |
| runId / nodeId / revision | body | No | Run 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. |
| decision | body | No | approve accepts approved or rejected; defaults to approved. |
| workflowId / workbookId | body | No | Legacy workflowId required for import_helper; workbookId optionally chooses its draft scope. |
| X-Atlas-Workspace | header | No | Optional 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
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.
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
| Name | Location | Required | Description |
|---|---|---|---|
| prompt | body | Yes | Nonempty instructions, maximum8,000 characters. |
| workbookId | body | No | Optional authorized workbook context. |
| definition | body | No | Optional current FlowDefinition to revise; must agree with workbookId when both are supplied. |
| X-Atlas-Workspace | header | No | Optional 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
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.
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
| Name | Location | Required | Description |
|---|---|---|---|
| workbookId | query | No | Optional workbook scope for summary lists. |
| reportId | query | No | Saved editable report definition. |
| runId | query | No | Saved generated version; takes precedence over reportId. |
| X-Atlas-Workspace | header | No | Optional 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
Preview, save, generate, or delete a business report
preview returns {result,workspaceRevision}; save returns {report}; generate returns201 {run}; delete returns {deleted:true}.
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
| Name | Location | Required | Description |
|---|---|---|---|
| action | body | Yes | preview | save | generate | delete. |
| definition | body | No | ReportDefinition required for preview/save; includes report kind, period, currency, source, notes, and current definition revision. |
| reportId / revision | body | No | Required for generate/delete; revision is the current report-definition revision. |
| expectedWorkspaceRevision | body | No | Required for generate; use the revision returned by the reviewed preview. Source changes invalidate generation. |
| X-Atlas-Workspace | header | No | Optional 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
Download a saved report as PDF or CSV
Returns the full saved report version as an attachment, preserving its definition, totals, and source snapshot.
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
| Name | Location | Required | Description |
|---|---|---|---|
| runId | query | Yes | ID of a generated report version. |
| format | query | Yes | pdf | csv. |
| X-Atlas-Workspace | header | No | Optional 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
Browse existing helper history
Returns {workspaceId,runs,total,filteredTotal,counts,summaries,nextCursor?} with authorized result projections and per-helper activity summaries.
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
| Name | Location | Required | Description |
|---|---|---|---|
| workbookId / workflowId | query | No | Optional workbook/helper filters. workbookId defaults to all. |
| status | query | No | Optional legacy run status: running | review | applied | no_changes | failed | dismissed. |
| q | query | No | Search helper names and run IDs; excludes private result payloads. |
| from / to | query | No | Optional ISO timestamps or YYYY-MM-DD dates; calendar dates use UTC day boundaries. |
| limit | query | No | Integer1–50; defaults to30. |
| cursor | query | No | Opaque nextCursor tied to the same filters and workspace. |
| X-Atlas-Workspace | header | No | Optional 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
Inspect an existing helper run
Returns {run} with recorded execution/review metadata, authorized result content, and access flags.
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
| Name | Location | Required | Description |
|---|---|---|---|
| runId | path | Yes | Existing legacy helper run ID. |
| X-Atlas-Workspace | header | No | Optional 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
Check an existing helper’s setup
Returns {source,connections,readiness}; readiness includes ready and actionable issues.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Existing legacy helper workflow ID. |
| X-Atlas-Workspace | header | No | Optional 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
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}.
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
| Name | Location | Required | Description |
|---|---|---|---|
| expectedRevision | body | Yes | Current nonnegative workspace revision. |
| workflow | body | Yes | Complete legacy Workflow configuration. |
| emailSource | body | No | Optional {config,consent:true} for the connecting mailbox owner’s explicit grant; applies only to email-capable helpers. |
| X-Atlas-Workspace | header | No | Optional 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
Preview a bounded mailbox selection for a helper
Returns matchedCount,truncated,lastSyncedAt,messages and limits for the proposed owner-authorized source.
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
| Name | Location | Required | Description |
|---|---|---|---|
| config | body | Yes | Validated AgentEmailSourceConfig selecting the owner’s mailbox and bounded filters. |
| X-Atlas-Workspace | header | No | Optional 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
Delete a pending app upload
The shared app-file gateway checks the exact app, release, principal, and input/field scope before the operation.
Signed-in app participant or a valid app-scoped embed session. Current app publication, grants, field scope, and record assignments are checked.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
| workspaceId | path | Yes | Exact workspaceId from the authorized application context; it does not grant access. |
| appId | path | Yes | Exact appId from the authorized application context; it does not grant access. |
| id | path | Yes | Exact 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
Delete a pending app upload
The shared app-file gateway checks the exact app, release, principal, and input/field scope before the operation.
Published public app policy and, where required, an app-bound resume or embed-exchange session. Public intake never grants workspace membership.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
| workspaceId | path | Yes | Exact workspaceId from the authorized application context; it does not grant access. |
| appId | path | Yes | Exact appId from the authorized application context; it does not grant access. |
| id | path | Yes | Exact 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
Read AI processing permissions
Reads or changes the account/workspace AI permission state through the account-principal boundary and current authorization.
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
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.
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
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.
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
Read a job’s document previews
Returns document previews attached to the authenticated actor’s saved AI job in the current workspace.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Exact 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
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.
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
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.
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
Read an authorized participant app
Returns the scoped published experience and allowed choices without a workspace snapshot.
Signed-in app participant or a valid app-scoped embed session. Current app publication, grants, field scope, and record assignments are checked.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
| workspaceId | path | Yes | Exact workspaceId from the authorized application context; it does not grant access. |
| appId | path | Yes | Exact 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
Download an authorized app file
The shared app-file gateway checks the exact app, release, principal, and input/field scope before the operation.
Signed-in app participant or a valid app-scoped embed session. Current app publication, grants, field scope, and record assignments are checked.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
| workspaceId | path | Yes | Exact workspaceId from the authorized application context; it does not grant access. |
| appId | path | Yes | Exact appId from the authorized application context; it does not grant access. |
| id | path | Yes | Exact 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
Read integration connections and sources
Reads connections and sources and dispatches supported reviewed preparation, preview, pause, disconnect, synchronization, or reconciliation operations.
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
Read integration access status
Reports private-preview eligibility and current workspace admission. POST records the explicit permissions acknowledgment against the expected epoch.
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
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.
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
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.
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
Read integration-assist state
Provides admitted integration planning and reviewed acceptance of supported setup suggestions.
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
Read the admitted integration capability catalog
Returns the current integration capability catalog under the integration permission boundary.
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
Read integration operation state
Prepares, applies, cancels, or reconciles supported integration operations under their current review and transport rules.
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
Read development connection state
Supports reviewed development connection configuration, begin/finish, cancellation, and disconnect.
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
Read integration platform setup status
Reads private platform setup status and handles explicit supported recovery actions.
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
Read the shared account setup state
Supports connection review, existing-account selection, begin/finish, and cancellation in the shared connection journey.
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
Read PostgreSQL discovery state
Runs the implemented PostgreSQL source discovery path after its exact setup review.
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
Read PostgreSQL record-import state
Handles reviewed bounded reads, mapping-preview edits, import review/application, receipts, and cancellation.
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
Read integration setup drafts
Creates, edits, refreshes, previews, reviews, applies, or discards supported source setup definitions.
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
Read supported source-sync status
Supports reviewed activation, pause, conflict comparison, reconciliation, and resolution for implemented admitted sources.
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
Read connected-tool resources
Lists, describes, configures, or reloads supported tools from an owned connected account.
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
Read supported two-way integration state
Handles configuration previews, reviews, dispatch, conflicts, and reconciliation for the implemented transport; explicit fixture simulation remains labeled.
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/mcp/oauth/consentRead an MCP OAuth consent request
Read an MCP OAuth consent request
Validates the configured OAuth client and authenticated user before exposing or saving consent.
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.
GET/api/owner/early-accessRead the configured early-access dashboard
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.
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
Read early-access grants and audit state
Authorized early-access administrators can inspect grants, audit/outbox state, decide access, and explicitly queue supported invitations.
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
Read a published public app
Returns the scoped published experience and allowed choices without a workspace snapshot.
Published public app policy and, where required, an app-bound resume or embed-exchange session. Public intake never grants workspace membership.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
| workspaceId | path | Yes | Exact workspaceId from the authorized application context; it does not grant access. |
| appId | path | Yes | Exact 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
Download an authorized app file
The shared app-file gateway checks the exact app, release, principal, and input/field scope before the operation.
Published public app policy and, where required, an app-bound resume or embed-exchange session. Public intake never grants workspace membership.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
| workspaceId | path | Yes | Exact workspaceId from the authorized application context; it does not grant access. |
| appId | path | Yes | Exact appId from the authorized application context; it does not grant access. |
| id | path | Yes | Exact 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
Set an AI processing permission
Reads or changes the account/workspace AI permission state through the account-principal boundary and current authorization.
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
Request account deletion
Uses the authenticated deletion-principal boundary. POST validates a deletion request and returns202 after admission to the durable deletion process.
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
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.
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
Apply reviewed native service commands
Applies selected command IDs from a saved AI job using the exact displayed native-review bindings and matching workspace.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Exact 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
Refresh a native-service proposal
Refreshes the saved AI job’s native review through the actor/workspace-scoped service.
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
| Name | Location | Required | Description |
|---|---|---|---|
| id | path | Yes | Exact 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
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.
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
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.
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
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.
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
Act on an authorized app task or response
Handles invitation acceptance, authorized journey/task operations, and submissions with current app authority.
Signed-in app participant or a valid app-scoped embed session. Current app publication, grants, field scope, and record assignments are checked.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
| workspaceId | path | Yes | Exact workspaceId from the authorized application context; it does not grant access. |
| appId | path | Yes | Exact 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
Upload a file for an app input
Accepts a bounded multipart upload through the app-specific upload-intent and private-storage path.
Signed-in app participant or a valid app-scoped embed session. Current app publication, grants, field scope, and record assignments are checked.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
| workspaceId | path | Yes | Exact workspaceId from the authorized application context; it does not grant access. |
| appId | path | Yes | Exact 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
Authorize an authenticated embed session
Supports authorized embed-session setup and revocation through the app’s current access policy.
Signed-in app participant or a valid app-scoped embed session. Current app publication, grants, field scope, and record assignments are checked.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
| workspaceId | path | Yes | Exact workspaceId from the authorized application context; it does not grant access. |
| appId | path | Yes | Exact 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
Manage an admitted integration source
Reads connections and sources and dispatches supported reviewed preparation, preview, pause, disconnect, synchronization, or reconciliation operations.
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
Acknowledge workspace integration access
Reports private-preview eligibility and current workspace admission. POST records the explicit permissions acknowledgment against the expected epoch.
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
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.
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
Suggest or accept an integration setup plan
Provides admitted integration planning and reviewed acceptance of supported setup suggestions.
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
Review and manage integration operations
Prepares, applies, cancels, or reconciles supported integration operations under their current review and transport rules.
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
Manage a development connection attempt
Supports reviewed development connection configuration, begin/finish, cancellation, and disconnect.
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
Review a supported platform recovery action
Reads private platform setup status and handles explicit supported recovery actions.
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
Review or advance account setup
Supports connection review, existing-account selection, begin/finish, and cancellation in the shared connection journey.
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
Review or discover PostgreSQL tables
Runs the implemented PostgreSQL source discovery path after its exact setup review.
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
Preview or import PostgreSQL records
Handles reviewed bounded reads, mapping-preview edits, import review/application, receipts, and cancellation.
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
Create or review an integration setup
Creates, edits, refreshes, previews, reviews, applies, or discards supported source setup definitions.
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
Review or manage a supported source sync
Supports reviewed activation, pause, conflict comparison, reconciliation, and resolution for implemented admitted sources.
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
Discover or configure an available tool
Lists, describes, configures, or reloads supported tools from an owned connected account.
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
Review supported two-way operations
Handles configuration previews, reviews, dispatch, conflicts, and reconciliation for the implemented transport; explicit fixture simulation remains labeled.
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
Record MCP OAuth consent
Validates the configured OAuth client and authenticated user before exposing or saving consent.
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
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.
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
Decide access or queue an invitation
Authorized early-access administrators can inspect grants, audit/outbox state, decide access, and explicitly queue supported invitations.
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
Submit a public app response
Validates final answers and commits an accepted public submission through its idempotent app service.
Published public app policy and, where required, an app-bound resume or embed-exchange session. Public intake never grants workspace membership.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
| workspaceId | path | Yes | Exact workspaceId from the authorized application context; it does not grant access. |
| appId | path | Yes | Exact 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
Upload a file for an app input
Accepts a bounded multipart upload through the app-specific upload-intent and private-storage path.
Published public app policy and, where required, an app-bound resume or embed-exchange session. Public intake never grants workspace membership.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
| workspaceId | path | Yes | Exact workspaceId from the authorized application context; it does not grant access. |
| appId | path | Yes | Exact 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
Manage a public-app resume or embed exchange
Supports explicit create/read/save/resume/revoke progress actions and the approved embed-code exchange.
Published public app policy and, where required, an app-bound resume or embed-exchange session. Public intake never grants workspace membership.
Parameters
| Name | Location | Required | Description |
|---|---|---|---|
| workspaceId | path | Yes | Exact workspaceId from the authorized application context; it does not grant access. |
| appId | path | Yes | Exact 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
Receive a Clerk deletion webhook
Receives the provider-verified Clerk deletion event through the durable account-deletion integration.
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.
No endpoints match. Try a broader search or choose all methods and areas.