Cache registries

Use these endpoints to list, inspect, create, update, and delete a cluster's cache registries.

The cache registries API is available to all Buildkite customers in public preview. This availability applies to registry administration only. Saving and restoring cache entries with Buildkite Cache remains in private preview and requires access as described in the Buildkite Cache guide.

This API manages cache registry metadata and policy only. The API doesn't expose cache entries or agent save and restore operations. Use the web interface to configure a registry's cache store or change a cluster's default registry.

Member endpoints (get, update, and delete) accept only the cache registry's uuid as the {id} path parameter. The slug returned in responses is informational and can't be used to look up or modify a cache registry.

Policy documents must be JSON objects, not YAML or JSON-encoded strings. The API validates and normalizes each policy, so authored YAML comments and formatting aren't preserved. The create and update sections describe how omitted or null policies behave.

Cache registry data model

`uuid`	UUID of the cache registry. Use this value as the `{id}` path parameter for the get, update, and delete endpoints.
`slug`	Slug generated from the cache registry's name. Informational only, and not accepted as an identifier.
`name`	Name of the cache registry.
`description`	Description of the cache registry, or `null`.
`emoji`	Emoji for the cache registry using the emoji syntax, or `null`.
`color`	Color hex code for the cache registry, or `null`.
`policy`	Normalized cache policy that controls which jobs can save and restore entries in this registry, or `null`.
`created_at`	When the cache registry was created.
`updated_at`	When the cache registry was last updated.
`url`	Canonical API URL of the cache registry.
`cluster_url`	API URL of the parent cluster.

List cache registries

Returns a paginated list of a cluster's cache registries, ordered by slug.

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/cache-registries?per_page=30"

{
  "items": [
    {
      "uuid": "b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
      "slug": "ruby-gems",
      "name": "Ruby gems",
      "description": "Shared Ruby dependencies",
      "emoji": "\u003aruby\u003a",
      "color": "#cc342d",
      "policy": {
        "save": { "scopes": { "branch": true } },
        "restore": { "scopes": [{ "branch": "$current" }] },
        "rules": [
          { "effect": "allow", "action": ["save"] },
          { "effect": "allow", "action": ["restore"] }
        ]
      },
      "created_at": "2026-08-11T10:15:32.000Z",
      "updated_at": "2026-08-11T10:15:32.000Z",
      "url": "https://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/cache-registries/b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
      "cluster_url": "https://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf"
    }
  ],
  "links": {
    "self": "https://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/cache-registries?per_page=30",
    "next": "https://api.buildkite.com/v2/organizations/acme-inc/clusters/42f1a7da-812d-4430-93d8-1cc7c33a6bcf/cache-registries?after=...&per_page=30"
  }
}

This endpoint uses cursor-based pagination. The response body is a JSON object with an items array and a links object. Use the next URL from links to fetch the next page. Follow that URL instead of constructing cursor values.

Optional query string parameters:

`per_page`	How many results to return per page. Default: `30` Maximum: `100`
`after`	Return results after this cursor value. Mutually exclusive with `before`.
`before`	Return results before this cursor value. Mutually exclusive with `after`.

per_page

How many results to return per page.

Default: 30

Maximum: 100

after Return results after this cursor value. Mutually exclusive with before.

before Return results before this cursor value. Mutually exclusive with after.

Required scope: read_clusters

Required permission: permission to manage the cluster

Success response: 200 OK

Error responses:

`400 Bad Request`	Invalid `per_page` or cursor value, or both `after` and `before` supplied
`404 Not Found`	The cluster doesn't exist

Get a cache registry

Returns the details for a single cache registry, looked up by UUID.

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/cache-registries/{id}"

The response contains the cache registry data model.

Required scope: read_clusters

Required permission: permission to manage the cluster

Success response: 200 OK

Error response: 404 Not Found when the cluster doesn't exist, or when no cache registry matches the given UUID in this cluster. Passing a slug instead of a UUID also returns 404 Not Found.

Create a cache registry

Creates a new cache registry in a cluster.

Use this policy only with trusted builds

This example allows every job to save and restore cache entries. Use it only for registries used exclusively by trusted builds. Branch names aren't trust boundaries, and this policy can share entries across pipelines. Don't allow untrusted builds to save caches that trusted builds can restore. See Configure a cache policy before sharing a registry with untrusted builds.

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/cache-registries" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ruby gems",
    "description": "Shared Ruby dependencies",
    "emoji": "\u003aruby\u003a",
    "color": "#cc342d",
    "policy": {
      "save": { "scopes": { "branch": true } },
      "restore": { "scopes": [{ "branch": "$current" }] },
      "rules": [
        { "effect": "allow", "action": "save" },
        { "effect": "allow", "action": "restore" }
      ]
    }
  }'

The response contains the created cache registry data model.

Required request body properties:

`name`	Name of the cache registry. Example: `"Ruby gems"`

Optional request body properties:

`description`	Description of the cache registry.
`emoji`	Emoji for the cache registry using the emoji syntax.
`color`	Color hex code for the cache registry.
`policy`	Cache policy as a JSON object that controls which jobs can save and restore entries. See Configure a cache policy for the policy structure. Omit this property or set it to `null` when creating a registry to use the default unrestricted policy.

The cache store can't be set through this API. New cache registries use agent-managed storage.

Required scope: write_clusters

Required permission: permission to manage the cluster

Success response: 201 Created

Error responses:

`400 Bad Request`	The request body isn't a valid JSON object
`404 Not Found`	The cluster doesn't exist
`415 Unsupported Media Type`	The request doesn't use an `application/json` content type
`422 Unprocessable Entity`	The request is missing `name`, contains an unsupported field or invalid policy, or a cache registry with the resulting slug already exists in this cluster

Update a cache registry

Updates a cache registry, looked up by UUID. Properties omitted from the request body are left unchanged. Supplying policy replaces the entire policy rather than merging its nested properties.

Use this policy only with trusted builds

This example allows every job to save and restore cache entries within its pipeline. Use it only for registries used exclusively by trusted builds. Pipeline scoping doesn't isolate trusted and untrusted builds within the same pipeline. Don't allow untrusted builds to save caches that trusted builds can restore.

curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/cache-registries/{id}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ruby gems",
    "description": "Updated description",
    "policy": {
      "save": { "scopes": { "pipeline": true } },
      "restore": { "scopes": [{ "pipeline": "$current" }] },
      "rules": [
        { "effect": "allow", "action": "save" },
        { "effect": "allow", "action": "restore" }
      ]
    }
  }'

The response contains the updated cache registry data model.

Optional request body properties:

`name`	Name of the cache registry. Changing the name regenerates the registry's slug.
`description`	Description of the cache registry. Set to `null` to clear it.
`emoji`	Emoji for the cache registry using the emoji syntax. Set to `null` to clear it.
`color`	Color hex code for the cache registry. Set to `null` to clear it.
`policy`	Cache policy as a JSON object that controls which jobs can save and restore entries. See Configure a cache policy for the policy structure. Set to `null` to clear the policy, which denies saves and restores. Unlike creation, updating with `null` doesn't apply the default unrestricted policy.

The cache registry's uuid and cache store can't be changed through this API.

Required scope: write_clusters

Required permission: permission to manage the cluster

Success response: 200 OK

Error responses:

`400 Bad Request`	The request body isn't a valid JSON object
`404 Not Found`	The cluster doesn't exist, or no cache registry matches the given UUID in this cluster
`415 Unsupported Media Type`	The request doesn't use an `application/json` content type
`422 Unprocessable Entity`	The request contains an unsupported field, attempts to change the `uuid` or cache store, contains an invalid policy, or a cache registry with the resulting slug already exists in this cluster

Delete a cache registry

Deletes a cache registry, looked up by UUID. A cluster's default cache registry can't be deleted. First, open another registry in the web interface and select Settings > Set as default.

curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/clusters/{cluster.id}/cache-registries/{id}"

Required scope: write_clusters

Required permission: permission to manage the cluster, and permission to destroy the cache registry

Success response: 204 No Content

Error responses:

`404 Not Found`	The cluster doesn't exist, or no cache registry matches the given UUID in this cluster
`422 Unprocessable Entity`	The cache registry is the cluster's default registry