User profile and workspace API

Read who the request is acting as: the signed-in user and the workspace the token belongs to. This is the endpoint to call right after an OAuth exchange to learn the account you were granted access to. It lives under https://api.cirrux.info/public_api/v1/user.

The user object is only present for a user-scoped OAuth token. A workspace API key has no signed-in user, so the response carries only workspace. This is and GET /v1/workspace/storage are the only endpoints a workspace API key can call today.

The user object

Field	Type	Required	Description
object	string	no	Always `user`.
uuid	string	no	Unique identifier of the user.
username	string	no	The user’s login handle.
first_name	string \| null	no	Given name, when set.
last_name	string \| null	no	Family name, when set.
profile_image_url	string \| null	no	Public URL of the user’s profile image at full resolution (512×512), or `null` when they have none.
profile_image_thumbnail_url	string \| null	no	Public URL of a small square thumbnail (80×80) of the same image, or `null`. Use this for avatars in lists and menus.

The workspace object

Field	Type	Required	Description
object	string	no	Always `workspace`.
uuid	string	no	Unique identifier of the workspace.
name	string	no	Display name of the workspace.
type	string	no	What kind of workspace this is: `personal` (a single-person workspace), `organization` (a team with multiple members) or `system` (an internal Cirrux workspace).

The workspace storage object

Storage is pooled per workspace, not per person. Every member adds to the pool (20 GB each on the standard tier, 100 GB on plus), and everything the members keep counts against it: mail, Google backups, Drive files and documents. These are the same numbers the Drive web app shows at the bottom of its sidebar.

Field	Type	Required	Description
object	string	no	Always `workspace_storage`.
workspace_uuid	string	no	The workspace the pool belongs to.
used_bytes	integer	no	Bytes stored across the whole workspace. Can be larger than `pool_bytes` when the workspace has outgrown its tier.
pool_bytes	integer	no	The size of the pool. An upload that would take `used_bytes` past it is refused with `422 storage_limit_exceeded`.

Endpoints

Get the current profile

GET/v1/user/profile

Returns the authenticated user (omitted for API-key auth) and their workspace. Scope user.profile.

curl https://api.cirrux.info/public_api/v1/user/profile \
  -H "Authorization: Bearer $CIRRUX_TOKEN"

{
  "user": {
    "object": "user",
    "uuid": "a1d9e7c8-2222-4a2b-8c3d-000000000001",
    "username": "ada",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "profile_image_url": "https://…/512_normal.jpg",
    "profile_image_thumbnail_url": "https://…/80_crop.jpg"
  },
  "workspace": {
    "object": "workspace",
    "uuid": "b3f1c2a4-3333-4a2b-8c3d-000000000002",
    "name": "Analytical Engines",
    "type": "organization"
  }
}

Get the workspace's storage use

GET/v1/workspace/storage

Returns the storage pool of the workspace the token belongs to and how much of it is used. Scope user.profile. Every Drive file the API returns lives in this workspace, so this is the pool it counts against. Within the pool a file is charged to its owner, not to whoever uploaded it, so moving a file into a folder someone else owns moves its bytes to them without changing used_bytes. Drive files and documents count as soon as they are stored; mail and backups are added up again overnight.

curl https://api.cirrux.info/public_api/v1/workspace/storage \
  -H "Authorization: Bearer $CIRRUX_TOKEN"

{
  "object": "workspace_storage",
  "workspace_uuid": "b3f1c2a4-3333-4a2b-8c3d-000000000002",
  "used_bytes": 31138512896,
  "pool_bytes": 64424509440
}

API-key auth

Called with a workspace API key, the same endpoint returns only the workspace, because there is no signed-in user to describe.

{
  "workspace": {
    "object": "workspace",
    "uuid": "b3f1c2a4-3333-4a2b-8c3d-000000000002",
    "name": "Analytical Engines",
    "type": "organization"
  }
}