Create a storage bucket

Endpoint

POST https://api.dairo.app/v1/buckets

Creates a named bucket and returns it with usedBytes and objectCount at 0. name is required, trimmed, at most 120 characters, and unique per account (case-insensitive); a duplicate name returns 409. The names dairo_bucket and attachments are reserved and rejected with 400. displayName, description, and metadata are optional. Each plan caps how many buckets you can hold — exceeding it returns 429. The create is not deduplicated by key: a retry after a lost response returns 409 for the name, so read the bucket back by listing. Requires buckets:write.

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

Request

cURL

curl -X POST "https://api.dairo.app/v1/buckets" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace"
  }'

Headers

Name	Type	Required	Description
`Idempotency-Key`	string	no	Optional idempotency key for safe retries of side-effecting operations. (max length 128)

Body

Required, application/json: CreateBucketRequest.

Field	Type	Required	Description
`name`	string	yes	Unique bucket name (case-insensitive per account). (min length 1, max length 128)
`displayName`	string or null	no	(max length 256)
`description`	string or null	no	(max length 1024)
`metadata`	object or null	no

Response

201 Created. Body: application/json, Bucket.

Field	Type	Required	Description
`object`	`"bucket"`	yes
`id`	string	yes	Bucket identifier (buk_*).
`name`	string	yes
`displayName`	string or null	no
`description`	string or null	no
`isDefault`	boolean	yes
`status`	`"active"`, `"archived"`	yes
`usedBytes`	integer	yes	(minimum 0)
`objectCount`	integer	yes	(minimum 0)
`metadata`	object or null	no
`createdAt`	string (date-time)	yes
`updatedAt`	string (date-time)	yes

201

{
  "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"
}

Errors

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

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