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 |
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.