Buckets

A bucket is the container for one gateway's data. An AI Gateway keeps all of its custom providers, provider assignments, pools, apps, user apps and API keys in the bucket of the project's production environment, so the bucket determines the project.

Buckets are listed and created in their account (/v4/accounts/{accountId}/buckets) and read at the root by their ID (/v4/buckets/{bucketId}). A project's buckets hold the bucket ID of each of its environment types, so creating or reading the project gives you the ID. Everything in a bucket, every AI Gateway resource included, is addressed under /v4/buckets/{bucketId}.

Every project has a bucket for each of its environment types, and the environments of one type share it. Custom buckets, created in the account, are not tied to an environment. Consumers and their API keys can live in one, so several projects can share them.

List buckets

GET

https://dev-api-v4-main-a471234.zuplo.app

/v4/accounts/{accountId}/buckets

Lists the account's buckets: one per environment type of each project, and the custom buckets created in the account, oldest first. Filter by projectId and environmentType to list the buckets of one project or environment type.

List buckets › path Parameters

accountId

string · maxLength: 64 · required

The account ID, a UUID.

List buckets › query Parameters

projectId

string · maxLength: 64

Only return buckets of this project.

environmentType

EnvironmentType · enum

Only return buckets of this environment type.

The environment of a project. New values may be added.

Enum values:

working-copy

preview

production

limit

integer · min: 1 · max: 100

The maximum number of items to return.

Default: 10

offset

integer · min: 0

The number of items to skip before the first item returned.

Default: 0

List buckets › Responses

A page of buckets.

BucketList

Bucket[] · required

The buckets on this page.

limit

integer · required

The page size that was applied.

offset

integer · required

The number of items skipped before this page.

total

integer · required

The number of items in the whole collection.

hasMore

boolean · required

Whether there are more items after this page.

next

string | null · required

The relative URL of the next page, or null on the last page.

Create a bucket

POST

https://dev-api-v4-main-a471234.zuplo.app

/v4/accounts/{accountId}/buckets

Creates a custom bucket in the account. A custom bucket is not tied to a project, so its projectId and environmentType are null. Every project already has a bucket for each of its environment types.

Consumers and their API keys can live in a custom bucket, so several projects can share them. An AI Gateway, including its apps and their API keys, always uses its project's production bucket. name must be unique in the account. The new bucket is read at the root: its Location is /v4/buckets/{bucketId}.

Create a bucket › path Parameters

accountId

string · maxLength: 64 · required

The account ID, a UUID.

Create a bucket › Request Body

A new custom bucket.

CreateBucketRequest

name

string · minLength: 5 · maxLength: 128 · pattern: ^[a-z0-9-]+$ · required

A friendly name, unique across Zuplo, so a name another account uses is a 409. Lowercase letters, digits and hyphens. Names that contain zuplo or start with zup, system or zprj- are reserved for Zuplo and are a 400.

description

string | null · maxLength: 1024

What the bucket is for.

Create a bucket › Responses

The bucket was created.

The container for the gateway data of one environment type of a project, or a custom bucket created in the account. Everything in a bucket is addressed under `/v4/buckets/{bucketId}`.

Bucket

id

string · required

The bucket ID.

Example: bckt_Y40ypGODCDP3S7iZxNwCAbIe

accountId

string · required

The account the bucket belongs to.

Example: 5f0c7c2e-8d3a-4b1e-9f2a-6c1d0e7b3a49

name

string · required

A friendly name, unique across Zuplo. Not an identifier; address buckets by id.

Example: contoso-qa

description

string | null · required

What the bucket is for.

projectId

string | null · required

The project the bucket belongs to. Null for a custom bucket.

Example: prj_Hn4QzW7cVb2LpX9sTe5RgK1m

required

The environment type of the project the bucket belongs to. Its environments of that type share it. Null for a custom bucket.

createdOn

string · date-time · required

When the bucket was created.

updatedOn

string · date-time · required

When the bucket was last changed.

POST/v4/accounts/{accountId}/buckets

curl https://dev-api-v4-main-a471234.zuplo.app/v4/accounts/:accountId/buckets \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "contoso-qa",
  "description": "Bucket for the QA environment"
}'

Example Request Body

{
  "name": "contoso-qa",
  "description": "Bucket for the QA environment"
}

json

application/json

Example Responses

{
  "id": "bckt_Y40ypGODCDP3S7iZxNwCAbIe",
  "accountId": "5f0c7c2e-8d3a-4b1e-9f2a-6c1d0e7b3a49",
  "name": "contoso-qa",
  "description": "description",
  "projectId": "prj_Hn4QzW7cVb2LpX9sTe5RgK1m",
  "environmentType": "working-copy",
  "createdOn": "2024-08-25T15:00:00Z",
  "updatedOn": "2024-08-25T15:00:00Z"
}

json

application/json

Get a bucket

GET

https://dev-api-v4-main-a471234.zuplo.app

/v4/buckets/{bucketId}

Returns a bucket and the account, project and environment it belongs to. Custom buckets have no project or environment. A bucket is read at the root by its ID. A bucket the caller cannot see, including one in another account than an account-scoped API key's, returns 404 as if it did not exist.

Get a bucket › path Parameters

bucketId

string · maxLength: 64 · required

The bucket ID (bckt_…). Everything in a bucket is addressed under it.

Get a bucket › Responses

The bucket.

The container for the gateway data of one environment type of a project, or a custom bucket created in the account. Everything in a bucket is addressed under `/v4/buckets/{bucketId}`.

Bucket

id

string · required

The bucket ID.

Example: bckt_Y40ypGODCDP3S7iZxNwCAbIe

accountId

string · required

The account the bucket belongs to.

Example: 5f0c7c2e-8d3a-4b1e-9f2a-6c1d0e7b3a49

name

string · required

A friendly name, unique across Zuplo. Not an identifier; address buckets by id.

Example: contoso-qa

description

string | null · required

What the bucket is for.

projectId

string | null · required

The project the bucket belongs to. Null for a custom bucket.

Example: prj_Hn4QzW7cVb2LpX9sTe5RgK1m

required

The environment type of the project the bucket belongs to. Its environments of that type share it. Null for a custom bucket.

createdOn

string · date-time · required

When the bucket was created.

updatedOn

string · date-time · required

When the bucket was last changed.

Deployments Budget Rules