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.

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.

GET /v1/orgs/{orgId}/buckets

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

Example

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.
`objectCount`	integer	Number of objects in the bucket. Refreshed hourly — recent uploads and deletes may not be reflected yet. 0 until the first refresh.
`totalBytes`	integer	Total size of the bucket’s objects in bytes. Refreshed hourly, like objectCount.
`statsUpdatedAt`	string or null	When objectCount and totalBytes were last refreshed (hourly cadence); null until the first refresh. Format: `date-time`.
`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.

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

curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/buckets" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "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.
`objectCount`	integer	Number of objects in the bucket. Refreshed hourly — recent uploads and deletes may not be reflected yet. 0 until the first refresh.
`totalBytes`	integer	Total size of the bucket’s objects in bytes. Refreshed hourly, like objectCount.
`statsUpdatedAt`	string or null	When objectCount and totalBytes were last refreshed (hourly cadence); null until the first refresh. Format: `date-time`.
`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.

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

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.

Start

Core concepts

Agents

Build

Data and work

Operate

CLI reference

API reference

buckets.list

Example

Responses

Response body (200)

buckets.create

Request body

Example

Responses

Response body (201)

buckets.delete

Path parameters

Example

Responses

​buckets.list

​Example

​Responses

​Response body (200)

​buckets.create

​Request body

​Example

​Responses

​Response body (201)

​buckets.delete

​Path parameters

​Example

​Responses

buckets.list

Example

Responses

Response body (200)

buckets.create

Request body

Example

Responses

Response body (201)

buckets.delete

Path parameters

Example

Responses