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.
`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": "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.

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.

Getting started

Agents

Primitives

API reference

CLI 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