Meet the API.

Read the current session

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

Parameters

Behavior to know

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

Authenticate locally or link an existing account

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

Parameters

Example request body

{
  "mode": "start_new"
}

Behavior to know

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

Complete an installed iOS sign-in handoff

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

Parameters

Behavior to know

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

List accessible workspaces

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

Example response

{
  "workspaces": []
}

Create, switch, or rename a workspace

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

Parameters

Example request body

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

Behavior to know

• Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
• Rename is managed by the service permission boundary. Workspace selection does not bypass membership.

Apply a validated operation batch

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

Parameters

Example request body

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

Behavior to know

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

Undo or redo the current history entry

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

Parameters

Example request body

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

Behavior to know

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

Read saved versions of a record

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

Parameters

Example response

{
  "versions": []
}

Behavior to know

• Versions are governed record evidence, separate from workspace undo/redo.

Page workspace records

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

Parameters

Behavior to know

• Cursor identity binds the query and workspace revision. HTTP 409 page_changed means reload from the first page.
• nextCursor is null at the end. Treat returned record arrays as pages, not the whole workspace.

Page records in a sheet

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

Parameters

Behavior to know

• The server validates sheet/view/item scope and enforces access.
• Cursor belongs to one query identity and revision; changing either requires starting again.

Download a sheet export

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

Parameters

Behavior to know

• Successful response is a file download with Content-Disposition, not an API JSON envelope.
• CSV resolves computed values and readable linked/member names and escapes formula-like text. Export operates on server-owned sheet data.
• Errors use the normal JSON error response.

Read permitted search-index status

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

Parameters

Behavior to know

• Sources are limited by workspace and mailbox access. The response exposes counts/configuration, not indexed private content.
• Semantic search dimensions are 512. coverage.attachments is false.

Interpret an immediate request

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

Parameters

Example request body

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

Behavior to know

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

Create a durable AI job

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

Parameters

Example request body

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

Behavior to know

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

List saved AI jobs

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

Parameters

Example response

{
  "jobs": []
}

Behavior to know

• The service lists up to 20 undismissed jobs, prioritizing active work. Membership is rechecked.

Read an owned AI job

Returns the public AiJob state and any completed proposal.

Parameters

Behavior to know

• A workspace teammate cannot read another actor’s private job merely by knowing its ID.

Cancel or dismiss an AI job

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

Parameters

Behavior to know

• Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
• Cancellation/dismissal is separate from undoing an already applied workspace change. Inspect the returned status.

Edit or refresh a saved draft

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

Parameters

Example request body

{
  "rebase": true
}

Behavior to know

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

Upload a private attachment

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

Parameters

Example response

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

Behavior to know

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

Download or preview an attachment

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

Parameters

Behavior to know

• Success is a binary response with private,no-store; default MIME is application/octet-stream and disposition is attachment.
• Preview remains sandboxed and nosniff. Other file types stay downloads. Errors use the normal JSON shape.

Read a workbook overview

Computes the authorized workbook dashboard from server-owned data.

Parameters

Behavior to know

• This workbook overview differs from saved insight document queries.

Query a dashboard/report layout

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

Parameters

Behavior to know

• Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
• Body limit: 2 MiB. Returns queryInsights output for the requested layout or drilldown; this is read-only computation despite POST.

Preview a proposed insight layout

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

Parameters

Behavior to know

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

Read document templates, drafts, and versions

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

Parameters

Behavior to know

• Record selectors take precedence over document/workbook selection. Access is enforced for every requested resource.

Manage document templates and drafts

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

Parameters

Example request body

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

Behavior to know

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

Plan a document template

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

Parameters

Example request body

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

Behavior to know

• Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
• Body limit: 4,000,000 bytes. Permission is rechecked after planning. Invalid generated bindings return 422 invalid_document_plan.

Download a saved document PDF

Reads the authorized finalized version and returns its PDF bytes.

Parameters

Behavior to know

• Successful response is application/pdf with attachment disposition and private,no-store.
• The downloaded filename derives from the document number and version. Errors remain JSON.

List saved workbook templates

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

Parameters

Example response

{
  "templates": []
}

Save a reusable workbook template

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

Parameters

Example request body

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

Behavior to know

• Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
• Strict schema rejects extra keys. Maximum 100 reusable templates per workspace.

Preview or install a saved template

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

Parameters

Example request body

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

Behavior to know

• Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
• Preview returns {workbookId,operations,installed:false}. Successful install returns {workbookId,installed:true}.

Install a reviewed built-in template

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

Parameters

Behavior to know

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

Read team state

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

Parameters

Behavior to know

• Invitations are returned only to members with management access.

Manage invitations, members, or notifications

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

Parameters

Example request body

{
  "action": "read_notifications"
}

Behavior to know

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

Read a record discussion

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

Parameters

Example response

{
  "comments": []
}

Add or delete a comment

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

Parameters

Example request body

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

Behavior to know

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

Poll revision and presence

Returns workspaceId, revision, presence, and unreadCount.

Parameters

Behavior to know

• This is a JSON polling endpoint, not an SSE event stream.

Update presence and read events

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

Parameters

Example request body

{}

Behavior to know

• Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
• Body limit: 1,024 bytes. This does not establish realtime cursor coauthoring.

Read helper runs and workspace

Returns {runs,workspace} for the selected workspace.

Parameters

Run or review a helper

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

Parameters

Example request body

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

Behavior to know

• Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
• Returns the helper/run service result; run is not equivalent to unconditional application. Scope, review mode, revision and role checks still apply.

Read an agent’s email grant

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

Parameters

Example response

{
  "source": null
}

Behavior to know

• ID must identify a saved agent. A grant can be invalid after behavioral edits, mailbox disconnection, or loss of the grantor’s access.

Grant a scoped email source to an agent

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

Parameters

Example request body

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

Behavior to know

• Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
• Behavior-changing agent edits require a fresh grant. This is separate from workspace email-thread sharing.

Revoke an agent’s email source

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

Parameters

Example response

{
  "source": null
}

Behavior to know

• Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.

Read the email dashboard

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

Parameters

Behavior to know

• Private mail remains owned by the connecting actor. Explicitly shared linked threads are visible to authorized workspace members.
• Provider OAuth credentials and remote sync cursors are never returned.

Page visible email threads

Returns {threads,filteredCount?,nextCursor?}.

Parameters

Example response

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

Behavior to know

• Cursor is an offset string for email, unlike revision-bound record cursors; it must be an integer from 0 to 100,000.
• folder=drafts returns an empty thread list; drafts have a separate endpoint.

Read a conversation

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

Parameters

Behavior to know

• Only synchronized, visible messages are included. A shared thread does not confer general mailbox access.

Link or share a conversation

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

Parameters

Example request body

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

Behavior to know

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

Organize an email conversation

Performs one supported owner action and returns updated thread detail.

Parameters

Example request body

{
  "action": "read"
}

Behavior to know

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

Synchronize a connected mailbox

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

Parameters

Example request body

{
  "connectionId": "mailbox_example"
}

Behavior to know

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

Disconnect a mailbox

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

Parameters

Example response

{
  "disconnected": true
}

Behavior to know

• Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
• Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.

Configure incoming email sorting

Updates owned mailbox sorting and returns its public EmailConnection.

Parameters

Example request body

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

Behavior to know

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

Begin Google authorization

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

Example request body

{}

Behavior to know

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

Complete Google authorization

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

Parameters

Behavior to know

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

Begin Microsoft authorization

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

Parameters

Example request body

{}

Behavior to know

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

Complete Microsoft authorization

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

Parameters

Behavior to know

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

Connect an IMAP/SMTP mailbox

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

Parameters

Behavior to know

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

Read personal mailbox categories

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

Parameters

Replace personal mailbox categories

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

Parameters

Example request body

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

Behavior to know

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

Plan a category setup

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

Parameters

Example request body

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

Behavior to know

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

Read notification preferences

Returns preferences, notificationSender, canManageNotifications, and delivery counts.

Parameters

Behavior to know

• Preferences are per user/workspace. Sender and delivery visibility respect workspace management access.

Update notification preferences or sender

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

Parameters

Example request body

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

Behavior to know

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

List private email drafts

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

Parameters

Example response

{
  "drafts": []
}

Create a private email draft

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

Parameters

Example request body

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

Behavior to know

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

Read a private email draft

Returns EmailDraft for its creating actor in this workspace.

Parameters

Behavior to know

• EmailDraft fields include id, connectionId, recipients, subject, bodyText, status, createdAt, updatedAt, and optional sentAt/link/replyToMessageId/error.

Edit an unsent draft

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

Parameters

Example request body

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

Behavior to know

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

Discard an unsent draft

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

Parameters

Example response

{
  "deleted": true
}

Behavior to know

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

Queue an explicitly reviewed message

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

Parameters

Example request body

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

Behavior to know

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

Reconcile an uncertain delivery

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

Parameters

Behavior to know

• Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
• No JSON request body is required. Reconciliation is not an instruction to send the message again.
• Mailbox/category mutations require a registered editing account; personal preference changes use their own membership/verified-email checks.

Read a published form

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

Parameters

Behavior to know

• Invalid/unpublished form capabilities return 404 without revealing the workspace.
• Response includes no-store and Referrer-Policy:no-referrer. The capability must not be exposed in shared logs.

Submit a published form

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

Parameters

Example request body

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

Example response

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

Behavior to know

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

List personal MCP connections

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

Parameters

Example response

{
  "connections": []
}

Issue a scoped MCP connection

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

Parameters

Example request body

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

Behavior to know

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

Revoke a personal MCP connection

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

Parameters

Example response

{
  "revoked": true
}

Behavior to know

• Browser mutations require an exact Origin matching the configured app origin. Native bearer requests may omit Origin; a supplied mismatched Origin is still rejected.
• Revocation is checked before and after tool operations; it does not delete already saved workspace data.

Use the MCP protocol transport

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

Parameters

Behavior to know

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

Use the MCP protocol transport

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

Parameters

Behavior to know

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

Use the MCP protocol transport

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

Parameters

Behavior to know

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

Check process liveness

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

Example response

{
  "status": "ok"
}

Behavior to know

• Response is no-store and nosniff. HTTP 200 does not establish database, worker, OAuth, or provider readiness.