Drive API

Lists the immediate children of a folder. Pass folder_uuid as a query parameter to list a folder’s contents; omit it to list the Drive root. Trashed items are excluded. An unknown or invisible folder is 404 folder_not_found. Scope drive.read.

curl "https://api.cirrux.info/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.info/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.info/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 alongside the file name, type and size. data is URL-safe base64 without padding. Like the simple upload, this buffers in memory and is capped at 100 MB (413 file_too_large), so use the chunked download for larger files. Scope drive.read.

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

For files above the in-memory cap, up to 2 GiB, upload and download ciphertext directly to storage in chunks. Cirrux hands you a per-file data_key (base64, over TLS) and presigned URLs; your client does the AES-256-GCM chunk encryption itself, so plaintext never touches Cirrux. All steps use scope drive.create (upload) or drive.read (download). Presigned URLs are valid for one hour; ask for them again if they run out. An upload that is not completed within 24 hours is discarded, and so is a replace: init returns the deadline as expires_at, and after it part_urls and complete answer 409 upload_expired (abort still works). When another person’s upload blocks the file, 409 upload_in_progress carries that upload’s expires_at, the latest moment it can still be holding the file.

Wire format. The object is a 16-byte header followed by the chunks. The header is the 8 magic bytes CXDRV2 plus two zero bytes, the format version (1 byte, 1), the algorithm id (1 byte, 1 for AES-256-GCM), chunk_size_bytes as a little-endian u32, and 2 zero bytes. It goes in front of the first chunk. Each chunk is a fresh 12-byte IV, the AES-256-GCM ciphertext of up to chunk_size_bytes of plaintext, and the 16-byte tag. Every chunk is authenticated with 56 bytes of additional data (AAD): the file’s file_uuid as 16 raw bytes, then the chunk index, the chunk count and that chunk’s plaintext size as little-endian u32s, then zero padding. Always the file_uuid, never the version_uuid, including for a replace: the file keeps its UUID across versions. Complete decrypts the first chunk to check this, and rejects an upload it cannot decrypt.

Upload

Download

Upload new bytes for an existing file, keeping its UUID. It works like the chunked upload above, but targets a file: Cirrux stages a new version while the current one stays live and downloadable, then swaps atomically on complete. The previous version is retained about 24 hours afterward, so a download already in progress never breaks. The file’s ctag goes up by one. It needs the editor role, and only growth over the current size counts against the workspace’s storage. All steps use scope drive.update.

Send name to rename and/or folder_uuid to move (include the key with a null value to move to the root), trashed to trash or restore, or content_modified_at to set your own date without touching the content. Omitting a key leaves it unchanged. Returns the updated drive_file. Scope drive.update (setting trashed: true also requires drive.delete). Restoring a file whose folder is still in the trash is 409 parent_trashed: restore the folder first. If a live file took its name (in any Unicode form or case) while it was in the trash, it comes back as name (1).ext (the lowest free number), and the response carries the new name. This route never changes the contents: a body with data or content_type is refused with 422 unsupported_field (naming the field) before anything is applied. Use the replace routes below for new contents.

Moves the file to the trash, where it can be restored for 30 days. Returns the file with trashed: true. Trashing a trashed file is fine. Scope drive.delete.

Permanently deletes the file. Returns 204 with an empty body. Deleting it again is 404. 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, whether or not it is empty. 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). Scope drive.read.

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_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
}

POST creates a link anyone can download the item from without signing in, and returns 201 with the drive_public_link. It starts as pending and becomes ready once the public copy is made. When a linked file’s contents are replaced, or a file finishes uploading into a linked folder, its copy is refreshed shortly after; a file still uploading isn’t listed. An item has at most one link: a second POST is 409 public_link_exists. DELETE revokes it and returns 204, or 404 public_link_not_found when there is none. Both need the manager or owner role. Scope drive.update.

curl -X POST https://api.cirrux.info/public_api/v1/drive/files/a1d9e7c8-…/public_link \
  -H "Authorization: Bearer $CIRRUX_TOKEN"

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.

A thumbnail changes when the file’s contents are replaced, and so does its ETag. With ctag set to the file’s current ctag, the URL names fixed bytes and the response carries Cache-Control: private, max-age=31536000, immutable. Without it (or with an older ctag) the response is private, no-cache: keep it, and revalidate by sending If-None-Match with its ETag to get a cheap 304 Not Modified while the picture is unchanged.

curl "https://api.cirrux.info/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 lead straight into the ongoing delta. Persist the token after each page: it’s a durable, crash-safe resume point. Scope drive.read.

as_of and freshness. as_of is the server’s clock when your request started. It does not promise that every write before it is included: a change reaches the feed once every database write that began before it has finished. That is usually immediate, but a long write elsewhere can hold changes back for longer (we have seen up to a minute). Nothing is skipped; a held-back change arrives on a later call. To read your own write back straight away, GET the item by uuid, which is always current.

curl "https://api.cirrux.info/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. An item created and trashed between two calls arrives as a create with trashed: true. A delete is permanent and carries no resource.
• Apply in order. Changes are in commit order, and a folder’s create comes before those of its children. The deletes of a cascade come in no particular order. Delivery is at-least-once, so applying must be idempotent; skip a change whose version you already have, and ignore a delete for a uuid you never saw (an aborted upload sends one).
• 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, since each is an independent domain. Items live in their owner’s workspace, so a folder someone shares with you from their organization’s workspace appears in that workspace’s feed (if you’re a member), not in your Personal one.
• Access changes. When you gain access to a folder (it is shared with you, or someone moves it into a folder you can see), the feed sends a create for it and for everything in it, parents first. When you lose access (the share is revoked, or the folder is moved somewhere you can’t see), it sends a delete for it and for everything in it, with no resource. Files work the same way. If you can still see part of what changed, through another share, that part comes as a create, so apply the changes in order.
• Page size. limit counts the changes the server reads, and an access change is one of them. A page with an access change can therefore hold more than limit changes. One too large to send in a page (more than 5,000 items) answers 410 sync_token_invalid instead, and you reseed.

An unknown apns_client_uuid is 404 apns_client_not_found, a token that is not even-length hex is 422 invalid_device_token, and a domain_identifier other than the workspace UUID is 422 invalid_domain_identifier. Each device keeps its own subscription: registering again with the same device_token (and the same apns_client_uuid, container_identifier and domain_identifier) updates it in place and returns the same uuid, so a user’s second Mac gets a subscription of its own. When a device’s token changes, register the new one; the old subscription stops at the first push APNs refuses. 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": "b3f1c2a4-3333-4a2b-8c3d-000000000002",
  "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; an unknown uuid is 404 subscription_not_found. 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: