Drive API

Lists the immediate children of a folder. Pass folder_uuidas a query parameter to list a folder’s contents; omit it to list the Drive root. Trashed items are excluded. Scope drive.read.

curl "https://api.cirrux.co/public_api/v1/drive/files?folder_uuid=b3f1c2a4-…" \
  -H "Authorization: Bearer $CIRRUX_TOKEN"

{
  "object": "list",
  "url": "/v1/drive/files",
  "folder_uuid": "b3f1c2a4-1111-4a2b-8c3d-000000000001",
  "folders": [ { "object": "drive_folder", "uuid": "…", "name": "Receipts", … } ],
  "files":   [ { "object": "drive_file",   "uuid": "…", "name": "april-2026.pdf", … } ]
}

Lists everything currently in the trash: every trashed (but not yet permanently deleted) folder and file you can see, flat across the whole workspace. Trash is a special folder, so the response mirrors the /v1/drive/files envelope. Restore an item with POST /v1/drive/files/{uuid} or /v1/drive/folders/{uuid} and trashed: false. Scope drive.read.

curl https://api.cirrux.co/public_api/v1/drive/trash \
  -H "Authorization: Bearer $CIRRUX_TOKEN"

{
  "object": "list",
  "url": "/v1/drive/trash",
  "folders": [ { "object": "drive_folder", "uuid": "…", "name": "Old receipts", "trashed": true, … } ],
  "files":   [ { "object": "drive_file",   "uuid": "…", "name": "draft.pdf",     "trashed": true, … } ]
}

Returns a single drive_file. Scope drive.read.

Uploads a file whose bytes you send inline as base64. Cirrux encrypts and stores it. This route buffers the whole file in memory, so it is capped at 100 MB— use the chunked flow below for larger files. Returns 201 with the created drive_file. Scope drive.create.

curl -X POST https://api.cirrux.co/public_api/v1/drive/files \
  -H "Authorization: Bearer $CIRRUX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hello.txt",
    "content_type": "text/plain",
    "data": "aGVsbG8gd29ybGQ=",
    "folder_uuid": null
  }'

Returns the decrypted contents as base64, alongside the file metadata. Like the simple upload, this buffers in memory — use the chunked download for large files. Scope drive.read.

{
  "uuid": "a1d9e7c8-…",
  "name": "hello.txt",
  "content_type": "text/plain",
  "size": 11,
  "data": "aGVsbG8gd29ybGQ"
}

For files above the in-memory cap, upload and download ciphertext directly to storage in chunks. Cirrux hands you a per-file data_key (over TLS) and presigned URLs; your client does the AES-GCM chunk encryption itself, so plaintext never touches Cirrux. All steps use scope drive.create (upload) or drive.read (download).

Upload

Download

Send name to rename and/or folder_uuid to move (include the key with a null value to move to the root), or trashed to trash or restore. Omitting a key leaves it unchanged. Returns the updated drive_file. Scope drive.update (setting trashed: true also requires drive.delete).

Moves the file to the trash (recoverable). Returns the file with trashed: true. Scope drive.delete.

Permanently deletes the file. Returns 204 with an empty body. Scope drive.delete.

Creates a folder. Returns 201 with the drive_folder. Scope drive.create.

Returns a single drive_folder. Scope drive.read.

Send name to rename, parent_uuid to move (null moves to the root), color (a #RRGGBB hex string, or blank to clear) to recolor, and/or trashed to trash or restore the folder and its subtree. Returns the updated drive_folder. Scope drive.update (setting trashed: true also requires drive.delete).

Moves the folder to the trash. Trashing cascades: every descendant folder and file is trashed too. Scope drive.delete.

Permanently deletes the folder and its entire subtree. Returns 204. Scope drive.delete.

Returns a drive_sharing object: the direct grants on the item and its public link, if any. You only need to be able to see the item (viewer or higher).

The grant object

The public link object

{
  "object": "drive_sharing",
  "resource_type": "folder",
  "resource_uuid": "b3f1c2a4-…",
  "accesses": [
    {
      "object": "drive_access",
      "uuid": "d4a0b8fb-…",
      "principal_type": "user",
      "principal_user_uuid": "9c2e7a10-…",
      "principal_workspace_uuid": null,
      "principal_email": "sam@example.com",
      "role": "editor",
      "status": "accepted",
      "created_at": "2026-06-19T09:13:40.000Z",
      "updated_at": "2026-06-19T09:13:40.000Z"
    }
  ],
  "public_link": null
}

Returns the preview as raw image bytes (Content-Type: image/jpeg or image/png). A trashed file still serves its thumbnail; only a permanently deleted file returns 404.

The bytes for a given file and variant never change, so responses are cacheable: Cache-Control: private, max-age=31536000, immutable plus an ETag. Send If-None-Match with the stored ETag to get a 304 Not Modified.

curl "https://api.cirrux.co/public_api/v1/drive/files/a1d9e7c8-…/thumbnail?variant=1024_fit" \
  -H "Authorization: Bearer $CIRRUX_TOKEN" --output thumb.jpg

Besides 200, the endpoint can return:

• 202: eligible but not rendered yet (Retry-After: 1). Rare, since clients gate on has_preview. Show the icon and retry shortly.
• 204: the file has no preview (unsupported type, over the size cap, or the render failed). Treat it like has_preview: false and stop asking for this version.
• 304: not modified (your If-None-Match matched). Reuse the cached image.

Fetch up to 25 thumbnails in one request (the File Provider batch hint). The call itself returns 200 whenever it was accepted; each item carries its own status, and ready items inline their bytes as base64. A request over 25 uuids returns 400 too_many_uuids.

{
  "object": "list",
  "thumbnails": [
    { "uuid": "a1d9e7c8-…", "status": "ready", "data": "<base64>", "content_type": "image/jpeg", "version": 3 },
    { "uuid": "b2e8f6d9-…", "status": "generating" },
    { "uuid": "c3f9a7ea-…", "status": "no_preview" },
    { "uuid": "d4a0b8fb-…", "status": "not_found" }
  ]
}

Each item’s status mirrors the single-fetch outcome:

• ready: includes data (base64), content_type and the file version.
• generating: not rendered yet; re-request it (single fetch or a later batch).
• no_preview: the file has no preview.
• not_found: unknown, invisible, or deleted uuid.

Keep calling with the returned sync_token while has_more is true; the first sync’s pages transition seamlessly into the ongoing delta. Persist the token after each page — it’s a durable, crash-safe resume point. Scope drive.read.

curl "https://api.cirrux.co/public_api/v1/drive/changes?since=$SYNC_TOKEN" \
  -H "Authorization: Bearer $CIRRUX_TOKEN"

{
  "object": "list",
  "url": "/v1/drive/changes",
  "as_of": "2026-06-19T12:41:00.000Z",
  "sync_token": "eyJ2IjoxLCJtIjoiZCIsIngiOjEyMDk0MDMzLCJpIjoxMDU5Mn0",
  "has_more": false,
  "changes": [
    {
      "type": "create",
      "resource_type": "file",
      "uuid": "a1d9e7c8-…",
      "resource": { "object": "drive_file", "name": "april-2026.pdf", "trashed": false, … }
    },
    {
      "type": "update",
      "resource_type": "file",
      "uuid": "c7b5a3d1-…",
      "resource": { "object": "drive_file", "name": "draft.pdf", "trashed": true, … }
    },
    {
      "type": "delete",
      "resource_type": "file",
      "uuid": "e9f0a1b2-…",
      "parent_uuid": "b3f1c2a4-…"
    }
  ]
}

Each change is one of:

Notes:

• Trash is an update. A trashed item arrives as an update with trashed: true; restoring sends trashed: false. A delete is permanent and carries no resource.
• Apply in order. Changes are in commit order and a parent always precedes its children. Delivery is at-least-once, so applying must be idempotent; skip a change whose version you already have.
• Folder cascade. Trashing or deleting a folder emits an explicit change for every descendant, so you never have to walk the tree yourself.
• Files still uploading are withheld until upload_status is completed.
• One workspace per feed.The feed only covers the token’s workspace. If you sync several workspaces, use a separate token and cursor for each — each is an independent domain.

Registering again for the same device (matched on apns_client_uuid + container_identifier + domain_identifier) updates it in place. Returns 201; store the returned uuid to unregister later. device_token is never returned.

{
  "object": "drive_apns_subscription",
  "uuid": "b3f1c2a4-0000-0000-0000-000000000000",
  "apns_client_uuid": "b7f3b1dc-0000-0000-0000-000000000000",
  "container_identifier": "NSFileProviderWorkingSetContainerItemIdentifier",
  "domain_identifier": "workspace-abc",
  "created_at": "2026-06-16T12:00:00.000Z",
  "updated_at": "2026-06-16T12:00:00.000Z",
  "unregistered_at": null
}

Marks the subscription unregistered; no further pushes are sent. Idempotent. Returns 200 with the subscription, now carrying an unregistered_at timestamp. Cirrux also auto-unregisters a device when APNs reports it gone (410 / BadDeviceToken).

In addition to the shared auth errors, Drive endpoints can return: