API
Cirrux has a public HTTP API for building on top of your workspace. Requests and responses are JSON, served under the base URL https://api.cirrux.info/public_api. Every endpoint below is versioned under /v1.
Authentication
Bearer tokens & scopes
Authenticate every request with a bearer token in the Authorization header. Tokens carry scopes that gate what each endpoint can do.
Authorization: Bearer <access-token> Content-Type: application/json
Two kinds of token exist: workspace API keys (created by a workspace admin) and user-scoped OAuth access tokens (issued to an app acting on behalf of a signed-in user). Every endpoint except GET /v1/user/profile and GET /v1/workspace/storage acts on a specific user’s data (mail, Drive, Calendar, Documents, contacts), so it needs a user-scoped OAuth token and answers a workspace API key with 403 forbidden. Today a workspace API key can only read the workspace profile and storage.
The available scopes are:
| Field | Type | Required | Description |
|---|---|---|---|
| user.profile | scope | no | Read the signed-in user’s profile. |
| email.read | scope | no | Read mailboxes, threads and messages. |
| email.write | scope | no | Change mail: labels, read and flag state, moves, drafts, and a mailbox’s labels and filters. |
| email.send | scope | no | Send a draft. |
| drive.read | scope | no | List, read and download Drive files and folders, read sharing settings, thumbnails and the changes feed. |
| drive.create | scope | no | Create folders and upload files. |
| drive.update | scope | no | Rename, move, recolor and restore files and folders, replace a file’s contents, and create or revoke public links. |
| drive.delete | scope | no | Trash and permanently delete files and folders. |
| calendar.read | scope | no | Read calendars and the events on them. |
| calendar.write | scope | no | Create, change and delete calendar events. |
| contacts.read | scope | no | Read addressbooks and contacts. |
| contacts.write | scope | no | Create, change and delete contacts. |
| docs.read | scope | no | List and read Cirrux Docs documents. |
| docs.comment | scope | no | Comment on documents, suggest changes, and withdraw your own suggestions. |
| docs.write | scope | no | Create, edit, rename, trash and restore documents, attach files, and accept or reject suggestions. |
Errors
Error responses
Errors return a non-2xx status and a JSON body with a machine-readable error code and a human error_description. Some errors add extra fields (for example max_size). The API is rate limited to 600 requests per minute per token, and to 60 requests per minute per IP address for requests that carry no bearer token. A 429 carries Retry-After (in seconds) and X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
{
"error": "insufficient_scope",
"error_description": "Required scope: drive.update"
}| Status | error | When |
|---|---|---|
| 400 | invalid_json | The request body is not valid JSON. |
| 400 | invalid_body | The request body is JSON but not an object. |
| 401 | invalid_request | The Authorization header is missing or malformed, or the API key or access token is unknown, expired or revoked. |
| 403 | forbidden | The endpoint requires a user-scoped OAuth token. |
| 403 | insufficient_scope | The token is missing the scope the endpoint requires. |
| 404 | not_found | The resource does not exist or is not visible to you. |
| 422 | invalid_uuid | An identifier in the path, query string or body is not a valid UUID. |
| 429 | rate_limited | Too many requests. Wait for Retry-After seconds. |
Per-resource error codes (e.g. name_taken, file_too_large, sync_token_invalid) are documented alongside each endpoint.
Reference
User profile and workspace
Read the signed-in user and their workspace, including profile image URLs, the workspace type and how much of its storage pool is used.
Drive
List, upload, download, replace, organize, trash and delete files and folders. Read sharing settings, create and revoke public links, fetch thumbnails, and keep a client in sync with a delta changes feed and push notifications for native sync apps.
Calendar
List a user’s calendars, read what is on them in a time window with recurring series already expanded, and create, change and delete events, a whole series or a single occurrence.
Documents
Find the Cirrux Docs documents a user owns or has been shared, read them as markdown, edit them, attach files, comment, suggest changes and decide them, create, rename, and move them in and out of Trash.
Webhooks
Get a signed HTTPS callback the moment mail arrives in a mailbox, instead of polling for it. Includes verifying the signature and what happens when your endpoint is down.
The API also has endpoints for mail (mailboxes, threads, emails, labels, filters, drafts, attachments and search) and for addressbooks and contacts, under the scopes listed above. They do not have reference pages here yet. The Cirrux CLI is built on them.