API differences between REST and GraphQL
Buildkite provides both a REST API and GraphQL API, but there are some differences between the two. Some tasks can only be achieved using the GraphQL API or the REST API. For example, REST API is a good choice for Organization-level tasks and it also allows using granular access permissions, while GraphQL is more comprehensive and often can help you achieve things a single user would want to do in the Buildkite UI. We recommend using a mixture of both when required.
The strengths of the GraphQL API are in complex data queries, and the strengths of the REST API are in creating and modifying records.
On this page, we've collected the known limitation where some API features are only available with either REST or GraphQL.
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.
- BUILDS Create annotations on a build.
- JOBS Get an output of job logs.
- JOBS Retry data for jobs.
- Get a list of IPs from which Buildkite sends webhooks.
-
PIPELINES Set provider properties
provider_settingsallow configuring how the pipeline is triggered based on the source code provider's events; available on pipeline for all the pipeline inputs on pipeline create.
Features only available in the GraphQL API
- AGENTS Get a list of agent token IDs (agent tokens are currently only available via GraphQL).
- BUILDS Get all environment variables set on a build.
- BUILDS Increase the next build number.
- BUILDS Get build info by ID.
- JOBS Get all jobs in a given queue for a given timeframe.
- JOBS Get all jobs in a particular concurrency group.
- JOBS list job events.
- JOBS Cancel a job.
- ORGANIZATIONS Remove users from an organization.
- ORGANIZATIONS Set up SSO.
- PIPELINES Get all the pipeline metrics from the dashboard from the API.
- PIPELINES Get the last build's creation date within every pipeline.
- PIPELINES Count the number of builds on a branch.
- PIPELINES Get the creation date of the most recent build in every pipeline.
- PIPELINES Filter results from pipeline listings.
- PIPELINES Create and manage pipeline schedules.
- USERS Invite a user into a specific team with a specific role and permissions set.
Known missing API features
These are known requested features that are currently missing from both REST and GraphQL APIs:
- NOTIFICATION SERVICES There is no API for managing notification services.
- USERS Display secondary user emails.