Endpoints
The routes of /api/v1, by resource.
All routes need a signed-in user unless noted. :id is a UUID.
Account
| Route | Does |
|---|---|
GET /api/v1/auth/me | The signed-in user and session. |
POST /api/v1/auth/sign-out | Ends the session. |
GET /api/v1/me/security | Whether you have a password and two-factor sign-in. |
PATCH /api/v1/me | Name, avatar (an https URL) and timezone. |
PUT /api/v1/me/password | Change the password after checking the current one; ends every session and revokes your API keys. |
GET /api/v1/me/activity-logs | Your own activity. |
GET, POST /api/v1/me/api-keys | List your API keys, or create one: name, expires_in_days (1 to 365, default 90). The key is in the create answer only. |
DELETE /api/v1/me/api-keys/:id | Revoke a key. |
POST /api/v1/auth/totp/enable, /disable, /generate-backup-codes | Two-factor sign-in. |
Organizations
| Route | Does |
|---|---|
GET, POST /api/v1/organizations | Yours, or create one (you become its owner). |
GET, PUT, DELETE /api/v1/organizations/:id | Read, rename (owner), move to the trash (owner). |
PUT /api/v1/organizations/:id/restore, DELETE /api/v1/organizations/:id/force | Restore from the trash, or delete for good. |
GET /api/v1/organizations/:id/stats | Unread inbox mail, spam and connected accounts. |
GET /api/v1/organizations/:id/activity-logs | The organization's audit log. |
Mailboxes and mail
| Route | Does |
|---|---|
GET, POST /api/v1/organizations/:id/email-accounts | List, or connect one (signs in over IMAP first, then syncs in the background). |
POST /api/v1/organizations/:id/email-accounts/oauth/:provider | Start an OAuth connection; answers the consent URL. |
GET /api/v1/email-accounts/:id/mails | One folder, filtered by importance and search, paginated. |
POST /api/v1/email-accounts/:id/sync | Sync now. |
DELETE /api/v1/email-accounts/:id | Disconnect and drop the synced mail. |
POST /api/v1/email-accounts/:id/send | Send a new mail: To and Cc (20 addresses in all), subject, text and HTML. |
GET, PATCH /api/v1/mails/:id | Read a mail; mark it read or starred, or set its importance. |
POST /api/v1/mails/:id/move, DELETE /api/v1/mails/:id | Move to inbox, archive, spam or trash; delete moves to the trash, or deletes for good from it. |
POST /api/v1/mails/bulk | One action on many mails of one account and folder: read, unread, trash or move. |
POST /api/v1/mails/:id/reply, /forward | Reply (threaded, quoting the original) or forward (up to 20 addresses, optional note). |
Send and reply take JSON, or multipart/form-data with that JSON in a payload field and the files in attachments (at most 10 files of 18 MB in all).
AI
| Route | Does |
|---|---|
POST /api/v1/mails/:id/summary | The AI summary (kept after the first call). |
POST /api/v1/mails/:id/reply-suggestions | Up to three short replies. |
POST /api/v1/mails/:id/draft-reply | A whole reply written by the model. |
POST /api/v1/mails/:id/skills/:key | Run a skill on the mail. |
GET, PUT, DELETE /api/v1/organizations/:id/llm-provider | The organization's model (owner). |
POST /api/v1/organizations/:id/llm-provider/models | The models a provider offers. |
GET /api/v1/llm-providers, PUT, DELETE /api/v1/llm-providers/global, PUT /api/v1/llm-providers/:id/scope | Providers you can see; the global one and moving a provider (super user). |
Agent
| Route | Does |
|---|---|
POST /api/v1/agent/chat | One assistant turn, streamed as server-sent events. |
GET, POST /api/v1/agent/conversations, GET, DELETE /api/v1/agent/conversations/:id | Conversation history. |
POST /api/v1/agent/actions/:id/approve, /deny | Decide a proposed mail. |
GET /api/v1/agent/drafts, POST /api/v1/agent/drafts/:id/approve, /discard | The AI Drafts queue. |
GET, POST /api/v1/organizations/:id/agent-bots, GET, PUT, DELETE /api/v1/agent-bots/:id | Agent bots. |
GET, POST /api/v1/organizations/:id/skills, PUT /api/v1/organizations/:id/skills/builtin/:key, PUT, DELETE /api/v1/skills/:id | Skills. |
GET, POST /api/v1/organizations/:id/mcp-servers, POST .../mcp-servers/test | MCP servers the assistant calls. |
PUT, DELETE /api/v1/mcp-servers/:id, POST /api/v1/mcp-servers/:id/sync, /test, /oauth/start | Manage one. |
Outside /api/v1
| Route | Does |
|---|---|
GET /health | {"data":{"status":"ok"}}; no sign-in. |
POST /mcp | MCP for outside clients, with an API key. See Connect MCP clients. |