Dairo Docs
GuidesAPI referenceDashboard
API referenceBuckets

List storage buckets

Returns every active bucket on the account, each with a live usedBytes total and objectCount computed across its stored objects.

Endpoint
GET https://api.dairo.app/v1/buckets

Returns every active bucket on the account, each with a live usedBytes total and objectCount computed across its stored objects. The list is not paginated. The first call lazily creates the account's default bucket (dairo_bucket) and the reserved attachments bucket, so both always appear in the results. Requires the buckets:read scope.

Scope: buckets:read. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

cURL
curl "https://api.dairo.app/v1/buckets" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

Response

200 Success. Body: application/json, BucketListResponse.

FieldTypeRequiredDescription
object"list"yes
dataarray of Bucketyes
paginationPaginationyes
200
{
  "object": "list",
  "data": [
    {
      "object": "bucket",
      "id": "string",
      "name": "Ada Lovelace",
      "displayName": null,
      "description": null,
      "isDefault": true,
      "status": "active",
      "usedBytes": 0,
      "objectCount": 0,
      "metadata": {},
      "createdAt": "2026-10-19T09:30:00Z",
      "updatedAt": "2026-10-19T09:30:00Z"
    }
  ],
  "pagination": {
    "nextCursor": "string",
    "hasMore": true
  }
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.

StatusMeaning
400The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch).
401The API key is missing or invalid.
403The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted).
404No such resource in this account (resource_not_found).
409The resource already exists or its state does not allow this (duplicate_resource or a condition-specific code).
422The request is well-formed but a field failed validation (validation_failed).
429Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached).
500An unexpected error; retry with backoff, then contact support (internal_error).

Show account identity, scopes, plan, and usage

Returns the identity and live state of the account behind the calling API key: the userId and projectId, the active organization (its id and your role) and every organization you belong to (organizations), the key's id, granted scopes, allowedIps, and inboxIds restriction, and the account's plan, limits, usage, period, storage, and credits wallet.

Create a storage bucket

Creates a named bucket and returns it with usedBytes and objectCount at 0.

On this page

RequestResponseErrors