Depot API Overview

The Depot API is a collection of endpoints that grant access to our underlying architecture that make Docker image builds fast and reliable. It allows organizations to manage projects, acquire BuildKit endpoints, and run image builds for their applications or services using our build architecture.

Our API is built with Connect, offering multiprotocol support for GRPC and HTTP JSON. We currently generate the following SDKs for interacting with Depot:

Node

Authentication

Authentication to the API is handled via an Authorization header with the value being an Organization Token that you generate inside of your Organization Settings. See the Authentication docs for more details.

Security

If you're going to be using the Depot Build API to build untrusted code, you need one Depot project per customer entity in your system. This is to ensure secure cache isolation between your customers so that one customer's build can't access another customer's build cache.

API Reference

Project Service

Docs: depot.core.v1.ProjectService

A project is an isolated cache. Projects belong to a single organization and are never shared. They represent the layer cache associated with the images built inside of it; you can build multiple images for different platforms with a single project. Or you can choose to have one project per image built.

When you want to segregate your customer builds from one another, we recommend one project per customer.

List projects for an organization

You can list all of the projects for your org with an empty request payload.

const headers = {Authorization: `Bearer ${process.env.DEPOT_TOKEN}`}
 
const result = await depot.core.v1.ProjectService.listProjects({}, {headers})
 
console.log(result.projects)

Create a project

To create a project, you need to pass a request that contains the name of the project, the id of your organization, the region you want to create the project in, and the cache volume size you want to use with the project.

Supported regions:

us-east-1
eu-central-1

const headers = {Authorization: `Bearer ${process.env.DEPOT_TOKEN}`}
 
const result = await depot.core.v1.ProjectService.createProject(
  {
    name: 'my-project',
    organizationId: 'org-id',
    regionId: 'us-east-1',
    cachePolicy: {keepBytes: 50 * 1024 * 1024 * 1024, keepDays: 14},
  },
  {headers},
)
 
console.log(result.project)

Get a project

To get a project, you need to pass the ID of the project you want to get.

const headers = {Authorization: `Bearer ${process.env.DEPOT_TOKEN}`}
 
const result = await depot.core.v1.ProjectService.getProject({projectId: 'project-id'}, {headers})
 
console.log(result.project)

Update a project

To update a project, you can pass the ID of the project you want to update and the fields you want to update.

const headers = {Authorization: `Bearer ${process.env.DEPOT_TOKEN}`}
 
const result = await depot.core.v1.ProjectService.updateProject(
  {
    projectId: 'project-id',
    name: 'my-project',
    regionId: 'us-east-1',
    cachePolicy: {keepBytes: 50 * 1024 * 1024 * 1024, keepDays: 14},
    hardware: Hardware.HARDWARE_32X64,
  },
  {headers},
)
 
console.log(result.project)

Delete a project

You can delete a project by ID. This will destroy any underlying volumes associated with the project.

await depot.core.v1.ProjectService.deleteProject({projectId: 'project-id'}, {headers})

List tokens for a project

You can list the tokens for a project by ID.

const headers = {Authorization: `Bearer ${process.env.DEPOT_TOKEN}`}
 
const result = await depot.core.v1.ProjectService.listTokens(
  {
    projectId: 'project-id',
  },
  {headers},
)

Create a project token

You can create a token for a given project ID.

const headers = {Authorization: `Bearer ${process.env.DEPOT_TOKEN}`}
 
const result = await depot.core.v1.ProjectService.createToken(
  {
    projectId: 'project-id',
    description: 'my-token',
  },
  {headers},
)

Update a project token

You can update a project token by ID.

const headers = {Authorization: `Bearer ${process.env.DEPOT_TOKEN}`}
 
const result = await depot.core.v1.ProjectService.updateToken(
  {
    tokenId: 'token-id',
    description: 'new-description',
  },
  {headers},
)

Delete a project token

You can delete a project token by ID.

const headers = {Authorization: `Bearer ${process.env.DEPOT_TOKEN}`}
 
const result = await depot.core.v1.ProjectService.deleteToken(
  {
    tokenId: 'token-id',
  },
  {headers},
)

List trust policies for a project

const policies = await depot.core.v1.ProjectService.listTrustPolicies({projectId: 'project-id'}, {headers})

Add a trust policy for a project

// GitHub
await depot.core.v1.ProjectService.addTrustPolicy(
  {
    projectId: 'project-id',
    provider: {
      case: 'github',
      value: {
        repositoryOwner: 'org',
        repository: 'repo',
      },
    },
  },
  {headers},
)

// BuildKite
await depot.core.v1.ProjectService.addTrustPolicy(
  {
    projectId: 'project-id',
    provider: {
      case: 'buildkite',
      value: {
        organizationSlug: 'org',
        pipelineSlug: 'pipeline',
      },
    },
  },
  {headers},
)

// GitHub
await depot.core.v1.ProjectService.addTrustPolicy(
  {
    projectId: 'project-id',
    provider: {
      case: 'circleci',
      value: {
        organizationUuid: 'uuid',
        projectUuid: 'uuid',
      },
    },
  },
  {headers},
)

Remove a trust policy for a project

await depot.core.v1.ProjectService.removeTrustPolicy({projectId: 'project-id', trustPolicyId: 'policy-id'}, {headers})

Build Service

Docs: depot.build.v1.BuildService

A build is a single image build within a given project. Once you create a build for a project, you get back an ID to reference it and a token for authentication.

Create a build

To create a build, you need to pass a request that contains the ID of the project you want to build in.

const headers = {Authorization: `Bearer ${process.env.DEPOT_TOKEN}`}
 
const result = await depot.build.v1.BuildService.createBuild({projectId: 'project-id'}, {headers})
 
console.log(result.buildId)
console.log(result.buildToken)

Using the build id & token

If you're not managing the build context yourself in code via buildx, you can use the Depot CLI to build a given Dockerfile as we wrap buildx inside our CLI. With a build created via our API, you pass along the project, build ID, and token as environment variables:

DEPOT_BUILD_ID=<build-id>
DEPOT_TOKEN=<build-token>
DEPOT_PROJECT_ID=<project-id>
depot build -f Dockerfile

Finish a build

Note: You only need to do this if you're managing the build context yourself in code via buildx.

To mark a build as finished and clean up the underlying BuildKit endpoint, you need to pass the ID of the build you want to finish and the error result if there was one.

const headers = {Authorization: `Bearer ${process.env.DEPOT_TOKEN}`}
await depot.build.v1.BuildService.finishBuild({buildId: 'build-id', result: {error: 'error message'}}, {headers})

BuildKit Service

Docs: depot.buildkit.v1.BuildKitService

The BuildKit service provides lower level access to the underlying BuildKit endpoints that power the image builds. They give you the ability to interact with the underlying builders without needing the Depot CLI as a dependency. For example, you can use the buildx Go library with the given BuildKit endpoint to build images from your own code via Depot.

Get a BuildKit endpoint

To get a BuildKit endpoint, you need to pass the ID of the build you want to get the endpoint for and the platform you want to build.

Supported platforms:

PLATFORM_AMD64 for linux/amd64 builds
PLATFORM_ARM64 for linux/arm64 builds

const headers = {Authorization: `Bearer ${process.env.DEPOT_TOKEN}`}
 
const createBuildResult = await depot.build.v1.BuildService.createBuild({projectId: 'project-id'}, {headers})
 
const getEndpointResult = await depot.buildkit.v1.BuildKitService.getEndpoint(
  {buildId: 'build-id', platform: 'PLATFORM_AMD64'},
  {Authorization: `Bearer ${createBuildResult.build_token}`},
)
 
console.log(getEndpointResult.connection)

When a connection is active and ready to be used the connection property will be populated with the following fields:

endpoint: The BuildKit endpoint to connect to
server_name: The server name to use for TLS verification
certificate: The certificate to use for TLS verification to the endpoint
ca_cert: The CA certificate to use for TLS verification to the endpoint

Report the health of a build

To report the health of a build, you need to pass the ID of the build you want to report and the platform.

Once you acquire a BuildKit endpoint, you must report the health of the build to Depot or the underlying resources will be removed after 5 minutes of inactivity.

const headers = {Authorization: `Bearer ${process.env.DEPOT_TOKEN}`}
 
const result = await depot.build.v1.BuildKitService.reportHealth(
  {buildId: 'build-id', platform: 'PLATFORM_AMD64'},
  {headers},
)

Release the endpoint for a build

To release the endpoint for a build, you need to pass the ID of the build you want to release and the platform.

This endpoint tells Depot you're are done using that endpoint and we can schedule it for removal.

const headers = {Authorization: `Bearer ${process.env.DEPOT_TOKEN}`}
 
const result = await depot.build.v1.BuildKitService.releaseEndpoint(
  {buildId: 'build-id', platform: 'PLATFORM_AMD64'},
  {Authorization: `Bearer ${createBuildResult.build_token}`},
)