> ## Documentation Index
> Fetch the complete documentation index at: https://docs.korve.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# buckets

> Named object-storage buckets, listed per organization. A bucket scoped to a project is usable only there; an organization-level shared bucket is usable from every project. Storage operations address a bucket by name via their `bucket` query parameter; without one they keep the original per-environment scope.

Named object-storage buckets, listed per organization. A bucket scoped to a project is usable only there; an organization-level shared bucket is usable from every project. Storage operations address a bucket by name via their `bucket` query parameter; without one they keep the original per-environment scope.

## buckets.list

List all of the organization's buckets — project-scoped ones (each annotated with its project's slug) and organization-level shared ones (project null). Every project starts with a default bucket named after its slug.

```text theme={null}
GET /v1/orgs/{orgId}/buckets
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/buckets" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                 |
| ------ | --------------------------- |
| `200`  | Buckets, ascending by name. |

### Response body (200)

An array of objects with these fields:

| Field       | Type           | Description                                                                                                          |
| ----------- | -------------- | -------------------------------------------------------------------------------------------------------------------- |
| `id`        | string         | —                                                                                                                    |
| `name`      | string         | Bucket name — unique within the organization. Pattern: `^[a-z][a-z0-9-]{1,61}$`.                                     |
| `region`    | string         | The bucket's storage area id (see regions.list). Set at creation.                                                    |
| `project`   | string or null | Slug of the project the bucket is scoped to; null for an organization-level shared bucket usable from every project. |
| `createdAt` | string         | Format: `date-time`.                                                                                                 |

## buckets.create

Create a bucket. Scope it to one project by passing that project's id or slug, or omit `project` for an organization-level shared bucket usable from every project. Names follow project-slug rules and are unique per organization.

```text theme={null}
POST /v1/orgs/{orgId}/buckets
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `admin`
* **Billing:** requires active organization billing — returns `402` otherwise.
* **Risk:** `write`

### Request body

| Field     | Type   | Required | Description                                                                                                                                                   |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`    | string | Yes      | Bucket name: 2-62 chars of lowercase letters, digits, and hyphens, starting with a letter. Unique within the organization. Pattern: `^[a-z][a-z0-9-]{1,61}$`. |
| `region`  | string | No       | Storage area id (see regions.list); defaults to the platform default. Set at creation.                                                                        |
| `project` | string | No       | Project id (UUID) or slug to scope the bucket to. Omitted = organization-level shared bucket.                                                                 |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/buckets" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Storefront",
  "region": "example",
  "project": "example"
}'
```

### Responses

| Status | Description                                                  |
| ------ | ------------------------------------------------------------ |
| `201`  | Bucket created.                                              |
| `402`  | Organization billing is not active.                          |
| `404`  | No such project in this organization.                        |
| `409`  | A bucket with that name already exists in this organization. |
| `422`  | Invalid bucket name or unknown storage area.                 |

### Response body (201)

| Field       | Type           | Description                                                                                                          |
| ----------- | -------------- | -------------------------------------------------------------------------------------------------------------------- |
| `id`        | string         | —                                                                                                                    |
| `name`      | string         | Bucket name — unique within the organization. Pattern: `^[a-z][a-z0-9-]{1,61}$`.                                     |
| `region`    | string         | The bucket's storage area id (see regions.list). Set at creation.                                                    |
| `project`   | string or null | Slug of the project the bucket is scoped to; null for an organization-level shared bucket usable from every project. |
| `createdAt` | string         | Format: `date-time`.                                                                                                 |

## buckets.delete

Delete an empty bucket. A bucket that still holds any object answers 409 (BUCKET\_NOT\_EMPTY) — delete its objects first; bucket deletion never deletes data. Objects under the project's original per-environment scope are unaffected either way.

```text theme={null}
DELETE /v1/orgs/{orgId}/buckets/{bucketId}
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `admin`
* **Risk:** `destructive`

### Path parameters

| Name       | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `bucketId` | string | Yes      | —           |

### Example

```bash theme={null}
curl -X DELETE "https://api.korve.dev/v1/orgs/$ORG_ID/buckets/$BUCKET_ID" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                                                |
| ------ | ---------------------------------------------------------- |
| `200`  | Bucket deleted.                                            |
| `404`  | No such bucket in this organization.                       |
| `409`  | The bucket is not empty (BUCKET\_NOT\_EMPTY).              |
| `502`  | The emptiness check failed upstream — nothing was deleted. |