API Documentation
The BuildBuddy API let's you programmatically obtain information about your Bazel builds. API access available to Enterprise BuildBuddy Customers.
Requests can be made via JSON or using Protobuf. The examples below are using the JSON API. For a full overview of the service, you can view the service definition or the individual protos.
GetInvocation
The GetInvocation
endpoint allows you to fetch invocations associated with a commit SHA or invocation ID. View full Invocation proto.
Endpoint
https://app.buildbuddy.io/api/v1/GetInvocation
Service
// Retrieves a list of invocations or a specific invocation matching the given
// request selector.
rpc GetInvocation(GetInvocationRequest) returns (GetInvocationResponse);
Example cURL request
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
Make sure to replace YOUR_BUILDBUDDY_API_KEY
and the invocation ID c6b2b6de-c7bb-4dd9-b7fd-a530362f0845
with your own values.
Example cURL response
{
"invocation": [
{
"id": {
"invocationId": "c7fbfe97-8298-451f-b91d-722ad91632ea"
},
"success": true,
"user": "runner",
"durationUsec": "221970000",
"host": "fv-az278-49",
"command": "build",
"pattern": "//...",
"actionCount": "1402",
"createdAtUsec": "1623193638545989",
"updatedAtUsec": "1623193638545989",
"repoUrl": "https://github.com/buildbuddy-io/buildbuddy",
"commitSha": "800f549937a4c0a1614e65501caf7577d2a00624",
"role": "CI"
}
]
}
GetInvocationRequest
// Request passed into GetInvocation
message GetInvocationRequest {
// The selector defining which invocations(s) to retrieve.
InvocationSelector selector = 1;
// The next_page_token value returned from a previous request, if any.
string page_token = 3;
}
GetInvocationResponse
// Response from calling GetInvocation
message GetInvocationResponse {
// Invocations matching the request invocation, possibly capped by a
// server limit.
repeated Invocation invocation = 1;
// Token to retrieve the next page of results, or empty if there are no
// more results in the list.
string next_page_token = 2;
}
InvocationSelector
// The selector used to specify which invocations to return.
message InvocationSelector {
// One invocation_id or commit_sha is required.
// Optional: The Invocation ID.
// Return only the invocation with this invocation ID.
string invocation_id = 1;
// Optional: The commmit SHA.
// If set, only the invocations with this commit SHA will be returned.
string commit_sha = 2;
}
Invocation
// Response from calling GetInvocation
message GetInvocationResponse {
// Invocations matching the request invocation, possibly capped by a
// server limit.
repeated Invocation invocation = 1;
// Token to retrieve the next page of results, or empty if there are no
// more results in the list.
string next_page_token = 2;
}
// Each Invocation represents metadata associated with a given invocation.
message Invocation {
// The resource ID components that identify the Invocation.
message Id {
// The Invocation ID.
string invocation_id = 1;
}
// The resource ID components that identify the Invocation.
Id id = 1;
// Whether or not the build was successful.
bool success = 3;
// The user who performed this build.
string user = 4;
// The duration of this build, from start to finish.
int64 duration_usec = 5;
// The host this build was executed on.
string host = 6;
// The command performed (usually "build" or "test").
string command = 7;
// The build patterns specified for this build.
string pattern = 8;
// The number of actions performed.
int64 action_count = 9;
// The time this invocation was created and updated, respectively. Invocations
// are created as soon as the first event is received from the client and
// updated with subsequent events until they are finalized.
int64 created_at_usec = 13;
int64 updated_at_usec = 14;
// A URL to the git repo this invocation was for.
string repo_url = 15;
// The commit SHA that this invocation was for.
string commit_sha = 16;
// The role played by this invocation. Ex: "CI"
string role = 19;
// The git branch that this invocation was for.
string branch_name = 20;
// The invocation's build metadata. Only included if include_metadata = true.
repeated InvocationMetadata build_metadata = 21;
// The invocation's workspace status.
// Only included if include_metadata = true.
repeated InvocationMetadata workspace_status = 22;
// Bazel exit code name for the invocation.
// At the time of writing, valid exit code names are listed here:
// https://github.com/bazelbuild/bazel/blob/b3602eb14cf27494a0a754bc215ec2b94d13d89b/src/main/java/com/google/devtools/build/lib/util/ExitCode.java#L42-L72
// Ex: "INTERRUPTED".
string bazel_exit_code = 23;
}
// Key value pair containing invocation metadata.
message InvocationMetadata {
string key = 1;
string value = 2;
}
GetLog
The GetLog
endpoint allows you to fetch build logs associated with an invocation ID. View full Log proto.
Endpoint
https://app.buildbuddy.io/api/v1/GetLog
Service
// Retrieves the logs for a specific invocation.
rpc GetLog(GetLogRequest) returns (GetLogResponse);
Example cURL request
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
Make sure to replace YOUR_BUILDBUDDY_API_KEY
and the invocation ID c6b2b6de-c7bb-4dd9-b7fd-a530362f0845
with your own values.