# Action API and revision-safe changes

Every saved change crosses the same validation boundary.

Ralti’s internal HTTP API supports the web and native clients. It is authenticated and workspace-scoped; it is not an unauthenticated public CRUD service. Prefer the scoped MCP integration for external assistants. Internal clients use domain operations defined in lib/core/types.ts rather than replacing arbitrary workspace objects.

| Endpoint | Purpose |
| --- | --- |
| GET /api/session | Current identity, scoped workspace, capabilities, and access context |
| GET /api/workspaces | Accessible workspace list |
| POST /api/ai-jobs | Create a durable AI request with creation idempotency |
| GET /api/ai-jobs/:id | Read an actor-owned request and result |
| DELETE /api/ai-jobs/:id | Cancel active work or dismiss a terminal result |
| POST /api/interpret | Immediate interpretation, using explicit built-in or direct AI; clients prefer durable AI jobs. |
| POST /api/actions | Commit typed operations with expectedRevision and required confirmation |
| POST /api/history | Undo or redo with an expected revision |

## All operations succeed together

The domain engine accepts up to 500 operations in a reviewed batch. It validates operations sequentially against a cloned workspace, so later operations can refer to entities created earlier in the batch. Invalid fields, values, or references reject the complete batch. A nonempty accepted batch advances the workspace revision once and writes history transactionally. Workflow runs have separate, smaller limits.

The action request carries operations, expectedRevision, confirmed when required, and aiJobId when applying a saved AI proposal. A stale revision must be resolved by refreshing and rebuilding the preview; it must not be overwritten by simply substituting a new revision number. Bulk actions enumerate exact target IDs—there is no model-authored predicate-based write operation.

| Internal name | User-facing concept |
| --- | --- |
| space / spaceId | Sheet |
| item / itemId | Record |
| field / fieldId | Column |
| workbook / workbookId | Workbook |

> **Authorization is repeated** Selecting a workspace never grants membership. Browser writes enforce origin checks, native requests carry authenticated client credentials, and every mutation checks the actor’s current role. A preview is not proof that the actor still has permission when Apply is selected.

Formula and rollup values are calculated and read-only. Relationship edits validate target IDs and synchronize explicitly paired links. Use the checked-in types and tests when adding operation families so web, native parsing, history, and AI compilation remain aligned.