API differences between REST and GraphQL
Buildkite provides both a REST API and GraphQL API. The APIs overlap for common operations but differ in authentication, query capabilities, and specialized operations.
The REST API supports granular access token scopes and specialized management endpoints. The GraphQL API supports nested queries, aggregate connection counts, and operations that aren't exposed through the REST API. Use both APIs when a workflow spans capabilities from each list.
The following lists cover public capabilities without an equivalent operation in the other API. Differences in field names and request or response shapes aren't included.
Features only available in the REST API
- ACCESS TOKEN Granular access permissions.
- ACCESS TOKEN Display the information about the access token currently in use.
- ACCESS TOKEN Revoke the current access token.
- AGENTS Create remote desktop sessions and SSH sessions for jobs running on Buildkite hosted agents.
- AGENTS Manage agent images and cache volumes, list network ranges, and assign cluster maintainers.
- AGENTS List, create, update, and delete Buildkite secrets.
-
JOBS Get the
group_keyfield for jobs that belong to group steps. - JOBS Retrieve and delete job log output.
- JOBS Reprioritize a job.
- Get a list of IP addresses from which Buildkite sends webhooks.
- ORGANIZATIONS List custom and built-in emojis.
- ORGANIZATIONS Prevent non-administrators from creating API access tokens.
- ORGANIZATIONS Manage organization-level pipeline settings, including hosted agent remote access, public pipeline creation, advanced queue metrics, and build exports.
- ORGANIZATIONS Create and manage notification services.
- ORGANIZATIONS Create and manage Buildkite Package Registries, packages, and registry tokens.
- ORGANIZATIONS Use the Test Engine APIs to manage test suites, tests, quarantine states, and execution tags, and inspect test runs.
- ORGANIZATIONS Enable team-based permissions.
- PIPELINES Set source code provider settings when creating or updating a pipeline.
- PIPELINES Create and manage pipeline triggers, and inspect trigger deliveries and their requests.
Features only available in the GraphQL API
- AGENTS List, create, and revoke unclustered agent tokens.
- BUILDS Update the next build number for an existing pipeline.
- BUILDS Get build information directly by UUID.
- JOBS Search jobs across an organization by queue, cluster, creation or finish date, or concurrency group.
- JOBS List job events.
- JOBS Cancel a job.
- ORGANIZATIONS Resend an organization invitation.
- ORGANIZATIONS Revoke a specific API access token's access to an organization.
- ORGANIZATIONS Set up and manage SSO.
- ORGANIZATIONS Create and delete system banners.
- ORGANIZATIONS Enforce two-factor authentication for organization members.
- ORGANIZATIONS Assign Buildkite Package Registries to teams and update or remove those assignments.
- PIPELINES Get the speed, reliability, and builds per week metrics shown on the pipeline dashboard.
- PIPELINES Get the creation date of the most recent build in every pipeline in one request.
- PIPELINES Count the number of builds on a branch without retrieving every build.
- PIPELINES Get pipeline information directly by UUID.
- PIPELINES Filter pipeline listings by archived state, cluster, creation date, favorite status, tags, or team, and control their sort order.
- PIPELINES Favorite or unfavorite a pipeline.
- PIPELINES Delete a source code provider webhook or rotate a pipeline webhook URL.
- PIPELINES Update a rule.
Some capabilities depend on the Buildkite product, plan, or preview features enabled for your organization.