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.com/public_api. This page documents the Drive push notification endpoints; more of the API will be documented here over time.

Authentication

Bearer tokens & scopes

Authenticate every request with a bearer token in the Authorization header. Tokens carry scopes (for example drive.read) that gate what each endpoint can do.

Authorization: Bearer <access-token>
Content-Type: application/json

The Drive push endpoints below require a user-scoped OAuth token with the drive.read scope — subscriptions belong to an individual user, so workspace API keys are rejected.

Drive push notifications

Register a device to receive Apple Push Notifications whenever Drive content changes in a workspace. Designed for native File Provider sync apps that re-enumerate a domain when they receive a push. When a file or folder is added, updated (renamed, moved or trashed), or deleted, Cirrux pushes to every active subscription whose user can see that item — its owner and anyone it’s shared with.

You supply the hex APNs device_token from pushRegistry(_:didUpdate:for:) and an apns_client_uuid for a server-managed APNs client. Cirrux mints the provider JWT server-side, so the native app does not ship a .p8 key or refresh hourly provider tokens. The domain_identifier must match the authenticated workspace UUID.

Register a subscription

POST/v1/drive/apns_subscriptions

Request body:

Field	Type	Required	Description
apns_client_uuid	string	yes	Server-managed APNs client configured by Cirrux with bundle identifier, APNs environment, Team ID, Key ID, and private key.
device_token	string	yes	Hex APNs device token from pushRegistry(_:didUpdate:for:).
container_identifier	string	yes	File Provider container identifier.
domain_identifier	string	yes	File Provider domain identifier; must match the authenticated workspace UUID.

Registering again for the same device (matched on apns_client_uuid + container_identifier + domain_identifier) updates the existing subscription in place — replacing device_token, and reactivating it if it had been unregistered.

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
}

Status	error	When
400	missing_required_fields	A required field is missing or blank.
422	invalid_device_token	The device token is not an even-length hex string.
422	invalid_domain_identifier	The domain does not match the workspace UUID.
404	apns_client_not_found	The APNs client UUID is unknown or inactive.
403	forbidden	Not a user-scoped OAuth token (e.g. an API key).
403	insufficient_scope	Token lacks the `drive.read` scope.

Unregister a subscription

DELETE/v1/drive/apns_subscriptions/{uuid}

Marks the subscription as unregistered; no further pushes are sent to it. Idempotent. The {uuid} is the one returned at registration and must belong to the authenticated user. Returns 200 with the subscription, now carrying an unregistered_at timestamp.

Status	error	When
404	subscription_not_found	No such subscription for the authenticated user.
403	forbidden	Not a user-scoped OAuth token.

Cirrux also auto-unregisters a device when APNs reports it as unregistered (410) or the token is invalid (BadDeviceToken).