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.co/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). Some surfaces — the whole Drive API included — act on a specific user’s files and therefore require a user-scoped OAuth token; API keys are rejected on those endpoints.
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 | Modify mail (labels, drafts, state). |
| email.send | scope | no | Send mail. |
| drive.read | scope | no | List, read and download Drive files and folders. |
| drive.create | scope | no | Create folders and upload files. |
| drive.update | scope | no | Rename and move files and folders. |
| drive.delete | scope | no | Trash and permanently delete files and folders. |
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).
{
"error": "insufficient_scope",
"error_description": "Required scope: drive.update"
}| Status | error | When |
|---|---|---|
| 400 | invalid_request | Missing or malformed Authorization header. |
| 400 | invalid_json | The request body is not valid JSON. |
| 401 | invalid_request | Unknown or expired API key / access token. |
| 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. |
| 429 | — | Rate limited (600 requests / minute, authenticated). |
Per-resource error codes (e.g. name_taken, file_too_large, sync_token_invalid) are documented alongside each endpoint.