<commit_before># API Differences Between REST and GraphQL

Buildkite provides both a [REST API](https://buildkite.com/docs/apis/rest-api) and [GraphQL API](/docs/apis/graphql-api), but there are some differences between the two. Some tasks can only be achieved using the REST API, or the GraphQL API. We recommend using a mixture of both when required.

{:toc}

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

* **ANNOTATIONS:** [retrieve and list annotations](/docs/apis/rest-api/annotations) on a build, but not create them (however, you can create the annotations using the [buildkite-agent annotate command](/docs/agent/v3/cli-pipeline) from within a job).
* **BUILDS:** set [`branch_configuration` and `github provider configuration`](/docs/pipelines/branch-configuration#step-level-branch-filtering) on pipelines.
* **BUILDS:** [get a build by ID](/docs/apis/rest-api/builds#get-a-build).
* **JOBS:** [get an output of job logs](/docs/apis/rest-api/jobs#get-a-jobs-log-output).
* **JOBS:** [retry data for jobs](/docs/apis/rest-api/jobs#retry-a-job).
* **META:** [get a list of IPs from which Buildkite sends webhooks](/docs/apis/rest-api/meta#get-meta-information).
* **PIPELINES:** [set provider properties](https://bk-docs-pr-1613.onrender.com/docs/apis/rest-api/pipelines#provider-settings-properties) `provider_settings` allow 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](/docs/apis/graphql/graphql-cookbook#get-a-list-of-agent-token-ids).
* **BUILDS:** [get all environment variables set on a build](/docs/apis/graphql/graphql-cookbook#get-all-environment-variables-set-on-a-build).
* **BUILDS:** [increase the next build number](/docs/apis/graphql/graphql-cookbook#increase-the-next-build-number).
* **BUILDS:** [retrieve, list, and create annotations on a build](/docs/apis/rest-api/annotations).<commit_msg>Update pages/apis/api_differences.md.erb<commit_after># API Differences Between REST and GraphQL

Buildkite provides both a [REST API](https://buildkite.com/docs/apis/rest-api) and [GraphQL API](/docs/apis/graphql-api), but there are some differences between the two. Some tasks can only be achieved using the REST API, or the GraphQL API. We recommend using a mixture of both when required.

{:toc}

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

* **ANNOTATIONS:** [retrieve and list annotations](/docs/apis/rest-api/annotations) on a build, but not create them (however, you can create the annotations using the [buildkite-agent annotate command](/docs/agent/v3/cli-pipeline) from within a job).
* **BUILDS:** set [`branch_configuration` and `github provider configuration`](/docs/pipelines/branch-configuration#step-level-branch-filtering) on pipelines.
* **BUILDS:** [get a build by ID](/docs/apis/rest-api/builds#get-a-build).
* **JOBS:** [get an output of job logs](/docs/apis/rest-api/jobs#get-a-jobs-log-output).
* **JOBS:** [retry data for jobs](/docs/apis/rest-api/jobs#retry-a-job).
* **META:** [get a list of IPs from which Buildkite sends webhooks](/docs/apis/rest-api/meta#get-meta-information).
* **PIPELINES:** [set provider properties](https://bk-docs-pr-1613.onrender.com/docs/apis/rest-api/pipelines#provider-settings-properties) `provider_settings` allow 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](/docs/apis/graphql/graphql-cookbook#get-a-list-of-agent-token-ids).
* **BUILDS:** [get all environment variables set on a build](/docs/apis/graphql/graphql-cookbook#get-all-environment-variables-set-on-a-build).
* **BUILDS:** [increase the next build number](/docs/apis/graphql/graphql-cookbook#increase-the-next-build-number).
* **BUILDS:** [create annotations on a build](/docs/apis/rest-api/annotations).
{'fraction_non_alphanumeric': 0.12644935462699627, 'fraction_numerical': 0.002187705097352877, 'mean_word_length': 5.0078843626806835, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2249550', 'n_tokens_mistral': 1409, 'n_tokens_neox': 1351, 'n_words': 463}