idapt REST API

REST API for managing chats, agents, workspaces, Drive (cloud files), image generation, speech synthesis, web search, triggers, code execution, notifications, and more programmatically.

Base URL

https://idapt.ai/api/v1

Authentication

Send your API key (starts with uk_) in every request:

Authorization: Bearer uk_your_key_here

Or via header: x-api-key: uk_your_key_here

Create API keys in Settings > API Keys. Select only the permissions you need.

Response Format

All responses use snake_case field names and ISO 8601 timestamps. Every
response also carries X-Request-Id and X-Idapt-Version headers.

// Single resource
{ "data": { "id": "...", "created_at": "2024-01-15T10:30:00.000Z" } }

// List — pagination carries has_more + next_cursor (no total count)
{ "data": [...], "pagination": { "has_more": true, "next_cursor": "..." } }

// Delete
{ "deleted": true, "id": "..." }

// Error — type is the coarse category; code an optional finer sub-code
{ "error": { "type": "not_found", "message": "Chat not found" } }

Pagination is cursor-based: list endpoints take limit (max 100) and an
optional opaque cursor. Page by passing the previous response's
pagination.next_cursor as the next request's ?cursor= — never parse
the cursor. next_cursor is null once has_more is false.

Endpoints

Method	Path	Description
GET	/me	Get current user info
GET	/me/usage	Get usage stats (storage, history)
GET	/chats	List chats
POST	/chats	Create a chat
GET	/chats/:id	Get a chat
PATCH	/chats/:id	Update a chat
DELETE	/chats/:id	Delete a chat
GET	/chats/:id/messages	List messages
POST	/chats/:id/messages	Send a message and get AI response
GET	/chats/:id/runs	List agent execution runs
GET	/chats/:id/cost	Get cost breakdown
GET	/agents	List agents
POST	/agents	Create an agent
GET	/agents/:id	Get an agent
PATCH	/agents/:id	Update an agent
DELETE	/agents/:id	Delete an agent
GET	/workspaces	List workspaces
POST	/workspaces	Create a workspace
GET	/workspaces/:id	Get a workspace
PATCH	/workspaces/:id	Update a workspace
DELETE	/workspaces/:id	Delete a workspace
GET	/workspaces/:id/members	List workspace members
POST	/workspaces/:id/members	Add a member
PATCH	/workspaces/:id/members/:mid	Update member role
DELETE	/workspaces/:id/members/:mid	Remove a member
GET	/files	List files
POST	/files	Upload a file (multipart/form-data)
GET	/files/:id	Download a file
PATCH	/files/:id	Update file metadata
DELETE	/files/:id	Trash a file
POST	/files/folders	Create a folder (idempotent)
POST	/files/:id/move	Move file/folder
POST	/files/:id/run	Execute code file in sandbox
GET	/models	List available LLM models
GET	/search?q=...	Search across resources
POST	/audio/transcriptions	Transcribe audio file
POST	/audio/speech	Generate speech from text (TTS)
POST	/images/generations	Generate an image from a text prompt
GET	/images/models	List image generation models
POST	/web/search	Search the web (Brave Search)
GET	/triggers	List triggers
POST	/triggers	Create a trigger (cron/webhook)
GET	/triggers/:id	Get a trigger
PATCH	/triggers/:id	Update a trigger
DELETE	/triggers/:id	Delete a trigger
POST	/triggers/:id/fire	Fire a webhook trigger
GET	/triggers/:id/runs	List trigger fire history
POST	/triggers/:id/rotate-secret	Rotate webhook secret
GET	/code-runs	List code runs
POST	/code-runs	Execute a code file in sandbox
GET	/code-runs/:id	Get code run details
GET	/notifications	List your inbox notifications
POST	/notifications	Send a notification to workspace members
GET	/notifications/:id	Get one notification
PATCH	/notifications/:id	Mark read / archive / unarchive
DELETE	/notifications/:id	Delete a notification
POST	/notifications/read-all	Mark all notifications as read
GET	/notifications/preferences	Channel preference matrix
PATCH	/notifications/preferences	Update channel preferences
GET	/notifications/config	Quiet hours / toasts / sound
PATCH	/notifications/config	Update quiet-hours + toasts + sound

Quick Examples

List chats

curl https://idapt.ai/api/v1/chats \
  -H "Authorization: Bearer uk_your_key_here"

Create an agent

curl https://idapt.ai/api/v1/agents \
  -H "Authorization: Bearer uk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "icon": "bot"}'

Upload a file

curl https://idapt.ai/api/v1/drive/files \
  -H "Authorization: Bearer uk_your_key_here" \
  -F "file=@report.pdf" \
  -F "workspace_id=YOUR_PROJECT_ID"

Send a message (sync — waits for AI response)

curl https://idapt.ai/api/v1/chats/CHAT_ID/messages \
  -H "Authorization: Bearer uk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"content": "What is the capital of France?"}'

Send a message (async — returns immediately)

curl https://idapt.ai/api/v1/chats/CHAT_ID/messages \
  -H "Authorization: Bearer uk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"content": "Summarize this workspace", "wait": false}'

Create a folder

curl https://idapt.ai/api/v1/drive/files/folders \
  -H "Authorization: Bearer uk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Documents", "workspace_id": "YOUR_PROJECT_ID"}'

Move a file

curl -X POST https://idapt.ai/api/v1/drive/files/FILE_ID/move \
  -H "Authorization: Bearer uk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"parent_id": "FOLDER_ID"}'

List workspace members

curl https://idapt.ai/api/v1/workspaces/WORKSPACE_ID/members \
  -H "Authorization: Bearer uk_your_key_here"

Get usage stats

curl https://idapt.ai/api/v1/me/usage \
  -H "Authorization: Bearer uk_your_key_here"

List models

curl https://idapt.ai/api/v1/models \
  -H "Authorization: Bearer uk_your_key_here"

Generate an image

curl https://idapt.ai/api/v1/images/generations \
  -H "Authorization: Bearer uk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A sunset over the ocean", "workspace_id": "WORKSPACE_ID"}'

Generate speech

curl https://idapt.ai/api/v1/audio/speech \
  -H "Authorization: Bearer uk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "workspace_id": "WORKSPACE_ID"}'

Web search

curl https://idapt.ai/api/v1/web/search \
  -H "Authorization: Bearer uk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"query": "latest AI news"}'

Create a cron trigger

curl "https://idapt.ai/api/v1/triggers?workspace_id=WORKSPACE_ID" \
  -H "Authorization: Bearer uk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"trigger_type":"cron","name":"Daily Report","cron_expression":"0 9 * * *","action_type":"agent-run","agent_id":"AGENT_ID","prompt_template":"Generate a daily report"}'

Execute code

curl https://idapt.ai/api/v1/code-runs \
  -H "Authorization: Bearer uk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "FILE_ID"}'

List code runs

curl https://idapt.ai/api/v1/code-runs \
  -H "Authorization: Bearer uk_your_key_here"

Send a notification to workspace members

curl https://idapt.ai/api/v1/notifications \
  -H "Authorization: Bearer uk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "WORKSPACE_ID",
    "target": "all_members",
    "title": "Build complete",
    "message": "The staging deploy finished successfully.",
    "channels": ["in_app", "web_push"],
    "urgency": "normal",
    "deep_link": { "kind": "chat", "chat_id": "CHAT_ID" }
  }'

List your inbox

curl "https://idapt.ai/api/v1/notifications?unread_only=true" \
  -H "Authorization: Bearer uk_your_key_here"

Error Codes

The error object is { error: { type, message, code? } }. type is the
coarse category clients branch on (one of the values below); code is an
optional finer computer-branchable sub-code present only on specific
errors (today only model_not_available_for_tier, on a 403 from
POST /images/generations and POST /audio/speech). invalid_request
is always 422 — the API never returns 400 for validation errors.

type	Status	Description
invalid_request	422	Validation error
unauthorized	401	Missing or invalid API key
forbidden	403	Key lacks required permissions
not_found	404	Resource not found
conflict	409	Resource conflict
rate_limit	429	Too many requests
service_unavailable	503	An upstream dependency (computer daemon, inference provider) is unreachable — retryable
internal_error	500	Server error

Permissions

API keys have granular permissions: chat, agents, workspace, drive, completions, user, triggers, notifications. Select only what you need when creating a key.

LLM Completions

For LLM completions (chat with models), use the OpenAI-compatible or Anthropic-compatible proxy APIs instead:

• OpenAI format: https://idapt.ai/api/openai/v1/chat/completions
• Anthropic format: https://idapt.ai/api/anthropic/v1/messages

Both accept the same uk_ API key and support all 200+ models.

Links

• OpenAPI spec (JSON): https://idapt.ai/api/v1/docs
• Interactive API reference: https://idapt.ai/developers/api-reference
• REST API guide (auth, examples, errors): https://idapt.ai/help/api-reference
• OpenAI-compatible API guide: https://idapt.ai/help/openai-compatible-api
• Anthropic-compatible API guide: https://idapt.ai/help/anthropic-compatible-api
• Developers hub: https://idapt.ai/developers
• Create API key: https://idapt.ai/#settings