Navigation

The REST API is a thin wrapper around the data API's "Getter" and "Control" sections.
It is also designed, in keeping with REST principles, to be discoverable.
As such, the details of the paths and resources are not documented here.
Begin at the root URL, and see the Data API documentation for more information.

The API described here is version 2.
The ad-hoc API from Buildbot-0.8.x, version 1, is no longer supported.

The policy for incrementing the version is when there is incompatible change added.
Removing a field or endpoint is considered incompatible change.
Adding a field or endpoint is not considered incompatible, and thus will only be described as a change in release note.
The policy is that we will avoid as much as possible incrementing version.

To get data, issue a GET request to the appropriate path.
For example, with a base URL of http://build.example.org/buildbot, the list of masters for builder 9 is available at http://build.example.org/buildbot/api/v2/builder/9/master.

Results are formatted in keeping with the JSON API specification.
The top level of every response is an object.
Its keys are the plural names of the resource types, and the values are lists of objects, even for a single-resource request.
For example:

A response may optionally contain extra, related resources beyond those requested.
The meta key contains metadata about the response, including the total count of resources in a collection.

Several query parameters may be used to affect the results of a request.
These parameters are applied in the order described (so, it is not possible to sort on a field that is not selected, for example).

Collection responses may be ordered with the order query parameter.
This parameter takes a field name to sort on, optionally prefixed with - to reverse the sort.
The parameter can appear multiple times, and will be sorted lexically with the fields arranged in the given order.
For example:

Collection responses may be paginated with the offset and limit query parameters.
The offset is the 0-based index of the first result to included, after filtering and sorting.
The limit is the maximum number of results to return.
Some resource types may impose a maximum on the limit parameter; be sure to check the resulting links to determine whether further data is available.
For example:

Data API control operations are handled by POST requests using a simplified form of JSONRPC 2.0.
The JSONRPC "method" is mapped to the data API "action", and the parameters are passed to that application.

The following parts of the protocol are not supported:

positional parameters

batch requests

Requests are sent as an HTTP POST, containing the request JSON in the body.
The content-type header must be application/json.

builderid (integer) -- the id of the builder linked to this buildrequest

buildsetid (integer) -- the id of the buildset that contains this buildrequest

claimed (boolean) -- true if this buildrequest has been claimed

claimed_at? (date) -- time at which this build has last been claimed.
None if this buildrequest has never been claimed or has been unclaimed

claimed_by_masterid? (integer) -- the id of the master that claimed this buildrequest.
None if this buildrequest has never been claimed or has been unclaimed

complete (boolean) -- true if this buildrequest is complete

complete_at? (date) -- time at which this buildrequest was completed, or None if it's still running

priority (integer) -- the priority of this buildrequest

results? (integer) -- the results of this buildrequest (see Build Result Codes), or None if not complete

submitted_at (date) -- time at which this buildrequest were submitted

waited_for (boolean) -- True if the entity that triggered this buildrequest is waiting for it to complete.
Should be used by an (unimplemented so far) clean shutdown to only start br that are waited_for.

This resource type describes completed and in-progress buildrequests.
Much of the contextual data for a buildrequest is associated with the buildset that contains this buildrequest.

This method should be called when a build request is finished.
It checks the given buildset to see if all of its buildrequests are finished.
If so, it updates the status of the buildset and send the appropriate messages.

This path selects all changes.
On a reasonabily loaded master, this can quickly return a very large result, taking minutes to process.
A specific query configuration is optimized which allows to get the recent changes: order:-changeid&limit=<n>

builder_names[] (identifier) -- names of the builders that this scheduler can trigger

button_name (string) -- label of the button to use in the UI

label (string) -- label of this scheduler to be displayed in the ui

name (identifier) -- name of this scheduler

A forcescheduler initiates builds, via a formular in the web UI.
At the moment, forceschedulers must be defined on all the masters where a web ui is configured. A particular forcescheduler runs on the master where the web request was sent.

Note

This datatype and associated enpoints will be deprecated when bug #2673 will be resolved.

A log represents a stream of textual output from a step.
The actual output is encoded as a sequence of logchunk resources.
In-progress logs append logchunks as new data is added to the end, and event subscription allows a client to "follow" the log.

Each log has a "slug" which is unique within the step, and which can be used in paths.
The slug is generated by addLog based on the name, using forceIdentifier and incrementIdentifier to guarantee uniqueness.

Todo

event: build.$buildid.step.$number.log.$logid.newlog

The log has just started.
Logs are started when they are created, so this also indicates the creation of a new log.

firstline (integer) -- zero-based line number of the first line in this chunk

logid (integer) -- the ID of log containing this chunk

A logchunk represents a contiguous sequence of lines in a logfile.
Logs are not individually addressible in the data API; instead, they must be requested by line number range.
In a strict REST sense, many logchunk resources will contain the same line.

The chunk contents is represented as a single unicode string.
This string is the concatenation of each newline terminated-line.

Each log has a type, as identified by the "type" field of the corresponding log.
While all logs are sequences of unicode lines, the type gives additional information fo interpreting the contents.
The defined types are:

t -- text, a simple sequence of lines of text

s -- stdio, like text but with each line tagged with a stream

h -- HTML, represented as plain text

In the stream type, each line is prefixed by a character giving the stream type for that line.
The types are i for input, o for stdout, e for stderr, and h for header.
The first three correspond to normal UNIX standard streams, while the header stream contains metadata produced by Buildbot itself.

The offset and limit parameters can be used to select the desired lines.
These are specified as query parameters via the REST interface, or as arguments to the get method in Python.
The result will begin with line offset (so the resulting firstline will be equal to the given offset), and will contain up to limit lines.

Mark this master as inactive.
Masters should call this method before completing an expected shutdown, and on startup.
This method will take care of deactivating or removing configuration resources like builders and schedulers as well as marking lost builds and build requests for retry.

Synchronise build properties with the db.
This sends only one event in the end of the sync, and only if properties changed.
The event contains only the updated properties, for network efficiency reasons.

codebase (string) -- revision for this sourcestamp, or none if unknown

created_at (date) -- the timestamp when this sourcestamp was created

patch? (patch) -- the patch for this sourcestamp, or none

project (string) -- user-defined project to which this sourcestamp corresponds

repository (string) -- repository where this sourcestamp occurred

revision? (string) -- revision for this sourcestamp, or none if unknown

A source stamp represents a particular version of the source code.
Absolute sourcestamps specify this completely, while relative sourcestamps (with revision = None) specify the latest source at the current time.
Source stamps can also have patches; such stamps describe the underlying revision with the given patch applied.

Note that, depending on the underlying version-control system, the same revision may describe different code in different branches (e.g., SVN) or may be independent of the branch (e.g., Git).

The created_at timestamp can be used to indicate the first time a sourcestamp was seen by Buildbot.
This provides a reasonable default ordering for sourcestamps when more reliable information is not available.

Create a new step and return its ID, number, and name.
Note that the name may be different from the requested name, if that name was already in use.
The state strings for the new step will be set to 'pending'.

configured_on[] -- list of builders on masters this worker is configured on

connected_to[] -- list of masters this worker is attached to

name (string) -- the name of the worker

workerinfo (object) --

information about the worker.

The worker information can be any JSON-able object.
In practice, it contains the following keys, based on information provided by the worker:

admin (the admin information)

host (the name of the host)

access_uri (the access URI)

version (the version on the worker)

A worker resource represents a worker to the source code monitored by Buildbot.

The contents of the connected_to and configured_on attributes are sensitive to the context of the request.
If a builder or master is specified in the path, then only the corresponding connections and configurations are included in the result.

This endpoint allows to get the raw logs for downloading into a file.
This endpoint does not provide paging capabilities.
For stream log types, the type line header characters are dropped.
'text/plain' is used as the mime type except for html logs, where 'text/html' is used.
The 'slug' is used as the filename for the resulting download. Some browsers are appending ".txt" or ".html" to this filename according to the mime-type.

#%RAML 1.0title:Buildbot Web APIversion:v2mediaType:application/jsontraits:bbget:responses:200:body:application/json:type:responseObjects.libraries.types.<<bbtype>>404:body:text/plain:example:"notfound"bbpost:body:type:<<reqtype>>responses:200:body:application/json:type:<<resptype>>404:body:text/plain:example:"notfound"bbgetraw:responses:200:headers:content-disposition:description:content disposition header allows browser to save log file with proper filenameexample:attachment; filename=stdiobody:text/html:description:"htmldataiftheobjectishtml"text/plain:description:"plaintextdataiftheobjectistext"types:build:!includetypes/build.ramlbuilder:!includetypes/builder.ramlbuildrequest:!includetypes/buildrequest.ramlbuildset:!includetypes/buildset.ramlworker:!includetypes/worker.ramlchange:!includetypes/change.ramlchangesource:!includetypes/changesource.ramlforcescheduler:!includetypes/forcescheduler.ramlidentifier:!includetypes/identifier.ramllog:!includetypes/log.ramllogchunk:!includetypes/logchunk.ramlmaster:!includetypes/master.ramlrootlink:!includetypes/rootlink.ramlscheduler:!includetypes/scheduler.ramlsourcedproperties:!includetypes/sourcedproperties.ramlsourcestamp:!includetypes/sourcestamp.ramlpatch:!includetypes/patch.ramlspec:!includetypes/spec.ramlstep:!includetypes/step.raml/:get:is:-bbget:{bbtype:rootlink}/application.spec:get:is:-bbget:{bbtype:spec}/builders:description:This path selects all buildersget:is:-bbget:{bbtype:builder}/{builderid}:uriParameters:builderid:type:numberdescription:the ID of the builderdescription:This path selects a builder by builderidget:is:-bbget:{bbtype:builder}/forceschedulers:description:This path selects all force-schedulers for a given builderget:is:-bbget:{bbtype:forcescheduler}/buildrequests:description:This path selects all buildrequests for a given builder (can return lots of data!)get:is:-bbget:{bbtype:buildrequest}/builds:description:This path selects all builds for a builder (can return lots of data!)get:is:-bbget:{bbtype:build}/{build_number}:uriParameters:build_number:type:numberdescription:the number of the build within the builderdescription:This path selects a specific build by builderid, buildnumberget:is:-bbget:{bbtype:build}/actions/stop:post:description:|stops one build.body:application/json:properties:reason:type:stringrequired:falsedescription:The reason why the build was stopped/actions/rebuild:post:description:|rebuilds one build.body:application/json:description:no parameter are needed/steps:description:This path selects all steps for the given build.get:is:-bbget:{bbtype:step}/{step_name}:uriParameters:step_name:type:identifierdescription:the slug name of the stepdescription:This path selects a specific step for the given build.get:is:-bbget:{bbtype:step}/logs:description:This path selects all logs for the given step.get:is:-bbget:{bbtype:log}/{log_slug}:uriParameters:log_slug:type:identifierdescription:the slug name of the logget:description:|This path selects a specific log in the given step.is:-bbget:{bbtype:log}/contents:get:description:|This path selects chunks from a specific log in the given step.is:-bbget:{bbtype:logchunk}/raw:get:description:|This endpoint allows to get the raw logs for downloading into a file.This endpoint does not provide paging capabilities.For stream log types, the type line header characters are dropped.'text/plain' is used as the mime type except for html logs, where 'text/html' is used.The 'slug' is used as the filename for the resulting download. Some browsers are appending ``".txt"`` or ``".html"`` to this filename according to the mime-type.is:-bbgetraw:/{step_number}:uriParameters:step_number:type:numberdescription:the number of the stepdescription:This path selects a specific step given its step numberget:is:-bbget:{bbtype:step}/logs:description:This path selects all log of a a specific stepget:is:-bbget:{bbtype:log}/{log_slug}:uriParameters:log_slug:type:identifierdescription:the slug name of the logdescription:This path selects one log of a a specific stepget:is:-bbget:{bbtype:log}/contents:get:description:|This path selects chunks from a specific log in the given step.is:-bbget:{bbtype:logchunk}/raw:get:description:|This path downloads the whole logis:-bbgetraw:/workers:description:|This path selects all workers configured for a given builderget:is:-bbget:{bbtype:worker}/{name}:description:|This path selects a worker by name filtered by given builderiduriParameters:name:type:identifierdescription:the name of the workerget:is:-bbget:{bbtype:worker}/{workerid}:description:|This path selects a worker by id filtered by given builderiduriParameters:workerid:type:numberdescription:the id of the workerget:is:-bbget:{bbtype:worker}/masters:description:|This path selects all masters supporting a given builderget:is:-bbget:{bbtype:master}/{masterid}:uriParameters:masterid:type:numberdescription:the id of the masterdescription:|This path selects a master by id filtered by given builderidget:is:-bbget:{bbtype:master}/buildrequests:/{buildrequestid}:uriParameters:buildrequestid:type:numberdescription:the id of the buildrequestget:is:-bbget:{bbtype:buildrequest}/builds:get:is:-bbget:{bbtype:build}/actions/cancel:post:description:|Cancel one buildrequest.If necessary, this will stop the builds generated by the buildrequest, including triggered builds.body:application/json:properties:reason:type:stringrequired:falsedescription:The reason why the buildrequest was cancelledget:is:-bbget:{bbtype:buildrequest}/builds:get:is:-bbget:{bbtype:build}/{buildid}:description:|This path selects a build by iduriParameters:buildid:type:numberdescription:the id of the buildget:is:-bbget:{bbtype:build}/actions/stop:post:description:|stops one build.body:application/json:properties:reason:type:stringrequired:falsedescription:The reason why the build was stopped/actions/rebuild:post:description:|rebuilds one build.body:application/json:description:no parameter are needed/changes:description:|This path selects all changes tested by a buildget:is:-bbget:{bbtype:change}/properties:description:|This path selects all properties of a buildget:is:-bbget:{bbtype:sourcedproperties}/steps:description:|This path selects all steps of a buildget:is:-bbget:{bbtype:step}/{step_number_or_name}:uriParameters:step_number_or_name:type:identifier | numberdescription:the name or number of the stepdescription:|This path selects one step of a buildget:is:-bbget:{bbtype:step}/logs:description:|This path selects all logs of a step of a buildget:is:-bbget:{bbtype:log}/{log_slug}:uriParameters:log_slug:type:identifierdescription:the slug name of the logdescription:This path selects one log of a a specific stepget:is:-bbget:{bbtype:log}/contents:get:description:|This path selects chunks from a specific log in the given step.is:-bbget:{bbtype:logchunk}/raw:get:description:|This path downloads the whole logis:-bbgetraw:/buildsets:description:this path selects all buildsetsget:is:-bbget:{bbtype:buildset}/{bsid}:description:this path selects a buildset by iduriParameters:bsid:type:identifierdescription:the id of the buildsetget:is:-bbget:{bbtype:buildset}/properties:description:|This path selects all properties of a buildset.Buildset properties is part of the initial properties of a build.get:is:-bbget:{bbtype:sourcedproperties}/workers:description:this path selects all workersget:is:-bbget:{bbtype:worker}/{name_or_id}:description:this path selects worker by name or iduriParameters:name_or_id:type:identifier | numberdescription:the name or id of a workerget:is:-bbget:{bbtype:worker}/changes:description:|This path selects **all** changes.On a reasonabily loaded master, this can quickly return a very large result, taking minutes to process.A specific query configuration is optimized which allows to get the recent changes: ``order:-changeid&limit=<n>``get:is:-bbget:{bbtype:change}/{changeid}:description:this path selects one change by iduriParameters:changeid:type:numberdescription:the id of a changeget:is:-bbget:{bbtype:change}/changesources:description:|This path selects all changesource.get:is:-bbget:{bbtype:changesource}/{changesourceid}:uriParameters:changesourceid:type:numberdescription:the id of a changesourcedescription:|This path selects one changesource given its id.get:is:-bbget:{bbtype:changesource}/forceschedulers:description:|This path selects all forceschedulers.get:is:-bbget:{bbtype:forcescheduler}/{schedulername}:description:|This path selects all changesource.uriParameters:schedulername:type:identifierdescription:the name of a schedulerget:is:-bbget:{bbtype:forcescheduler}/actions/force:post:description:|Triggers the forceschedulerbody:application/json:properties:owner:type:stringrequired:falsedescription:The user who wants to create the buildrequest'[]':description:content of the forcescheduler parameter is dependent on the configuration of the forcescheduler/logs/{logid}:uriParameters:logid:type:numberdescription:the id of the logdescription:This path selects one logget:is:-bbget:{bbtype:log}/contents:get:description:|This path selects chunks from a specific logis:-bbget:{bbtype:logchunk}/raw:get:description:|This path downloads the whole logis:-bbgetraw:/masters:description:This path selects all mastersget:is:-bbget:{bbtype:master}/{masterid}:description:This path selects one master given its iduriParameters:masterid:type:numberdescription:the id of the masterget:is:-bbget:{bbtype:master}/builders:description:This path selects all builders of a given masterget:is:-bbget:{bbtype:builder}/{builderid}:description:This path selects one builder by id of a given masteruriParameters:builderid:type:numberdescription:the id of the builderget:is:-bbget:{bbtype:builder}/workers:description:This path selects all workers for a given builder and a given masterget:is:-bbget:{bbtype:worker}/{name}:description:This path selects one workers by name for a given builder and a given masteruriParameters:name:type:identifierdescription:the name of the workerget:is:-bbget:{bbtype:worker}/{workerid}:description:This path selects one workers by name for a given builder and a given masteruriParameters:workerid:type:numberdescription:the id of the workerget:is:-bbget:{bbtype:worker}/workers:description:This path selects all workers for a given masterget:is:-bbget:{bbtype:worker}/{name}:description:This path selects one worker by name for a given masteruriParameters:name:type:identifierdescription:the name of the workerget:is:-bbget:{bbtype:worker}/{workerid}:description:This path selects one worker by id for a given masteruriParameters:workerid:type:numberdescription:the id of the workerget:is:-bbget:{bbtype:worker}/changesources:description:This path selects all changesources for a given masterget:is:-bbget:{bbtype:changesource}/{changesourceid}:description:This path selects one changesource by id for a given masterget:is:-bbget:{bbtype:changesource}/schedulers:description:This path selects all schedulers for a given masterget:is:-bbget:{bbtype:scheduler}/{schedulerid}:description:This path selects one scheduler by id for a given masteruriParameters:schedulerid:type:numberdescription:the id of the schedulerget:is:-bbget:{bbtype:scheduler}/schedulers:description:This path selects all schedulersget:is:-bbget:{bbtype:scheduler}/{schedulerid}:uriParameters:schedulerid:type:numberdescription:the id of the schedulerdescription:This path selects one scheduler by idget:is:-bbget:{bbtype:scheduler}/sourcestamps:description:This path selects all sourcestamps (can return lots of data!)get:is:-bbget:{bbtype:sourcestamp}/{ssid}:description:This path selects one sourcestamp by iduriParameters:ssid:type:numberdescription:the id of the sourcestampget:is:-bbget:{bbtype:sourcestamp}/changes:description:This path selects all changes associated to one sourcestampget:is:-bbget:{bbtype:change}/steps:/{stepid}:description:This path selects one step by iduriParameters:stepid:type:numberdescription:the id of the step/logs:description:This path selects all logs for the given step.get:is:-bbget:{bbtype:log}/{log_slug}:uriParameters:log_slug:type:identifierdescription:the slug name of the logget:description:|This path selects a specific log in the given step.is:-bbget:{bbtype:log}/contents:get:description:|This path selects chunks from a specific log in the given step.is:-bbget:{bbtype:logchunk}/raw:get:description:|This path downloads the whole logis:-bbgetraw: