Reference
REST API
Every route the Agentic API serves, generated from the route manifest.
The API is mounted at /api/agentic (agentic.basePath in Nuxt, basePath in Void). It
serves an OpenAPI 3.1 document at /api/agentic/openapi.json; point any OpenAPI client or
generator at it.
Requests
- Authentication: the better-auth session cookie. Requests without a session get
401. - Workspace: send
X-Agentic-Workspace: <workspace id>; without it, requests act in the signed-in user'spersonalworkspace. Membership and role are checked on every request. - Access:
Memberroutes need any role in the workspace,Adminan owner or admin role,Ownerthe owner role.Signed inroutes check workspace roles inside the handler. - Mutations from another origin are refused with
403. - Errors are JSON:
{ "message": "…" }with the HTTP status. - Lists take
page(from 1),pageSize(up to 100, default 50),search,sortBy,sortDir(ascordesc) andfilters(JSON), and answer{ data, totalCount, totalPages, page, pageSize }.
Agentic Models
Each model adds up to five routes, one per action its access allows. For a model named
customer:
models
| Method | Path | Access | Summary |
|---|---|---|---|
| GET | /models/customer | Member | List customer records |
| GET | /models/customer/:id | Member | Get a customer record |
| POST | /models/customer | Admin | Create a customer record |
| PATCH | /models/customer/:id | Admin | Update a customer record |
| DELETE | /models/customer/:id | Owner | Delete a customer record |
Built-in features
identity
| Method | Path | Access | Summary |
|---|---|---|---|
| POST | /identity/images | Signed in | Upload a bounded raster avatar or workspace logo |
| GET | /identity/images/:id/status | Signed in | Check whether an owned upload is still available |
| GET | /identity/images/:id | Signed in | Download an authorized image with safe attachment headers |
workspaces
| Method | Path | Access | Summary |
|---|---|---|---|
| GET | /session | Signed in | Get the authenticated user and available workspaces |
| GET | /workspaces | Signed in | List available workspaces |
| POST | /workspaces | Signed in | Create a workspace with the authenticated user as owner |
| GET | /workspaces/:workspace | Signed in | Get a workspace and its members |
| PATCH | /workspaces/:workspace | Signed in | Update a managed workspace |
| PATCH | /workspaces/:workspace/logo | Signed in | Update a managed workspace logo |
| PATCH | /workspaces/:workspace/members/:id | Signed in | Change a member role while preserving an active owner |
| DELETE | /workspaces/:workspace/members/:id | Signed in | Leave a workspace or remove a permitted member |
| GET | /workspaces/:workspace/invitations | Signed in | List invitations in a managed workspace |
| POST | /workspaces/:workspace/invitations | Signed in | Create or rotate a workspace invitation |
| DELETE | /workspaces/:workspace/invitations/:id | Signed in | Revoke a permitted workspace invitation |
| POST | /invitations/preview | Signed in | Preview an invitation addressed to the authenticated account |
| POST | /invitations/accept | Signed in | Accept a valid invitation for the authenticated account |
approvals
| Method | Path | Access | Summary |
|---|---|---|---|
| GET | /records/integrationApproval | Member | List action approvals |
| GET | /records/integrationApproval/:id | Member | Get an owned action approval |
integrations
| Method | Path | Access | Summary |
|---|---|---|---|
| POST | /integrations/approvals/:id | Member | Answer an owned pending action approval |
| GET | /oauth/:provider/callback | Signed in | Complete a one-use provider authorization for the authenticated account |
| GET | /mcp/client-metadata | Public | Get public OAuth client metadata for this application |
| GET | /mcp-oauth/callback | Signed in | Complete one-use MCP authorization for the authenticated account |
| POST | /integration-hooks/:id | Signed webhook | Receive a signed or capability-authenticated connection event |
| POST | /provider-hooks/:provider | Signed webhook | Receive and verify a supported vendor webhook |
| GET | /integrations/catalog | Member | List available integrations and visible connections |
| GET | /integrations/catalog/tools | Member | List tools granted by visible active connections |
| GET | /integrations/catalog/:provider/tools | Member | List available actions for an owned or shared connection |
| POST | /integrations/catalog/:provider/connection | Member | Connect or manage an authorized integration account |
| POST | /integrations/catalog/:provider/action | Member | Execute a granted integration action or request approval |
data
| Method | Path | Access | Summary |
|---|---|---|---|
| GET | /data | Member | List accessible data collections |
| GET | /data/:id | Member | Query an authorized data collection |
| GET | /data/:id/records/:record | Member | Inspect the public fields of an authorized data record |
mcp
| Method | Path | Access | Summary |
|---|---|---|---|
| GET, POST, … | /mcp | Member | Serve authenticated manifest tools over stateless MCP |
local-mcp
| Method | Path | Access | Summary |
|---|---|---|---|
| GET | /local-mcp/identity | Signed webhook | Resolve a native local account using the development capability |
| POST | /local-mcp | Signed webhook | Serve local project tools through a development process capability |
prompt
| Method | Path | Access | Summary |
|---|---|---|---|
| GET | /prompt/options | Member | Get public prompt decision provider settings |
| GET | /prompt/resources | Member | List registered public prompt resources |
| GET | /prompt/resources/:id | Member | Query an authorized prompt resource |
| GET | /prompt/resources/:id/records/:record | Member | Read an authorized prompt resource record |
| POST | /prompt/plan | Member | Prepare a session-bound review without executing writes |
| POST | /prompt/execute | Member | Claim and execute the exact records in an owned review |
| POST | /prompt/cancel | Member | Cancel an owned pending review |
agents
| Method | Path | Access | Summary |
|---|---|---|---|
| GET | /records/agent | Member | List agents in the current workspace |
| GET | /records/agent/:id | Member | Get an owned agent |
| GET | /records/agent/code/:slug | Member | Get the workspace copy of a code agent by its file name |
| POST | /records/agent | Member | Create an agent in the current workspace |
| PATCH | /records/agent/:id | Member | Update an owned agent |
| DELETE | /records/agent/:id | Member | Delete an owned agent |
| GET | /agents/runtimes | Member | Discover configured model providers and local development runtimes |
runs
| Method | Path | Access | Summary |
|---|---|---|---|
| POST | /agents/:id/runs | Member | Accept an owned agent run in a scoped durable runner |
| GET | /agents/:id/runs/:run | Member | Get a run in the current user, workspace, agent and session |
| GET | /agents/:id/runs/:run/events | Member | Stream run status changes as server-sent events until the run finishes |
| POST | /agents/:id/runs/:run/cancel | Member | Cancel an owned agent run in its accepted session |
automations
| Method | Path | Access | Summary |
|---|---|---|---|
| GET | /records/automation | Member | List automations in the current workspace |
| GET | /records/automation/:id | Member | Get an owned automation |
| POST | /records/automation | Member | Create an automation |
| PATCH | /records/automation/:id | Member | Update an owned automation |
| DELETE | /records/automation/:id | Member | Delete an owned automation |
| POST | /automations/:id/run | Member | Accept a test run from the saved automation and agent snapshot |
| GET | /automations/:id/endpoint | Member | Get the secret webhook URL for an owned automation |
| POST | /automations/events | Member | Deliver an event to active owned automations with stable event identities |
| POST | /automations/runs/:id/resume | Member | Resume an unfinished owned automation run |
| POST | /automations/runs/:id/cancel | Member | Cancel an owned automation run without overwriting a terminal result |
| GET | /automations/templates | Member | List automation templates defined in code |
| POST | /automations/templates/:slug | Member | Install a code-defined automation template as an inactive workspace draft |
| POST | /hooks/:id/:token | Signed webhook | Accept a capability-authenticated automation webhook |
automationFolders
| Method | Path | Access | Summary |
|---|---|---|---|
| GET | /records/automationFolder | Member | List automation folders |
| POST | /records/automationFolder | Member | Create an automation folder |
| DELETE | /records/automationFolder/:id | Member | Delete an owned automation folder |
automationRuns
| Method | Path | Access | Summary |
|---|---|---|---|
| GET | /records/automationRun | Member | List automation run history |
| GET | /records/automationRun/:id | Member | Get an owned automation run |