Docs menu
Docs/Developer interfaces/REST API/Buckets
View as Markdown

Buckets

Manage account-owned storage independently from the sites that serve it.

Method Operation Path
GET List buckets /v0/buckets
POST Create a bucket /v0/buckets
GET Get a bucket /v0/buckets/:bucketId
POST Update a bucket /v0/buckets/:bucketId

List buckets

List buckets in an account.

GET /v0/buckets

  • API key permission: Read-only or Read/write

Parameters

  • accountId — required account UUID.
  • limit and offset — standard pagination fields.

Request

curl \
  "https://api.interfold.dev/v0/buckets" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"

Response

{
  "buckets": [{
  "id": "<bucket-id>",
  "appAccountId": "<account-id>",
  "name": "Website files",
  "createdAt": "2026-09-20T12:00:00.000Z",
  "updatedAt": "2026-09-20T12:00:00.000Z"
}],
  "pagination": { "hasMore": false, "nextOffset": null }
}
  • CLI: interfold buckets list
  • MCP: list_buckets

See Errors for the standard error envelope and Authentication for API key handling.

Create a bucket

Create account-owned file storage.

POST /v0/buckets

  • API key permission: Read/write

Parameters

  • accountId — required account UUID.
  • name — required string, 1–100 characters.

Request

curl -X POST \
  "https://api.interfold.dev/v0/buckets" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{  "accountId": "<account-id>",  "name": "Website files"}'

Response

{
  "id": "<bucket-id>",
  "appAccountId": "<account-id>",
  "name": "Website files",
  "createdAt": "2026-09-20T12:00:00.000Z",
  "updatedAt": "2026-09-20T12:00:00.000Z"
}
  • CLI: interfold buckets create --name "Website files"
  • MCP: create_bucket

See Errors for the standard error envelope and Authentication for API key handling.

Get a bucket

Read bucket metadata.

GET /v0/buckets/:bucketId

  • API key permission: Read-only or Read/write

Parameters

  • bucketId — bucket UUID.

Request

curl \
  "https://api.interfold.dev/v0/buckets/<bucket-id>" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY"

Response

{
  "id": "<bucket-id>",
  "appAccountId": "<account-id>",
  "name": "Website files",
  "createdAt": "2026-09-20T12:00:00.000Z",
  "updatedAt": "2026-09-20T12:00:00.000Z"
}
  • CLI: interfold buckets get <bucket-id>
  • MCP: get_bucket

See Errors for the standard error envelope and Authentication for API key handling.

Update a bucket

Rename a bucket.

POST /v0/buckets/:bucketId

  • API key permission: Read/write

Parameters

  • bucketId — bucket UUID.
  • name — required string, 1–100 characters.

Request

curl -X POST \
  "https://api.interfold.dev/v0/buckets/<bucket-id>" \
  -H "Authorization: Bearer $INTERFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{  "name": "Production files"}'

Response

{
  "id": "<bucket-id>",
  "appAccountId": "<account-id>",
  "name": "Website files",
  "createdAt": "2026-09-20T12:00:00.000Z",
  "updatedAt": "2026-09-20T12:00:00.000Z"
}
  • CLI: interfold buckets update <bucket-id> --name "Production files"
  • MCP: update_bucket

See Errors for the standard error envelope and Authentication for API key handling.

Shared behavior

All operations use the API authentication, error, and rate-limit contracts. List operations use standard pagination unless the operation says otherwise.

On this page