[ { "id": "get-api-session", "method": "GET", "path": "/api/session", "group": "Identity", "summary": "Read the current session", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns user, workspace, access, workspaces, members, and capabilities. Paged mode uses a bounded session response.", "notes": [ "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." ], "parameters": [ { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." }, { "name": "X-Ralti-Workspace-Mode", "in": "header", "required": false, "description": "Set to paged to receive workspace metadata and bounded initial data rather than assuming every sheet is fully loaded." }, { "name": "initialSheet", "in": "query", "required": false, "description": "Optional initial sheet ID when X-Ralti-Workspace-Mode is paged." }, { "name": "view / query / q / archived", "in": "query", "required": false, "description": "Initial paged-sheet view, search (query or q), and archived=true options." } ] }, { "id": "post-api-auth", "method": "POST", "path": "/api/auth", "group": "Identity", "summary": "Authenticate locally or link an existing account", "auth": "Clerk link/start_new requires a verified Clerk identity and any required legacy proof. Local signup/signin/signout use the local authentication boundary.", "description": "Clerk deployments accept only link and start_new after a verified Clerk identity. Explicit local mode accepts signup, signin, and signout.", "notes": [ "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." ], "parameters": [ { "name": "mode", "in": "body", "required": true, "description": "clerk: link | start_new; local: signup | signin | signout." }, { "name": "email", "in": "body", "required": false, "description": "Required for local signin/signup or password-based legacy proof." }, { "name": "password", "in": "body", "required": false, "description": "10\u2013256 characters for local sign-in/signup and legacy proof." }, { "name": "name", "in": "body", "required": false, "description": "Required local signup name, nonempty and at most 100 characters." } ], "requestExample": { "mode": "start_new" } }, { "id": "post-api-mobile-auth-exchange", "method": "POST", "path": "/api/mobile/auth/exchange", "group": "Identity", "summary": "Complete an installed iOS sign-in handoff", "auth": "A valid, unexpired, single-use sign-in handoff code and its matching device verifier. An exact same-origin browser Origin header is required.", "description": "An app-managed step used by the installed iOS app\u2019s 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.", "notes": [ "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." ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "The exact configured application origin, supplied by the shared finish page." }, { "name": "code", "in": "body", "required": true, "description": "The one-use code returned by the authorized system sign-in handoff." }, { "name": "verifier", "in": "body", "required": true, "description": "The matching private verifier retained by the initiating device." } ] }, { "id": "get-api-workspaces", "method": "GET", "path": "/api/workspaces", "group": "Workspace", "summary": "List accessible workspaces", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns {workspaces:[...]}, limited to workspaces accessible to the actor.", "notes": [], "responseExample": { "workspaces": [] } }, { "id": "post-api-workspaces", "method": "POST", "path": "/api/workspaces", "group": "Workspace", "summary": "Create, switch, or rename a workspace", "auth": "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.", "description": "Applies action create, switch, or rename and returns the resulting session response.", "notes": [ "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." ], "parameters": [ { "name": "action", "in": "body", "required": true, "description": "create | switch | rename." }, { "name": "name", "in": "body", "required": false, "description": "Name for create or rename." }, { "name": "workspaceId", "in": "body", "required": false, "description": "Target workspace for switch; membership required." } ], "requestExample": { "action": "create", "name": "Example projects" } }, { "id": "post-api-actions", "method": "POST", "path": "/api/actions", "group": "Actions", "summary": "Apply a validated operation batch", "auth": "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.", "description": "Validates and atomically applies the operation array, checks the expected workspace revision, and returns the application result with authoritative workspace and runs.", "notes": [ "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." ], "parameters": [ { "name": "operations", "in": "body", "required": true, "description": "Array of supported Operation objects; at most 500 operations." }, { "name": "expectedRevision", "in": "body", "required": true, "description": "Integer workspace revision from the server-owned workspace or proposal being applied." }, { "name": "confirmed", "in": "body", "required": false, "description": "true when the reviewed operation batch requires explicit confirmation." }, { "name": "aiJobId", "in": "body", "required": false, "description": "Optional owned, completed saved job ID; its application receipt commits with the mutation." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." }, { "name": "X-Ralti-Workspace-Mode", "in": "header", "required": false, "description": "Set to paged to receive workspace metadata and bounded initial data rather than assuming every sheet is fully loaded." } ], "requestExample": { "operations": [ { "action": "update_item", "spaceId": "sheet_projects", "itemId": "record_example", "notes": "Reviewed launch checklist." } ], "expectedRevision": 7 } }, { "id": "post-api-history", "method": "POST", "path": "/api/history", "group": "Actions", "summary": "Undo or redo the current history entry", "auth": "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.", "description": "Applies an undo or redo with a revision check, then returns {workspace}.", "notes": [ "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." ], "parameters": [ { "name": "direction", "in": "body", "required": true, "description": "undo | redo." }, { "name": "expectedRevision", "in": "body", "required": true, "description": "Integer workspace revision from the server-owned workspace or proposal being applied." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." }, { "name": "X-Ralti-Workspace-Mode", "in": "header", "required": false, "description": "Set to paged to receive workspace metadata and bounded initial data rather than assuming every sheet is fully loaded." } ], "requestExample": { "direction": "undo", "expectedRevision": 8 } }, { "id": "get-api-record-versions", "method": "GET", "path": "/api/record-versions", "group": "Actions", "summary": "Read saved versions of a record", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns {versions:[...]} for the authorized sheet and record.", "notes": [ "Versions are governed record evidence, separate from workspace undo/redo." ], "parameters": [ { "name": "spaceId", "in": "query", "required": true, "description": "Sheet identifier." }, { "name": "itemId", "in": "query", "required": true, "description": "Record identifier." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ], "responseExample": { "versions": [] } }, { "id": "get-api-records", "method": "GET", "path": "/api/records", "group": "Records", "summary": "Page workspace records", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns workspaceId, revision, records:[{spaceId,item}], total, nextCursor, labels, and counts for all/assigned/due records.", "notes": [ "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." ], "parameters": [ { "name": "scope", "in": "query", "required": false, "description": "all (default), assigned, or due; other values normalize to all." }, { "name": "query", "in": "query", "required": false, "description": "Optional text search." }, { "name": "today", "in": "query", "required": false, "description": "Date used for due scope." }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous response." }, { "name": "limit", "in": "query", "required": false, "description": "Integer 1\u2013100; default 100." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "get-api-sheets-id-items", "method": "GET", "path": "/api/sheets/{id}/items", "group": "Records", "summary": "Page records in a sheet", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns a SheetPage: workspaceId, spaceId, revision, items, total, nextCursor, and labels.", "notes": [ "The server validates sheet/view/item scope and enforces access.", "Cursor belongs to one query identity and revision; changing either requires starting again." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "view", "in": "query", "required": false, "description": "Saved view identifier used for filtering/sorting." }, { "name": "query", "in": "query", "required": false, "description": "Search text." }, { "name": "archived", "in": "query", "required": false, "description": "Literal true selects archived records." }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous response." }, { "name": "limit", "in": "query", "required": false, "description": "Integer 1\u2013100; default 100." }, { "name": "item", "in": "query", "required": false, "description": "Fetch a specific item." }, { "name": "items", "in": "query", "required": false, "description": "JSON-encoded array of record IDs." }, { "name": "exact", "in": "query", "required": false, "description": "Literal true selects exact-label matching." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "get-api-sheets-id-export", "method": "GET", "path": "/api/sheets/{id}/export", "group": "Records", "summary": "Download a sheet export", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Exports the authorized sheet as CSV when format=csv, or JSON otherwise.", "notes": [ "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." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "format", "in": "query", "required": false, "description": "csv for text/csv; any other/omitted value gives application/json." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "get-api-search-status", "method": "GET", "path": "/api/search/status", "group": "Records", "summary": "Read permitted search-index status", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns workspaceId, keywordSearch, semanticSearch configuration/model/dimensions/sources, and coverage.", "notes": [ "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." ], "parameters": [ { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "post-api-interpret", "method": "POST", "path": "/api/interpret", "group": "AI", "summary": "Interpret an immediate request", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Produces a proposal without applying it. Supports JSON or a request-connected NDJSON stream.", "notes": [ "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." ], "parameters": [ { "name": "request", "in": "body", "required": true, "description": "Nonempty instruction, at most 5,000 characters." }, { "name": "interpretationMode", "in": "body", "required": false, "description": "ai (default) or explicit built_in." }, { "name": "intent", "in": "body", "required": false, "description": "ask (answer-only) or edit." }, { "name": "stream", "in": "body", "required": false, "description": "true requests NDJSON progress events." }, { "name": "spaceId / workbookId / insightId / viewId", "in": "body", "required": false, "description": "Optional validated context identifiers." }, { "name": "selectedItemIds", "in": "body", "required": false, "description": "Up to 1,000 selected record IDs." }, { "name": "conversation / pendingDraft / draftJobId", "in": "body", "required": false, "description": "Bounded prior conversation or owned saved-draft context." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ], "requestExample": { "request": "Summarize the open projects.", "intent": "ask", "interpretationMode": "ai" } }, { "id": "post-api-ai-jobs", "method": "POST", "path": "/api/ai-jobs", "group": "AI", "summary": "Create a durable AI job", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Persists a private actor/workspace-scoped request and returns its public AiJob with HTTP 202.", "notes": [ "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." ], "parameters": [ { "name": "request", "in": "body", "required": true, "description": "Nonempty instruction, at most 5,000 characters." }, { "name": "clientRequestId", "in": "body", "required": false, "description": "Optional retry deduplication identifier, 8\u2013100 letters, digits, underscore or hyphen." }, { "name": "intent", "in": "body", "required": false, "description": "ask or edit." }, { "name": "spaceId / workbookId / insightId / viewId / selectedItemIds", "in": "body", "required": false, "description": "Optional validated context." }, { "name": "conversation / pendingDraft / draftJobId", "in": "body", "required": false, "description": "Bounded conversation or owned saved-draft refinement context." }, { "name": "resumeJobId", "in": "body", "required": false, "description": "Failed, undismissed job to resume with exactly matching saved request/context." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ], "requestExample": { "request": "Summarize the open projects.", "intent": "ask", "clientRequestId": "example_request_0001" } }, { "id": "get-api-ai-jobs", "method": "GET", "path": "/api/ai-jobs", "group": "AI", "summary": "List saved AI jobs", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns {jobs:[...]} for the requesting actor in the selected workspace.", "notes": [ "The service lists up to 20 undismissed jobs, prioritizing active work. Membership is rechecked." ], "parameters": [ { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ], "responseExample": { "jobs": [] } }, { "id": "get-api-ai-jobs-id", "method": "GET", "path": "/api/ai-jobs/{id}", "group": "AI", "summary": "Read an owned AI job", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns the public AiJob state and any completed proposal.", "notes": [ "A workspace teammate cannot read another actor\u2019s private job merely by knowing its ID." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "delete-api-ai-jobs-id", "method": "DELETE", "path": "/api/ai-jobs/{id}", "group": "AI", "summary": "Cancel or dismiss an AI job", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Requests cancellation for active work or dismisses a finished request; returns the resulting public AiJob.", "notes": [ "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." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "patch-api-ai-jobs-id", "method": "PATCH", "path": "/api/ai-jobs/{id}", "group": "AI", "summary": "Edit or refresh a saved draft", "auth": "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.", "description": "For a completed, unapplied, undismissed job, accepts sheetNames, validated operations, or rebase:true and returns the updated public AiJob.", "notes": [ "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." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "sheetNames", "in": "body", "required": false, "description": "Alternative body: array of {spaceId,name}, 1\u2013100 unique sheet IDs; names up to 200 characters." }, { "name": "operations", "in": "body", "required": false, "description": "Alternative body: nonempty validated Operation array for the draft." }, { "name": "rebase", "in": "body", "required": false, "description": "Alternative body: true requests safe refresh against unchanged dependencies." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ], "requestExample": { "rebase": true } }, { "id": "post-api-attachments", "method": "POST", "path": "/api/attachments", "group": "Files", "summary": "Upload a private attachment", "auth": "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.", "description": "Accepts multipart/form-data with a nonempty file field and returns {url,name} with HTTP 201.", "notes": [ "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." ], "parameters": [ { "name": "file", "in": "formData", "required": true, "description": "Nonempty file, at most 10 MiB." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ], "responseExample": { "url": "/api/attachments/00000000-0000-4000-8000-000000000001", "name": "example.pdf" } }, { "id": "get-api-attachments-id", "method": "GET", "path": "/api/attachments/{id}", "group": "Files", "summary": "Download or preview an attachment", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Checks membership against the attachment\u2019s actual workspace before returning private bytes.", "notes": [ "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." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "preview", "in": "query", "required": false, "description": "1 permits inline rendering only for stored PNG/JPEG/WebP/GIF/AVIF MIME types." } ] }, { "id": "get-api-dashboard", "method": "GET", "path": "/api/dashboard", "group": "Insights", "summary": "Read a workbook overview", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Computes the authorized workbook dashboard from server-owned data.", "notes": [ "This workbook overview differs from saved insight document queries." ], "parameters": [ { "name": "workbookId", "in": "query", "required": true, "description": "Existing workbook ID." }, { "name": "sheetId", "in": "query", "required": false, "description": "all (default) or a sheet belonging to this workbook." }, { "name": "today", "in": "query", "required": false, "description": "YYYY-MM-DD date; defaults to server UTC date." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "post-api-insights-query", "method": "POST", "path": "/api/insights/query", "group": "Insights", "summary": "Query a dashboard/report layout", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Evaluates a validated InsightDocument against authorized server data without saving the layout.", "notes": [ "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." ], "parameters": [ { "name": "document", "in": "body", "required": true, "description": "InsightDocument validated by insightDocumentSchema." }, { "name": "blockId", "in": "body", "required": false, "description": "Optional block in that document." }, { "name": "groupKey", "in": "body", "required": false, "description": "Optional group drilldown; requires blockId." }, { "name": "offset", "in": "body", "required": false, "description": "Integer 0\u20131,000,000." }, { "name": "limit", "in": "body", "required": false, "description": "Integer 1\u2013100." }, { "name": "today", "in": "body", "required": false, "description": "Optional ISO date." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "post-api-insights-preview", "method": "POST", "path": "/api/insights/preview", "group": "Insights", "summary": "Preview a proposed insight layout", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Stages operations in memory against the exact expected revision, finds documentId in that preview, and computes its result without saving.", "notes": [ "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." ], "parameters": [ { "name": "operations", "in": "body", "required": true, "description": "1\u2013500 operations to stage." }, { "name": "documentId", "in": "body", "required": true, "description": "Insight document present in the staged layout." }, { "name": "expectedRevision", "in": "body", "required": true, "description": "Integer workspace revision from the server-owned workspace or proposal being applied." }, { "name": "blockId / groupKey / offset / limit / today", "in": "body", "required": false, "description": "Optional drilldown fields; groupKey requires blockId, limit 1\u2013100, offset 0\u20131,000,000." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "get-api-documents", "method": "GET", "path": "/api/documents", "group": "Documents", "summary": "Read document templates, drafts, and versions", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "With workbookId returns templates/documents; with documentId returns {document}; adding version returns {version,snapshot}; recordSpaceId+recordId returns sourceRecord/documents.", "notes": [ "Record selectors take precedence over document/workbook selection. Access is enforced for every requested resource." ], "parameters": [ { "name": "workbookId", "in": "query", "required": false, "description": "Workbook to list when other selectors are absent." }, { "name": "documentId", "in": "query", "required": false, "description": "Existing document to inspect." }, { "name": "version", "in": "query", "required": false, "description": "Version selector when documentId is present; an empty selector requests service default." }, { "name": "recordSpaceId", "in": "query", "required": false, "description": "Sheet of a related record; required together with recordId." }, { "name": "recordId", "in": "query", "required": false, "description": "Related record; required together with recordSpaceId." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "post-api-documents", "method": "POST", "path": "/api/documents", "group": "Documents", "summary": "Manage document templates and drafts", "auth": "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.", "description": "Dispatches save_template, create_draft, create_batch, save_draft, preview, finalize, or revise through the document service.", "notes": [ "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." ], "parameters": [ { "name": "action", "in": "body", "required": true, "description": "save_template | create_draft | create_batch | save_draft | preview | finalize | revise." }, { "name": "template", "in": "body", "required": false, "description": "Required for save_template and preview; validated document template." }, { "name": "templateId", "in": "body", "required": false, "description": "Required for create_draft/create_batch." }, { "name": "sourceItemId / sourceSpaceId / name", "in": "body", "required": false, "description": "Optional draft context; accepted fields vary by action." }, { "name": "sourceItemIds", "in": "body", "required": false, "description": "1\u2013100 IDs for create_batch; duplicate IDs are deduplicated." }, { "name": "documentId / revision", "in": "body", "required": false, "description": "Required for save_draft/finalize/revise; revision is a positive document revision, not workspace expectedRevision." }, { "name": "layout", "in": "body", "required": false, "description": "Required for save_draft." } ], "requestExample": { "action": "finalize", "documentId": "document_example", "revision": 1 } }, { "id": "post-api-documents-plan", "method": "POST", "path": "/api/documents/plan", "group": "Documents", "summary": "Plan a document template", "auth": "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.", "description": "Produces {template} from a prompt and workbook context without saving the result.", "notes": [ "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." ], "parameters": [ { "name": "workbookId", "in": "body", "required": true, "description": "Workbook identifier, up to 160 characters." }, { "name": "prompt", "in": "body", "required": true, "description": "Nonempty prompt, up to 5,000 characters." }, { "name": "sourceSpaceId", "in": "body", "required": false, "description": "Optional source sheet ID." }, { "name": "template", "in": "body", "required": false, "description": "Optional existing validated template to refine." } ], "requestExample": { "workbookId": "workbook_projects", "prompt": "Create a clear project summary with client and due date." } }, { "id": "get-api-documents-id-pdf", "method": "GET", "path": "/api/documents/{id}/pdf", "group": "Documents", "summary": "Download a saved document PDF", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Reads the authorized finalized version and returns its PDF bytes.", "notes": [ "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." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "version", "in": "query", "required": false, "description": "Optional version selector; omitted uses the service default." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "get-api-workbook-templates", "method": "GET", "path": "/api/workbook-templates", "group": "Templates", "summary": "List saved workbook templates", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns {templates:[...]} for the selected workspace.", "notes": [], "parameters": [ { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ], "responseExample": { "templates": [] } }, { "id": "post-api-workbook-templates", "method": "POST", "path": "/api/workbook-templates", "group": "Templates", "summary": "Save a reusable workbook template", "auth": "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.", "description": "Captures an existing workbook structure and document layouts without its business records, returning {template}.", "notes": [ "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." ], "parameters": [ { "name": "workbookId", "in": "body", "required": true, "description": "Existing workbook to capture." }, { "name": "name", "in": "body", "required": true, "description": "Trimmed name, 1\u2013100 characters." }, { "name": "description", "in": "body", "required": false, "description": "Description up to 1,000 characters; defaults empty." } ], "requestExample": { "workbookId": "workbook_projects", "name": "Project delivery", "description": "Reusable project structure." } }, { "id": "post-api-workbook-templates-install", "method": "POST", "path": "/api/workbook-templates/install", "group": "Templates", "summary": "Preview or install a saved template", "auth": "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.", "description": "Instantiates a saved template with chosen name and reuse mapping; preview:true returns the staged plan instead of installing.", "notes": [ "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}." ], "parameters": [ { "name": "templateId", "in": "body", "required": true, "description": "Saved template ID." }, { "name": "name", "in": "body", "required": true, "description": "New workbook name, 1\u2013100 characters." }, { "name": "expectedRevision", "in": "body", "required": true, "description": "Integer workspace revision from the server-owned workspace or proposal being applied." }, { "name": "reuse", "in": "body", "required": false, "description": "String-to-string mapping of template sheet IDs to existing sheets; defaults {}." }, { "name": "requestId", "in": "body", "required": false, "description": "8\u2013100 character deduplication identifier; required when preview is false." }, { "name": "preview", "in": "body", "required": false, "description": "Boolean, default false." } ], "requestExample": { "templateId": "template_example", "name": "New delivery workbook", "expectedRevision": 7, "preview": true } }, { "id": "post-api-templates-install", "method": "POST", "path": "/api/templates/install", "group": "Templates", "summary": "Install a reviewed built-in template", "auth": "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.", "description": "Installs a recognized built-in template from a validated reviewed operation batch and matching workspace revision.", "notes": [ "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." ], "parameters": [ { "name": "templateId", "in": "body", "required": true, "description": "ID from WORKSPACE_TEMPLATES; not an arbitrary user-supplied template name." }, { "name": "operations", "in": "body", "required": true, "description": "1\u2013500 validated template operations including create_workbook." }, { "name": "expectedRevision", "in": "body", "required": true, "description": "Integer workspace revision from the server-owned workspace or proposal being applied." } ] }, { "id": "get-api-team", "method": "GET", "path": "/api/team", "group": "Collaboration", "summary": "Read team state", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns members, permitted invitations, activity, notifications, and presence.", "notes": [ "Invitations are returned only to members with management access." ], "parameters": [ { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "post-api-team", "method": "POST", "path": "/api/team", "group": "Collaboration", "summary": "Manage invitations, members, or notifications", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Dispatches invite, accept_invite, revoke_invite, update_member, remove_member, or read_notifications.", "notes": [ "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\u2019s 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." ], "parameters": [ { "name": "action", "in": "body", "required": true, "description": "invite | accept_invite | revoke_invite | update_member | remove_member | read_notifications." }, { "name": "email / role / sendEmail", "in": "body", "required": false, "description": "For invite: email and invitable role; optional boolean sendEmail." }, { "name": "token", "in": "body", "required": false, "description": "For accept_invite." }, { "name": "invitationId", "in": "body", "required": false, "description": "For revoke_invite." }, { "name": "userId / role", "in": "body", "required": false, "description": "For update_member; userId alone for remove_member." }, { "name": "ids", "in": "body", "required": false, "description": "For read_notifications: up to 100 notification IDs; omitted marks all own unread notifications." } ], "requestExample": { "action": "read_notifications" } }, { "id": "get-api-comments", "method": "GET", "path": "/api/comments", "group": "Collaboration", "summary": "Read a record discussion", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns {comments:[...]} for an accessible record.", "notes": [], "parameters": [ { "name": "spaceId", "in": "query", "required": true, "description": "Record sheet." }, { "name": "itemId", "in": "query", "required": true, "description": "Record ID." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ], "responseExample": { "comments": [] } }, { "id": "post-api-comments", "method": "POST", "path": "/api/comments", "group": "Collaboration", "summary": "Add or delete a comment", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Adds a record comment/reply or deletes an authorized comment; returns {comments}.", "notes": [ "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." ], "parameters": [ { "name": "action", "in": "body", "required": true, "description": "add | delete." }, { "name": "spaceId / itemId / body", "in": "body", "required": false, "description": "Required for add; body is nonempty, up to 5,000 characters." }, { "name": "mentions", "in": "body", "required": false, "description": "Optional up to 25 current member IDs." }, { "name": "parentId", "in": "body", "required": false, "description": "Optional original comment ID for a reply on the same record." }, { "name": "commentId", "in": "body", "required": false, "description": "Required for delete." } ], "requestExample": { "action": "add", "spaceId": "sheet_projects", "itemId": "record_example", "body": "The launch checklist is ready for review." } }, { "id": "get-api-events", "method": "GET", "path": "/api/events", "group": "Collaboration", "summary": "Poll revision and presence", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns workspaceId, revision, presence, and unreadCount.", "notes": [ "This is a JSON polling endpoint, not an SSE event stream." ], "parameters": [ { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "post-api-events", "method": "POST", "path": "/api/events", "group": "Collaboration", "summary": "Update presence and read events", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Saves the actor\u2019s presence (optional sheet) and returns the same event snapshot.", "notes": [ "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." ], "parameters": [ { "name": "spaceId", "in": "body", "required": false, "description": "Optional current sheet identifier." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ], "requestExample": {} }, { "id": "get-api-workflows", "method": "GET", "path": "/api/workflows", "group": "Workflows", "summary": "Read helper runs and workspace", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns {runs,workspace} for the selected workspace.", "notes": [], "parameters": [ { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." }, { "name": "X-Ralti-Workspace-Mode", "in": "header", "required": false, "description": "Set to paged to receive workspace metadata and bounded initial data rather than assuming every sheet is fully loaded." } ] }, { "id": "post-api-workflows", "method": "POST", "path": "/api/workflows", "group": "Workflows", "summary": "Run or review a helper", "auth": "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.", "description": "Runs a saved workflow/agent or applies/dismisses an existing run.", "notes": [ "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." ], "parameters": [ { "name": "action", "in": "body", "required": true, "description": "run | apply | dismiss." }, { "name": "workflowId", "in": "body", "required": false, "description": "Required for run." }, { "name": "runId", "in": "body", "required": false, "description": "Required for apply or dismiss." }, { "name": "expectedRevision", "in": "body", "required": false, "description": "Workspace revision used by the reviewed/run request; repository checks govern the action." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ], "requestExample": { "action": "run", "workflowId": "workflow_example", "expectedRevision": 7 } }, { "id": "get-api-workflows-id-email-source", "method": "GET", "path": "/api/workflows/{id}/email-source", "group": "Workflows", "summary": "Read an agent\u2019s email grant", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns {source:null} when absent, or source configuration, grant identity/time, ownership, validity, and optional reason.", "notes": [ "ID must identify a saved agent. A grant can be invalid after behavioral edits, mailbox disconnection, or loss of the grantor\u2019s access." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ], "responseExample": { "source": null } }, { "id": "put-api-workflows-id-email-source", "method": "PUT", "path": "/api/workflows/{id}/email-source", "group": "Workflows", "summary": "Grant a scoped email source to an agent", "auth": "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.", "description": "Grants access to a saved agent from a connected mailbox owned by the grantor, after revision and editing checks.", "notes": [ "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." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "config", "in": "body", "required": true, "description": "{connectionId,folder,days,limit,sender,subject,unreadOnly}; folder inbox|sent, days 1|7|30|90, limit 1\u201325, text filters max 200 characters." }, { "name": "expectedRevision", "in": "body", "required": true, "description": "Integer workspace revision from the server-owned workspace or proposal being applied." } ], "requestExample": { "config": { "connectionId": "mailbox_example", "folder": "inbox", "days": 7, "limit": 10, "sender": "", "subject": "Project", "unreadOnly": true }, "expectedRevision": 7 } }, { "id": "delete-api-workflows-id-email-source", "method": "DELETE", "path": "/api/workflows/{id}/email-source", "group": "Workflows", "summary": "Revoke an agent\u2019s email source", "auth": "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.", "description": "Revokes the source under service ownership/management checks and returns {source:null}.", "notes": [ "Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." } ], "responseExample": { "source": null } }, { "id": "get-api-email", "method": "GET", "path": "/api/email", "group": "Email", "summary": "Read the email dashboard", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns provider availability, categories/categoryRevision, connections, counts/metrics, visible threads, draft summaries, and bounded page data.", "notes": [ "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." ], "parameters": [ { "name": "connectionId", "in": "query", "required": false, "description": "Limit to one accessible mailbox." }, { "name": "folder", "in": "query", "required": false, "description": "inbox | sent | awaiting_reply | drafts | unread | starred | archive | trash." }, { "name": "category", "in": "query", "required": false, "description": "Category ID or uncategorized; category filtering is owner-only." }, { "name": "spaceId", "in": "query", "required": false, "description": "Linked record sheet filter." }, { "name": "itemId", "in": "query", "required": false, "description": "Linked record filter." }, { "name": "query", "in": "query", "required": false, "description": "Search matching latest-message subject/preview/participant text." }, { "name": "cursor", "in": "query", "required": false, "description": "Email page cursor." }, { "name": "limit", "in": "query", "required": false, "description": "Thread-page requested size; /threads clamps to 1\u201350, default 30." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "get-api-email-threads", "method": "GET", "path": "/api/email/threads", "group": "Email", "summary": "Page visible email threads", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns {threads,filteredCount?,nextCursor?}.", "notes": [ "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." ], "parameters": [ { "name": "connectionId", "in": "query", "required": false, "description": "Limit to one accessible mailbox." }, { "name": "folder", "in": "query", "required": false, "description": "inbox | sent | awaiting_reply | drafts | unread | starred | archive | trash." }, { "name": "category", "in": "query", "required": false, "description": "Category ID or uncategorized; category filtering is owner-only." }, { "name": "spaceId", "in": "query", "required": false, "description": "Linked record sheet filter." }, { "name": "itemId", "in": "query", "required": false, "description": "Linked record filter." }, { "name": "query", "in": "query", "required": false, "description": "Search matching latest-message subject/preview/participant text." }, { "name": "cursor", "in": "query", "required": false, "description": "Email page cursor." }, { "name": "limit", "in": "query", "required": false, "description": "Thread-page requested size; /threads clamps to 1\u201350, default 30." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ], "responseExample": { "threads": [], "filteredCount": 0 } }, { "id": "get-api-email-threads-id", "method": "GET", "path": "/api/email/threads/{id}", "group": "Email", "summary": "Read a conversation", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns {thread,messages,nextCursor?} after private/shared conversation authorization.", "notes": [ "Only synchronized, visible messages are included. A shared thread does not confer general mailbox access." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "cursor", "in": "query", "required": false, "description": "Optional next message-page cursor." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "patch-api-email-threads-id", "method": "PATCH", "path": "/api/email/threads/{id}", "group": "Email", "summary": "Link or share a conversation", "auth": "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.", "description": "Mailbox owner updates a record link and private/workspace visibility; returns the thread detail.", "notes": [ "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." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "link", "in": "body", "required": false, "description": "{spaceId,itemId} or null; referenced record must be accessible." }, { "name": "visibility", "in": "body", "required": false, "description": "private | workspace." }, { "name": "shared", "in": "body", "required": false, "description": "Legacy boolean alternative when visibility is omitted." } ], "requestExample": { "link": { "spaceId": "sheet_clients", "itemId": "record_example" }, "visibility": "workspace" } }, { "id": "patch-api-email-threads-id-actions", "method": "PATCH", "path": "/api/email/threads/{id}/actions", "group": "Email", "summary": "Organize an email conversation", "auth": "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.", "description": "Performs one supported owner action and returns updated thread detail.", "notes": [ "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." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "action", "in": "body", "required": true, "description": "read | unread | star | unstar | archive | trash | restore | categorize." }, { "name": "category", "in": "body", "required": false, "description": "Category ID or null; only accepted with categorize." } ], "requestExample": { "action": "read" } }, { "id": "post-api-email-sync", "method": "POST", "path": "/api/email/sync", "group": "Email", "summary": "Synchronize a connected mailbox", "auth": "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.", "description": "Runs synchronization for the requested owned connection and returns its service result.", "notes": [ "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." ], "parameters": [ { "name": "connectionId", "in": "body", "required": true, "description": "Connected mailbox identifier." } ], "requestExample": { "connectionId": "mailbox_example" } }, { "id": "delete-api-email-connections-id", "method": "DELETE", "path": "/api/email/connections/{id}", "group": "Email", "summary": "Disconnect a mailbox", "auth": "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.", "description": "Disconnects an owned connection and returns {disconnected:true}.", "notes": [ "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." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." } ], "responseExample": { "disconnected": true } }, { "id": "patch-api-email-connections-id-sorting", "method": "PATCH", "path": "/api/email/connections/{id}/sorting", "group": "Email", "summary": "Configure incoming email sorting", "auth": "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.", "description": "Updates owned mailbox sorting and returns its public EmailConnection.", "notes": [ "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." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "enabled", "in": "body", "required": true, "description": "Boolean sorting state." }, { "name": "instructions", "in": "body", "required": false, "description": "Optional text up to 1,000 characters." } ], "requestExample": { "enabled": true, "instructions": "Prioritize direct customer questions." } }, { "id": "post-api-email-google-authorize", "method": "POST", "path": "/api/email/google/authorize", "group": "Email authorization", "summary": "Begin Google authorization", "auth": "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.", "description": "Creates a short-lived OAuth flow for an editing account and returns {url} for browser navigation.", "notes": [ "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." ], "requestExample": {} }, { "id": "get-api-email-google-callback", "method": "GET", "path": "/api/email/google/callback", "group": "Email authorization", "summary": "Complete Google authorization", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Consumes the provider code/state for the signed-in user and redirects back to the application email page.", "notes": [ "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." ], "parameters": [ { "name": "code", "in": "query", "required": false, "description": "OAuth authorization code returned by the provider." }, { "name": "state", "in": "query", "required": false, "description": "Server-issued OAuth state returned by the provider." }, { "name": "error", "in": "query", "required": false, "description": "Provider-declared consent failure/cancellation." } ] }, { "id": "post-api-email-microsoft-authorize", "method": "POST", "path": "/api/email/microsoft/authorize", "group": "Email authorization", "summary": "Begin Microsoft authorization", "auth": "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.", "description": "Creates a short-lived OAuth flow for an editing account and returns {url} for browser navigation.", "notes": [ "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." ], "parameters": [ { "name": "sharedMailbox", "in": "body", "required": false, "description": "Optional shared mailbox email address." } ], "requestExample": {} }, { "id": "get-api-email-microsoft-callback", "method": "GET", "path": "/api/email/microsoft/callback", "group": "Email authorization", "summary": "Complete Microsoft authorization", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Consumes the provider code/state for the signed-in user and redirects back to the application email page.", "notes": [ "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." ], "parameters": [ { "name": "code", "in": "query", "required": false, "description": "OAuth authorization code returned by the provider." }, { "name": "state", "in": "query", "required": false, "description": "Server-issued OAuth state returned by the provider." }, { "name": "error", "in": "query", "required": false, "description": "Provider-declared consent failure/cancellation." } ] }, { "id": "post-api-email-imap-connect", "method": "POST", "path": "/api/email/imap/connect", "group": "Email authorization", "summary": "Connect an IMAP/SMTP mailbox", "auth": "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.", "description": "Validates mailbox credentials, verifies provider connectivity, and returns {connection,workspaceId}.", "notes": [ "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." ], "parameters": [ { "name": "address", "in": "body", "required": true, "description": "Mailbox email address." }, { "name": "username", "in": "body", "required": false, "description": "Defaults to address when omitted/empty." }, { "name": "password", "in": "body", "required": true, "description": "Mailbox app password; never log or return it." }, { "name": "displayName", "in": "body", "required": false, "description": "Optional name, at most 150 characters." }, { "name": "imap", "in": "body", "required": true, "description": "{host,port,secure}: 993/true or 143/false (required STARTTLS)." }, { "name": "smtp", "in": "body", "required": true, "description": "{host,port,secure}: 465/true or 587/false (required STARTTLS)." } ] }, { "id": "get-api-email-categories", "method": "GET", "path": "/api/email/categories", "group": "Email categories", "summary": "Read personal mailbox categories", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns {categories,revision} for the actor in this workspace.", "notes": [], "parameters": [ { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "put-api-email-categories", "method": "PUT", "path": "/api/email/categories", "group": "Email categories", "summary": "Replace personal mailbox categories", "auth": "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.", "description": "Saves the complete category list with its category-specific revision and returns categories, revision, and clearedThreads.", "notes": [ "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." ], "parameters": [ { "name": "categories", "in": "body", "required": true, "description": "Up to 30 {id,name,color,description} objects; IDs/names unique, reserved uncategorized ID prohibited." }, { "name": "expectedRevision", "in": "body", "required": true, "description": "Current category revision (not the workspace revision)." } ], "requestExample": { "categories": [ { "id": "client_requests", "name": "Client requests", "color": "blue", "description": "Questions and requests from current clients." } ], "expectedRevision": 0 } }, { "id": "post-api-email-categories-plan", "method": "POST", "path": "/api/email/categories/plan", "group": "Email categories", "summary": "Plan a category setup", "auth": "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.", "description": "Builds a reviewed category proposal without changing saved categories or reading mailbox message content.", "notes": [ "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." ], "parameters": [ { "name": "request", "in": "body", "required": true, "description": "Nonempty prompt, up to 4,000 characters." }, { "name": "baseRevision", "in": "body", "required": true, "description": "Current category revision." }, { "name": "conversation", "in": "body", "required": false, "description": "Up to 10 {role:user|assistant,content} turns; content up to 6,000 chars." }, { "name": "draft", "in": "body", "required": false, "description": "Optional existing category-array draft." } ], "requestExample": { "request": "Separate client questions from newsletters.", "baseRevision": 0 } }, { "id": "get-api-email-preferences", "method": "GET", "path": "/api/email/preferences", "group": "Email notifications", "summary": "Read notification preferences", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns preferences, notificationSender, canManageNotifications, and delivery counts.", "notes": [ "Preferences are per user/workspace. Sender and delivery visibility respect workspace management access." ], "parameters": [ { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "patch-api-email-preferences", "method": "PATCH", "path": "/api/email/preferences", "group": "Email notifications", "summary": "Update notification preferences or sender", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Updates personal boolean preferences and/or the workspace notification mailbox, then returns settings.", "notes": [ "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." ], "parameters": [ { "name": "preferences", "in": "body", "required": false, "description": "Optional subset of enabled, assignments, mentions, replies, salesReplies, workflows; every supplied value is boolean." }, { "name": "notificationSender", "in": "body", "required": false, "description": "Optional {connectionId:string|null}; owner/admin access and owned capable mailbox required." } ], "requestExample": { "preferences": { "enabled": true, "mentions": true } } }, { "id": "get-api-email-drafts", "method": "GET", "path": "/api/email/drafts", "group": "Email drafts", "summary": "List private email drafts", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns {drafts:[...]} for this actor/workspace.", "notes": [], "parameters": [ { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ], "responseExample": { "drafts": [] } }, { "id": "post-api-email-drafts", "method": "POST", "path": "/api/email/drafts", "group": "Email drafts", "summary": "Create a private email draft", "auth": "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.", "description": "Creates or deduplicates a draft for an owned connected mailbox and returns EmailDraft with HTTP 201.", "notes": [ "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." ], "parameters": [ { "name": "connectionId", "in": "body", "required": true, "description": "Owned connected mailbox ID." }, { "name": "clientRequestId", "in": "body", "required": true, "description": "Deduplication ID used for draft creation." }, { "name": "to", "in": "body", "required": true, "description": "Array of {address,name?} recipients." }, { "name": "cc / bcc", "in": "body", "required": false, "description": "Optional address arrays; total recipients at most 100." }, { "name": "subject", "in": "body", "required": true, "description": "Plain subject, max 998 characters, no newlines." }, { "name": "bodyText", "in": "body", "required": true, "description": "Plain text body, max 200,000 characters." }, { "name": "link", "in": "body", "required": false, "description": "Optional {spaceId,itemId} record link." }, { "name": "replyToMessageId", "in": "body", "required": false, "description": "Optional visible message ID from the same connection." } ], "requestExample": { "connectionId": "mailbox_example", "clientRequestId": "example_draft_0001", "to": [ { "address": "recipient@example.com" } ], "subject": "Project update", "bodyText": "Here is the update for your review." } }, { "id": "get-api-email-drafts-id", "method": "GET", "path": "/api/email/drafts/{id}", "group": "Email drafts", "summary": "Read a private email draft", "auth": "Clerk session cookie or Clerk bearer JWT; explicit local mode accepts its session cookie or opaque native bearer token. Current workspace membership is checked.", "description": "Returns EmailDraft for its creating actor in this workspace.", "notes": [ "EmailDraft fields include id, connectionId, recipients, subject, bodyText, status, createdAt, updatedAt, and optional sentAt/link/replyToMessageId/error." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ] }, { "id": "patch-api-email-drafts-id", "method": "PATCH", "path": "/api/email/drafts/{id}", "group": "Email drafts", "summary": "Edit an unsent draft", "auth": "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.", "description": "Merges provided draft fields with the original and returns the updated EmailDraft.", "notes": [ "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." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "to / cc / bcc / subject / bodyText / link / replyToMessageId", "in": "body", "required": false, "description": "Optional replacements using the same draft validation." } ], "requestExample": { "bodyText": "Updated project summary for review." } }, { "id": "delete-api-email-drafts-id", "method": "DELETE", "path": "/api/email/drafts/{id}", "group": "Email drafts", "summary": "Discard an unsent draft", "auth": "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.", "description": "Deletes a draft or failed message and returns {deleted:true}.", "notes": [ "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." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." } ], "responseExample": { "deleted": true } }, { "id": "post-api-email-drafts-id-send", "method": "POST", "path": "/api/email/drafts/{id}/send", "group": "Email drafts", "summary": "Queue an explicitly reviewed message", "auth": "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.", "description": "Queues one reviewed draft for durable delivery and returns EmailDraft with HTTP 202.", "notes": [ "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." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "confirmed", "in": "body", "required": true, "description": "Must be true after reviewing actual recipients and content." }, { "name": "clientRequestId", "in": "body", "required": true, "description": "Unique send deduplication identifier." }, { "name": "expectedUpdatedAt", "in": "body", "required": true, "description": "Exact updatedAt of the draft that was reviewed." } ], "requestExample": { "confirmed": true, "clientRequestId": "example_send_0001", "expectedUpdatedAt": "2026-01-01T12:00:00.000Z" } }, { "id": "post-api-email-drafts-id-reconcile", "method": "POST", "path": "/api/email/drafts/{id}/reconcile", "group": "Email drafts", "summary": "Reconcile an uncertain delivery", "auth": "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.", "description": "Checks provider evidence for an owned draft whose delivery outcome needs resolution and returns the updated draft.", "notes": [ "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." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." } ] }, { "id": "get-api-forms-workspaceid-viewid", "method": "GET", "path": "/api/forms/{workspaceId}/{viewId}", "group": "Public forms", "summary": "Read a published form", "auth": "Published-form capability in x-ralti-form-key. No signed-in account is required; the form must still be published and its capability valid.", "description": "Returns {form} only when the supplied capability identifies a currently published form.", "notes": [ "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." ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "viewId", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "x-ralti-form-key", "in": "header", "required": true, "description": "64 lowercase hexadecimal characters from the published form capability." } ] }, { "id": "post-api-forms-workspaceid-viewid", "method": "POST", "path": "/api/forms/{workspaceId}/{viewId}", "group": "Public forms", "summary": "Submit a published form", "auth": "Published-form capability in x-ralti-form-key. No signed-in account is required; the form must still be published and its capability valid.", "description": "Validates the form fields and creates its record atomically under the published-form capability.", "notes": [ "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." ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "viewId", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." }, { "name": "x-ralti-form-key", "in": "header", "required": true, "description": "Valid published-form capability." }, { "name": "submissionId", "in": "body", "required": true, "description": "UUID-shaped stable submission identifier; reusing it deduplicates a retry." }, { "name": "values", "in": "body", "required": true, "description": "Field-ID keyed values accepted by this published form." } ], "requestExample": { "submissionId": "00000000-0000-4000-8000-000000000001", "values": { "field_name": "Example request" } }, "responseExample": { "success": true, "message": "Thank you for your response." } }, { "id": "get-api-mcp-connections", "method": "GET", "path": "/api/mcp/connections", "group": "External AI", "summary": "List personal MCP connections", "auth": "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.", "description": "Returns {connections:[...]} for this signed-in actor and workspace; token secret is never listed.", "notes": [], "parameters": [ { "name": "X-Atlas-Workspace", "in": "header", "required": false, "description": "Optional workspace ID. Selects scope; never grants access. Omit to use the account preference." } ], "responseExample": { "connections": [] } }, { "id": "post-api-mcp-connections", "method": "POST", "path": "/api/mcp/connections", "group": "External AI", "summary": "Issue a scoped MCP connection", "auth": "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.", "description": "Creates a personal connection and returns {connection,token} with HTTP 201. The token is shown only at creation.", "notes": [ "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." ], "parameters": [ { "name": "name", "in": "body", "required": true, "description": "Trimmed connection name, 1\u201380 characters." }, { "name": "scopes", "in": "body", "required": true, "description": "Nonempty array: records:read, email:read, drafts:propose." }, { "name": "days", "in": "body", "required": true, "description": "Expiration: 7, 30, or 90." } ], "requestExample": { "name": "Example research connection", "scopes": [ "records:read" ], "days": 7 } }, { "id": "delete-api-mcp-connections-id", "method": "DELETE", "path": "/api/mcp/connections/{id}", "group": "External AI", "summary": "Revoke a personal MCP connection", "auth": "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.", "description": "Revokes an actor-owned connection in the selected workspace and returns {revoked:true}.", "notes": [ "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." ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identifier supplied by the corresponding Ralti resource; examples use synthetic IDs." } ], "responseExample": { "revoked": true } }, { "id": "post-api-mcp", "method": "POST", "path": "/api/mcp", "group": "External AI", "summary": "Use the MCP protocol transport", "auth": "Authorization: Bearer . This is a separately issued rlt_mcp_ credential bound to one actor/workspace and scopes, not a Clerk/local session.", "description": "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.", "notes": [ "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." ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer credential returned once by POST /api/mcp/connections." } ] }, { "id": "get-api-mcp", "method": "GET", "path": "/api/mcp", "group": "External AI", "summary": "Use the MCP protocol transport", "auth": "Authorization: Bearer . This is a separately issued rlt_mcp_ credential bound to one actor/workspace and scopes, not a Clerk/local session.", "description": "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.", "notes": [ "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." ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer credential returned once by POST /api/mcp/connections." } ] }, { "id": "delete-api-mcp", "method": "DELETE", "path": "/api/mcp", "group": "External AI", "summary": "Use the MCP protocol transport", "auth": "Authorization: Bearer . This is a separately issued rlt_mcp_ credential bound to one actor/workspace and scopes, not a Clerk/local session.", "description": "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.", "notes": [ "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." ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer credential returned once by POST /api/mcp/connections." } ] }, { "id": "get-api-health", "method": "GET", "path": "/api/health", "group": "Operations", "summary": "Check process liveness", "auth": "Public; bypasses Clerk middleware.", "description": "Returns {status:\"ok\"} without contacting the database or an external provider.", "notes": [ "Response is no-store and nosniff. HTTP 200 does not establish database, worker, OAuth, or provider readiness." ], "responseExample": { "status": "ok" } } ]