Enterprise API - BuildBuddy

The BuildBuddy API lets you programmatically obtain information about your Bazel builds. API access is available to Enterprise BuildBuddy customers. Requests can be made via JSON or using Protobuf. The examples below use the JSON API. For a full overview of the service, view the service definition or the individual protos.

Authentication

All API requests require authentication using the x-buildbuddy-api-key header:

curl -H 'x-buildbuddy-api-key: YOUR_BUILDBUDDY_API_KEY' \
  https://app.buildbuddy.io/api/v1/GetInvocation

GetInvocation

Retrieves invocations associated with a commit SHA or invocation ID.

Endpoint

POST https://app.buildbuddy.io/api/v1/GetInvocation

Request

selector

InvocationSelector

required

The selector defining which invocation(s) to retrieve

selector.invocation_id

string

Return only the invocation with this invocation ID

selector.commit_sha

string

Return only invocations with this commit SHA

include_metadata

boolean

default:"false"

If true, includes additional build metadata

include_artifacts

boolean

default:"false"

If true, include artifacts attached to the invocation

include_child_invocations

boolean

default:"false"

If true, include child invocations (if this invocation was a workflow)

page_token

string

The next_page_token value returned from a previous request

Response

invocation

Invocation[]

Invocations matching the request, possibly capped by a server limit

next_page_token

string

Token to retrieve the next page of results, or empty if there are no more results

Example

curl -d '{"selector": {"invocation_id":"c6b2b6de-c7bb-4dd9-b7fd-a530362f0845"}}' \
  -H 'x-buildbuddy-api-key: YOUR_BUILDBUDDY_API_KEY' \
  -H 'Content-Type: application/json' \
  https://app.buildbuddy.io/api/v1/GetInvocation

GetLog

Retrieves build logs associated with an invocation ID.

Endpoint

POST https://app.buildbuddy.io/api/v1/GetLog

Request

selector

LogSelector

required

The selector defining which log(s) to retrieve

selector.invocation_id

string

required

Return only logs associated with this invocation ID

page_token

string

The next_page_token value returned from a previous request

Response

log

Log

Log matching the request, possibly capped by a server limit

log.id.invocation_id

string

The invocation ID

log.contents

string

The contents of the log

next_page_token

string

Token to retrieve the next page of the log, or empty if there are no more logs

Example

curl -d '{"selector": {"invocation_id":"c6b2b6de-c7bb-4dd9-b7fd-a530362f0845"}}' \
  -H 'x-buildbuddy-api-key: YOUR_BUILDBUDDY_API_KEY' \
  -H 'Content-Type: application/json' \
  https://app.buildbuddy.io/api/v1/GetLog

GetTarget

Retrieves targets associated with a given invocation ID.

Endpoint

POST https://app.buildbuddy.io/api/v1/GetTarget

Request

selector

TargetSelector

required

The selector defining which target(s) to retrieve

selector.invocation_id

string

required

All targets returned will be scoped to this invocation

selector.target_id

string

If set, only the target with this target ID will be returned

selector.tag

string

If set, only targets with this tag will be returned

selector.label

string

If set, only the target with this target label will be returned

page_token

string

The next_page_token value returned from a previous request

Response

target

Target[]

Targets matching the request invocation, possibly capped by a server limit

target[].id

object

The resource ID components

invocation_id

string

The invocation ID

target_id

string

The target ID

target[].label

string

The label of the target (e.g., //server/test:foo)

target[].status

Status

The aggregate status of the target

target[].rule_type

string

The type of the target rule (e.g., go_library, java_binary)

target[].language

string

The language of the target rule (e.g., go, java, sh)

next_page_token

string

Token to retrieve the next page of results

Example

curl -d '{"selector": {"invocation_id":"c6b2b6de-c7bb-4dd9-b7fd-a530362f0845"}}' \
  -H 'x-buildbuddy-api-key: YOUR_BUILDBUDDY_API_KEY' \
  -H 'Content-Type: application/json' \
  https://app.buildbuddy.io/api/v1/GetTarget

GetAction

Retrieves actions associated with a given target or invocation.

Endpoint

POST https://app.buildbuddy.io/api/v1/GetAction

Request

selector

ActionSelector

required

The selector defining which action(s) to retrieve

selector.invocation_id

string

required

All actions returned will be scoped to this invocation

selector.target_id

string

If set, all actions returned will be scoped to this target

selector.configuration_id

string

If set, all actions returned will be scoped to this configuration

selector.action_id

string

If set, only the action with this action ID will be returned

selector.target_label

string

If set, only the action with this target label will be returned

page_token

string

The next_page_token value returned from a previous request

Response

action

Action[]

Actions matching the request, possibly capped by a server limit

action[].id

object

The resource ID components that identify the action

action[].file

File[]

A list of file references for action level files

action[].target_label

string

The label of the target that generated this action

action[].shard

int64

The test shard this action represents (only for test actions)

action[].run

int64

The test run this action represents (only for test actions)

action[].attempt

int64

The test attempt this action represents (only for test actions)

next_page_token

string

Token to retrieve the next page of results

Example

curl -d '{"selector": {"invocation_id":"c6b2b6de-c7bb-4dd9-b7fd-a530362f0845"}}' \
  -H 'x-buildbuddy-api-key: YOUR_BUILDBUDDY_API_KEY' \
  -H 'Content-Type: application/json' \
  https://app.buildbuddy.io/api/v1/GetAction

GetFile

Retrieves files associated with a given URI.

Endpoint

POST https://app.buildbuddy.io/api/v1/GetFile

Request

uri

string

required

File URI corresponding to the uri field in the File messageIf the BuildBuddy instance supports ZSTD transcoding, the literal string /blobs/ in the URI (third-to-last path segment) may be replaced with /compressed-blobs/zstd/, and the server will return a compressed payload.Examples:

Uncompressed blob with remote instance name of “ci”: bytestream://remote.buildbuddy.io/ci/blobs/09e6fe6e1fd8c8734339a0a84c3c7a0eb121b57a45d21cfeb1f265bffe4c4888/216
zstd-compressed blob with no remote instance name: bytestream://remote.buildbuddy.io/compressed-blobs/zstd/09e6fe6e1fd8c8734339a0a84c3c7a0eb121b57a45d21cfeb1f265bffe4c4888/216

Response

data

bytes

The file data

Example

curl -d '{"uri":"bytestream://remote.buildbuddy.io/buildbuddy-io/buildbuddy/ci/blobs/09e6fe6e1fd8c8734339a0a84c3c7a0eb121b57a45d21cfeb1f265bffe4c4888/216"}' \
  -H 'x-buildbuddy-api-key: YOUR_BUILDBUDDY_API_KEY' \
  -H 'Content-Type: application/json' \
  https://app.buildbuddy.io/api/v1/GetFile

DeleteFile

Deletes a specific cache entry associated with a URI. This can be used to address cache poisoning.

Endpoint

POST https://app.buildbuddy.io/api/v1/DeleteFile

Request

uri

string

required

URI of file to deleteCAS URI format: <instance_name>/<blobs|compressed-blobs/zstd>/<digest_hash>/<digest_size>Action cache URI format: <instance_name>/<blobs|compressed-blobs/zstd>/ac/<digest_hash>/<digest_size>Examples:

CAS artifact: compressed-blobs/zstd/aaaa.../2084
CAS artifact with remote_instance_name: my_instance/blobs/aaaa.../2084
Action cache artifact: blobs/ac/aaaa.../2084
Action cache artifact with remote_instance_name: my_instance/blobs/ac/aaaa.../2084

Response

Empty response on success.

Example

curl -d '{"uri":"bytestream://remote.buildbuddy.io/buildbuddy-io/buildbuddy/ci/blobs/09e6fe6e1fd8c8734339a0a84c3c7a0eb121b57a45d21cfeb1f265bffe4c4888/216"}' \
  -H 'x-buildbuddy-api-key: YOUR_BUILDBUDDY_API_KEY' \
  -H 'Content-Type: application/json' \
  https://app.buildbuddy.io/api/v1/DeleteFile

ExecuteWorkflow

Triggers a BuildBuddy Workflow for the given repository and branch/commit.

GitHub App authentication is required. The API does not support running legacy workflows. See the Workflows setup guide for more information.

Endpoint

POST https://app.buildbuddy.io/api/v1/ExecuteWorkflow

Request

repo_url

string

required

URL of the repo the workflow is running for (e.g., https://github.com/some-user/acme)

branch

string

Git branch at which the workflow should be run. At least one of branch or commit_sha must be set

commit_sha

string

Git commit SHA at which the workflow should be run. At least one of branch or commit_sha must be set

action_names

string[]

Names of the workflow actions to execute. Correspond to actions in buildbuddy.yaml. If not set, will execute all actions in the workflow config

visibility

string

default:"PRIVATE"

VISIBILITY build metadata used for the workflow invocation. Can be set to “PUBLIC” to make the workflow invocation public

async

boolean

default:"false"

If true, start the workflow but do not wait for the status to be returned

env

map<string, string>

Environment variables to apply to each action. These overrides take precedence over env vars in buildbuddy.yaml

disable_retry

boolean

default:"false"

If true, disable automatic retry of transient errors (for non-idempotent workloads)

Response

action_statuses

ActionStatus[]

A list of the actions executed by the API, or actions started if async is true

action_statuses[].action_name

string

The name of the action from buildbuddy.yaml

action_statuses[].invocation_id

string

The BuildBuddy invocation ID from executing the action

action_statuses[].status

google.rpc.Status

The gRPC status from executing the action, or from starting the action if async is true

Example

curl -d '{
  "repo_url": "https://github.com/buildbuddy-io/buildbuddy-ci-playground",
  "branch": "cool-feature",
  "commit_sha": "abc123",
  "action_names": ["Test"],
  "env": {"USE_BAZEL_VERSION": "6.4.0"}
}' \
-H "x-buildbuddy-api-key: YOUR_BUILDBUDDY_API_KEY" \
-H 'Content-Type: application/json' \
https://app.buildbuddy.io/api/v1/ExecuteWorkflow

Run

Runs a command on a remote runner hosted on a remote executor.

Endpoint

POST https://app.buildbuddy.io/api/v1/Run

Request

repo

string

URL of the repo the remote workspace should be initialized for (e.g., https://github.com/some-user/acme). If not provided, commands will run in an empty directory

branch

string

Git branch to configure the remote git workspace. At least one of branch or commit_sha must be set when repo is provided

commit_sha

string

Git commit SHA to configure the remote git workspace. At least one of branch or commit_sha must be set when repo is provided

patches

bytes[]

Local patches that should be applied to the repo before running the command. Patches will be applied using git apply in the root directory. In JSON requests, specify as a list of base64-encoded strings

steps

Step[]

required

Bash commands to run, in order. If a step fails, subsequent steps are not runExample: [{"run": "bazel build :server"}, {"run": "echo 'Hello World'"}]

env

map<string, string>

Environment variables to set in the runner env

platform_properties

map<string, string>

Platform properties to apply to the runner (e.g., {"OSFamily":"linux", "Arch":"amd64"})

remote_headers

string[]

Remote headers to be applied to the execution request. Can be used to set platform properties containing secretsExample: ["x-buildbuddy-platform.env-overrides=SECRET_NAME=SECRET_VALUE"]

timeout

string

Max time before run should be canceled (e.g., ”15s”, “2h”)

wait_until

WaitCondition

default:"STARTED"

Specifies what to wait until before returning a RunResponse. Options: QUEUED, STARTED, COMPLETED

use_system_git_credentials

boolean

default:"false"

Whether to use GitHub credentials configured on the executor. Only supported for bare runners

skip_auto_checkout

boolean

default:"false"

Whether to skip the automatic GitHub setup steps on the remote runner

Response

invocation_id

string

The invocation ID of the remote run

Example

curl -d '{
  "repo": "[email protected]:buildbuddy-io/buildbuddy.git",
  "branch": "main",
  "steps": [{"run": "bazel test //..."}]
}' \
-H "x-buildbuddy-api-key: YOUR_BUILDBUDDY_API_KEY" \
-H 'Content-Type: application/json' \
https://app.buildbuddy.io/api/v1/Run

CreateUserApiKey

Creates an API key (authentication token) for a given user.

To create API keys for users within an organization, this API must be called with an Org admin key.Org admin keys can be created via the BuildBuddy UI by navigating to Settings > Org API keys, then creating a new key with the “Org admin” capability.

Endpoint

POST https://app.buildbuddy.io/api/v1/CreateUserApiKey

Request

user_id

string

required

BuildBuddy user ID of the user to create the API key forExample: US1234567890

label

string

Optional display name for the API key. This is not required to be uniqueExample: My API key

expires_in

duration

Optional duration after which the API key should expire. If unset, the API key does not expireExample: 720h (30 days), 8760h (1 year)

Response

api_key

ApiKey

The API key that was created

Show ApiKey

api_key_id

string

The unique ID of this API keyExample: AK1234567890

value

string

The API key value passed in API requestsExample: eXaMpLeSecRetKeY314159

This is the only time the API key value will be returned. Store it securely.

label

string

Optional display name for the API key

expiration_timestamp

timestamp

Timestamp at which the API key expires. If unset, the API key does not expire

Example

curl -d '{
  "user_id": "US1234567890",
  "label": "CI API Key",
  "expires_in": "8760h"
}' \
-H "x-buildbuddy-api-key: YOUR_ORG_ADMIN_API_KEY" \
-H 'Content-Type: application/json' \
https://app.buildbuddy.io/api/v1/CreateUserApiKey

Response Example

{
  "apiKey": {
    "apiKeyId": "AK9876543210",
    "value": "bXlTZWNyZXRLZXkxMjM0NTY=",
    "label": "CI API Key",
    "expirationTimestamp": "2025-03-03T00:00:00Z"
  }
}

Overview

Architecture

Monitoring

​Authentication

​GetInvocation

​Endpoint

​Request

​Response

​Example

​GetLog

​Endpoint

​Request

​Response

​Example

​GetTarget

​Endpoint

​Request

​Response

​Example

​GetAction

​Endpoint

​Request

​Response

​Example

​GetFile

​Endpoint

​Request

​Response

​Example

​DeleteFile

​Endpoint

​Request

​Response

​Example

​ExecuteWorkflow

​Endpoint

​Request

​Response

​Example

​Run

​Endpoint

​Request

​Response

​Example

​CreateUserApiKey

​Endpoint

​Request

​Response

​Example

​Response Example

Build docs developers (and LLMs) love

Authentication

GetInvocation

Endpoint

Request

Response

Example

GetLog

Endpoint

Request

Response

Example

GetTarget

Endpoint

Request

Response

Example

GetAction

Endpoint

Request

Response

Example

GetFile

Endpoint

Request

Response

Example

DeleteFile

Endpoint

Request

Response

Example

ExecuteWorkflow

Endpoint

Request

Response

Example

Run

Endpoint

Request

Response

Example

CreateUserApiKey

Endpoint

Request

Response

Example

Response Example