# Buckets

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

| Method | Operation | Path |
| --- | --- | --- |
| **`GET`** | [List buckets](#list-buckets) | `/v0/buckets` |
| **`POST`** | [Create a bucket](#create-a-bucket) | `/v0/buckets` |
| **`GET`** | [Get a bucket](#get-a-bucket) | `/v0/buckets/:bucketId` |
| **`POST`** | [Update a bucket](#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

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

### Response

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

### Related interfaces

- **CLI:** `interfold buckets list`
- **MCP:** `list_buckets`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/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

~~~sh
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

~~~json
{
  "id": "<bucket-id>",
  "appAccountId": "<account-id>",
  "name": "Website files",
  "createdAt": "2026-09-20T12:00:00.000Z",
  "updatedAt": "2026-09-20T12:00:00.000Z"
}
~~~

### Related interfaces

- **CLI:** `interfold buckets create --name "Website files"`
- **MCP:** `create_bucket`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/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

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

### Response

~~~json
{
  "id": "<bucket-id>",
  "appAccountId": "<account-id>",
  "name": "Website files",
  "createdAt": "2026-09-20T12:00:00.000Z",
  "updatedAt": "2026-09-20T12:00:00.000Z"
}
~~~

### Related interfaces

- **CLI:** `interfold buckets get <bucket-id>`
- **MCP:** `get_bucket`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/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

~~~sh
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

~~~json
{
  "id": "<bucket-id>",
  "appAccountId": "<account-id>",
  "name": "Website files",
  "createdAt": "2026-09-20T12:00:00.000Z",
  "updatedAt": "2026-09-20T12:00:00.000Z"
}
~~~

### Related interfaces

- **CLI:** `interfold buckets update <bucket-id> --name "Production files"`
- **MCP:** `update_bucket`

See [Errors](/api-reference/errors) for the standard error envelope and
[Authentication](/api-reference/authentication) for API key handling.

## Shared behavior

All operations use the [API authentication](/api-reference/authentication),
[error](/api-reference/errors), and [rate-limit](/api-reference/rate-limits)
contracts. List operations use [standard pagination](/api-reference/pagination)
unless the operation says otherwise.