REST API
Found this helpful? Share it:
Found this helpful? Share it:
The idapt REST API gives your code the same actions you take in the app: chats, agents, files, computers, knowledge, inference, search, and more. Any language that can make an HTTP request can call it 📖
Free and upEvery endpoint is relative to a single base URL. Listing chats, for
example, is GET https://idapt.app/api/v1/chats.
https://idapt.app/api/v1Authenticate every request with an API key. Send it as a bearer token,
or in the x-api-key header:
Authorization: Bearer uk_your_key_here
x-api-key: uk_your_key_hereKeys start with uk_. Create one under Settings → Developer. See API keys and scopes for scopes,
rotation, and spend caps.
The API uses dated versions. Send an X-Idapt-Version header to select a contract explicitly:
X-Idapt-Version: 2026-07-07Omit the header and the request uses the version pinned to your API key. A dated version controls breaking request and response shapes. New endpoints and optional fields can appear without a new date, so pinning keeps existing code stable.
Every response uses one of three JSON envelopes.
{
"data": {
"id": "01h0m2k3p4q5r6s7t8v9w0x1y2",
"title": "My chat",
"created_at": "2026-01-15T10:30:00.000Z"
}
}Every id and foreign-key field is a 26-character
Crockford base32 resource id, never a UUID. Path parameters like /chats/{id}expect the same shape.
{
"data": [ ... ],
"pagination": { "has_more": true, "next_cursor": "b3Blbjox..." }
}Lists are cursor-paginated. Pass next_cursor back as
the cursor query parameter for the next page. It is null when has_more is false. The limit parameter caps at 100.
{
"error": { "type": "not_found", "message": "Chat not found" }
}Branch on type, not the wording of message. Some errors also carry an optional code with a more
specific reason. See Rate limits and errors.
Field names use snake_case and timestamps are ISO 8601
strings. A delete returns { deleted, id }. Every
response carries an X-Request-Id header, so quote it when
you contact support. There are no idempotency keys.
The rows below are generated from the same registry that powers the CLI and the agent tool, so they always match the live routes. Resource ids, request bodies, and per-field rules live behind each route.
Chats
| Endpoint | What it does |
|---|---|
GET /chats | List chats. |
GET /chats/:id | Get a chat by id. |
POST /chats | Create a chat. |
PATCH /chats/:id | Update a chat (title, model, …). |
DELETE /chats/:id | Trash a chat. |
POST /chats/:id/archive | Archive a chat. |
POST /chats/:id/unarchive | Unarchive a chat. |
POST /chats/:id/restore | Restore a trashed chat. |
DELETE /chats/:id/permanent-delete | Permanently delete a trashed chat (irreversible). |
GET /chats/:id/messages | List a chat's messages. |
POST /chats/:id/messages | Send a message and generate a response (long-running). |
POST /chats/:id/messages/stream | Send a message and stream the response as Server-Sent Events. |
POST /chats/:id/runs/:run_id/retry | Retry a failed run (long-running). |
GET /chats/:id/runs | List a chat's agent runs. |
GET /chats/:id/cost | Get a chat's total cost. |
GET /chats/:id/message-costs | Get per-message and per-run cost details. |
POST /chats/:id/compact | Compact a chat's conversation history. |
POST /chats/:id/goal | Start goal mode on a chat. |
GET /chats/:id/goal | Read the goal governing a chat's active branch. |
DELETE /chats/:id/goal | End the active goal. |
POST /chats/:id/goal/resume | Re-open an exhausted or stalled goal with a bigger cap. |
POST /chats/:id/stop | Stop the active run in a chat. |
GET /chats/:id/export | Export a chat transcript. |
POST /chats/:id/copy-to-agent | Copy a chat to another agent. |
POST /chats/:id/copy-to-workspace | Copy a chat into another workspace. |
POST /chats/:id/fork-to-workspace | Fork a chat into another workspace. |
Agents
| Endpoint | What it does |
|---|---|
GET /agents | List agents. |
GET /agents/:id | Get an agent by id. |
POST /agents | Create an agent (name, system_prompt, workspace_id, …). |
PATCH /agents/:id | Update an agent's fields. |
DELETE /agents/:id | Trash an agent. |
POST /agents/:id/archive | Archive an agent. |
POST /agents/:id/unarchive | Unarchive an agent. |
POST /agents/:id/restore | Restore a trashed agent. |
DELETE /agents/:id/permanent-delete | Permanently delete a trashed agent (irreversible). |
POST /agents/:id/move | Move an agent to another workspace. |
POST /agents/:id/copy-to-workspace | Copy an agent into another workspace. |
Workspaces
| Endpoint | What it does |
|---|---|
GET /workspaces | List workspaces. |
GET /workspaces/:id | Get a workspace by id. |
POST /workspaces | Create a workspace. |
PATCH /workspaces/:id | Update a workspace. |
DELETE /workspaces/:id | Delete a workspace. |
POST /workspaces/:id/archive | Archive a workspace. |
POST /workspaces/:id/unarchive | Unarchive a workspace. |
GET /workspaces/:id/members | List workspace members. |
POST /workspaces/:id/members | Add a workspace member. |
PATCH /workspaces/:id/members/:memberId | Update a member's role/permissions. |
DELETE /workspaces/:id/members/:memberId | Remove a workspace member. |
GET /workspaces/:id/invitations | List workspace invitations. |
POST /workspaces/:id/invitations | Invite someone to a workspace. |
DELETE /workspaces/:id/invitations | Revoke a pending workspace invitation. |
Shares
| Endpoint | What it does |
|---|---|
GET /shares | List grantees on a resource. |
POST /shares | Share a resource with someone. |
PATCH /shares | Update a share's access. |
DELETE /shares | Revoke a share. |
Shared with me
| Endpoint | What it does |
|---|---|
GET /shared-with-me | List resources others have shared with you. |
There is no fork endpoint for a workspace. Use the copy verbs to duplicate resources between workspaces.
| Endpoint | What it does |
|---|---|
GET /drive/files | List files (cursor-paginated). Filter to a folder with parent_id. |
GET /drive/files/:id/content | Read a file's text, with paging, tail or a regex search. |
GET /drive/files/:id | Download a file's raw bytes (streamed) by id. |
GET /drive/files/:id/metadata | Get a file's metadata by id. |
POST /drive/files | Upload a file (multipart). Provide workspace_id or parent_id. |
PATCH /drive/files/:id | Update file name/content. OCC via expected_updated_at. |
DELETE /drive/files/:id | Trash a file by id (recoverable with `drive restore`). |
POST /drive/files/:id/restore | Restore a trashed file. |
DELETE /drive/files/:id/permanent-delete | Permanently delete a trashed file (irreversible). |
POST /drive/files/folders | Create-or-get a folder (idempotent). |
POST /drive/files/:id/move | Move a file to a new parent_id (null = workspace root). |
POST /drive/files/:id/signed-url | Mint a short-lived direct link to a file's bytes. |
GET /drive/files/:id/content-versions | List a file's content version history (newest first). |
POST /drive/files/:id/content-versions/restore | Restore a file to a previous content version. |
GET /drive/glob | Find files by glob pattern (e.g. **/*.ts) across the drive. |
GET /drive/grep | Search file contents by regex (modes: content/files/count, ripgrep-style context). |
| Endpoint | What it does |
|---|---|
GET /computers | List machines you can reach - yours and your orgs' (`--owner me` for just yours, `--workspace-id` for one workspace's reachable set). |
GET /computers/:id | Get a computer by id. |
POST /computers | Not available: computers are paired from the machine itself, not created here. |
PATCH /computers/:id | Update a computer (name, …). |
DELETE /computers/:id | Delete a computer. |
POST /computers/:id/exposures | Allow a workspace to use a machine, with a capability grant. |
PATCH /computers/:id/exposures/:workspace_id | Replace a workspace allowance's capability grant. |
DELETE /computers/:id/exposures/:workspace_id | Revoke a workspace's access to a machine. |
POST /computers/:id/transfer | Transfer a machine to a new owner. |
POST /computers/:id/local-inference | Control a computer's local inference engine and models. |
GET /computers/:id/local-inference/models | List a computer's installed local-inference models. |
POST /computers/:id/local-inference/models | Install a local-inference model on a computer. |
DELETE /computers/:id/local-inference/models/:ollama_id | Remove a local-inference model from a computer. |
PATCH /computers/:id/local-inference/models/:ollama_id/mapping | Map (or unmap) an installed local model to an Idapt model id. |
GET /computers/:id/local-inference/operations | List a computer's local-inference operations (installs, pulls, …). |
POST /computers/:id/local-inference/operations/:operation_id/cancel | Cancel an in-flight local-inference operation. |
POST /computers/pair | Daemon pair-token redemption. |
POST /computers/:id/start | Start a computer. |
POST /computers/:id/stop | Stop a computer. |
POST /computers/:id/rotate-credential | Rotate a computer's machine credential. |
POST /computers/:id/test-connection | Probe daemon connectivity. |
POST /computers/:id/exec | Run a shell command on a computer (long-running). |
POST /computers/:id/terminal | Manage persistent terminals on a computer. |
GET /computers/:id/fs/download | Download a file from a computer (?path=). |
POST /computers/:id/fs/upload | Upload to a computer - raw `file` bytes OR a Drive `drive_source`. |
POST /computers/:id/fs | FS op (list/stat/mkdir/remove). |
GET /computers/:id/ports | List a computer's ports. |
PATCH /computers/:id/ports | Label a port. |
GET /computers/:id/users | List computer users. |
POST /computers/:id/users | Create a computer user. |
GET /computers/:id/users/:username | Get a computer user. |
PATCH /computers/:id/users/:username | Update a computer user. |
DELETE /computers/:id/users/:username | Delete a computer user. |
You cannot create a computer over the API: pair a machine with the daemon, or provision a cloud computer from the app. See Computers.
| Endpoint | What it does |
|---|---|
GET /automations | List automations. |
GET /automations/cost-stats | Get automation cost stats keyed by automation id. |
GET /automations/:id | Get an automation by id. |
POST /automations | Create an automation (cron / webhook). |
PATCH /automations/:id | Update an automation. |
DELETE /automations/:id | Delete an automation. |
POST /automations/:id/archive | Archive an automation. |
POST /automations/:id/unarchive | Unarchive an automation. |
POST /automations/:id/fire | Fire a webhook automation using its bearer token. |
POST /automations/:id/test-fire | Test-fire an automation now. |
GET /automations/:id/cost-stats | Get one automation's cost stats. |
GET /automations/:id/runs | List an automation's runs. |
GET /automations/runs | List automation runs in a workspace. |
POST /automations/:id/runs/:runId/cancel | Cancel a queued or cancellable automation run. |
POST /automations/:id/runs/:runId/retry | Admit a new attempt for a retryable terminal run. |
POST /automations/:id/rotate-secret | Rotate a webhook automation's secret. |
See Automations and webhooks for the schedule and signed-webhook flows.
Inference
| Endpoint | What it does |
|---|---|
POST /inference/text | Run a one-shot LLM completion (message-based). Returns the completion inline, or an operation handle with `background: true`. |
POST /inference/text/stream | Stream a one-shot LLM completion over SSE (token-by-token). |
POST /inference/images | Generate an image from a prompt. Returns the saved image inline, or a handle with `background: true`. |
POST /inference/videos | Generate a video as a durable operation (external clients may await it; foreground chat resumes automatically). |
POST /inference/speech | Synthesize speech from text (TTS). Returns the saved audio inline, or a handle with `background: true`. |
POST /inference/speech/stream | Stream synthesized speech over SSE (audio chunks). |
POST /inference/transcriptions | Transcribe audio to text (STT). Returns the transcript inline, or a handle with `background: true`. |
Models
| Endpoint | What it does |
|---|---|
GET /models | List available LLM models (id, pricing, capabilities). |
GET /models/:id | Get one model's pricing and capabilities by id. |
GET /models/search | Search LLM models by capability (vision, reasoning), price, capability index and context length. Filtered, sorted and paginated. |
Images
| Endpoint | What it does |
|---|---|
GET /images/models | List available image-generation models. |
GET /images/models/search | Search image models by provider/tier (filtered + paginated). Envelope: {items,total_count,offset,has_more,query,applied_filters}. |
Audio
| Endpoint | What it does |
|---|---|
GET /audio/voices | List TTS voices (filter by language/gender). |
GET /audio/models | List available TTS/transcription models. |
GET /audio/models/search | Search TTS models by speed/price (sorted + paginated). Envelope: {items,total_count,offset,has_more,query,applied_filters}. |
GET /audio/voices/search | Search TTS voices by gender/language/provider (paginated). Envelope: {items,total_count,offset,has_more,query,applied_filters}. |
Video
| Endpoint | What it does |
|---|---|
GET /videos/models | List available video-generation models. |
GET /videos/models/search | Search video models by provider/mode/resolution/audio (paginated). Envelope: {items,total_count,offset,has_more,query,applied_filters}. |
Operations(poll long-running and async work)
| Endpoint | What it does |
|---|---|
GET /operations/:id/await | Wait briefly for an operation transition or terminal result. |
GET /operations/:id | Get an async operation's status/result by id. |
GET /operations | List recent async operations (filter by status). |
POST /operations/:id/cancel | Cancel a running async operation. |
GET /operations/:id/content | Retrieve a completed operation's output (file redirect or stdout). |
Search
| Endpoint | What it does |
|---|---|
GET /search | Hybrid semantic + keyword search across your files, chats, messages, agents, computers, repos and notes. |
Web
| Endpoint | What it does |
|---|---|
POST /web/search | Search the web (Brave). Returns titles, urls, and snippets. |
POST /web/fetch | Fetch a URL and return its content as clean markdown. |
Notifications
| Endpoint | What it does |
|---|---|
GET /notifications | List notifications. |
GET /notifications/preferences | Get notification preferences. |
PATCH /notifications/preferences | Bulk update notification preferences. |
GET /notifications/config | Get notification config (toasts, sound, quiet hours). |
PATCH /notifications/config | Update notification config. |
GET /notifications/:id | Get a notification. |
POST /notifications | Send a notification. |
PATCH /notifications/:id | Update a notification (mark read, …). |
DELETE /notifications/:id | Delete a notification. |
POST /notifications/read-all | Mark all notifications read. |
Realtime
| Endpoint | What it does |
|---|---|
POST /realtime/:channel/broadcast | Broadcast an ephemeral message to a channel's subscribers. |
POST /realtime/:channel/presence | Record/refresh the caller's presence in a channel (TTL heartbeat). |
GET /realtime/:channel/presence | List who is currently present in a channel. |
GET /realtime/subscribe | Open an SSE stream of one or more channels' durable changes + ephemeral broadcasts. |
You
| Endpoint | What it does |
|---|---|
GET /me | Get the current user's profile. |
GET /me/usage | Get usage (view=summary storage, or view=history metered calls). |
GET /me/limits | Get the viewer's effective tier and session limits. |
Settings
| Endpoint | What it does |
|---|---|
GET /settings | Get account preferences. |
PATCH /settings | Update account preferences. |
Subscription
API keys(create and rotate from the dashboard, not over a bearer key)
| Endpoint | What it does |
|---|---|
GET /api-keys | List API keys. |
POST /api-keys | Create an API key. |
PATCH /api-keys/:id | Update an API key (name/scopes). |
DELETE /api-keys/:id | Revoke an API key. |
POST /api-keys/:id/rotate | Rotate an API key's secret. |
AI Gateway
| Endpoint | What it does |
|---|---|
GET /ai-gateway/providers | List the routable serving providers. |
GET /ai-gateway/usage | Per-model / per-provider usage breakdown. |
POST /ai-gateway/routing-preview | Preview the provider routing order for a model. |
Provider endpoints
| Endpoint | What it does |
|---|---|
GET /ai-gateway/provider-endpoints | List provider endpoints. |
GET /ai-gateway/provider-endpoints/presets | List provider-endpoint presets. |
POST /ai-gateway/provider-endpoints | Add a provider endpoint. |
PATCH /ai-gateway/provider-endpoints/:id | Update a provider endpoint. |
DELETE /ai-gateway/provider-endpoints/:id | Delete a provider endpoint. |
POST /ai-gateway/provider-endpoints/:id/test | Test a provider endpoint's connectivity. |
API keys and scopes: create, scope, pin, and rotate a key.
JavaScript SDK quickstart: call the same surface from Node or the browser.
Rate limits and errors: every error shape and how to handle a wall.
Related articles
API keys and scopes
Create a key, choose its scopes, pin it to an API version, rotate it, and cap what it can spend.
JavaScript SDK quickstart
Install @idapt/sdk, authenticate, and make your first calls from Node or the browser.
Rate limits and errors
Every error shape the API returns, what each rate limit is, and how to handle a wall in code.
Was this helpful?