Sourcegraph GraphQL debug API

The Sourcegraph GraphQL API is a debug API that can be used for Sourcegraph diagnostics and simple tooling.

Quickstart

There are two ways to authenticate with the Sourcegraph GraphQL API:

Access Tokens

Generate an access token for your Sourcegraph instance under Settings > Access tokens.

Then run this query to echo your username back:

BASH
curl -H 'Authorization: token YOUR_TOKEN'
-d '{"query": "query { currentUser { username } }"}'
https://sourcegraph.example.com/.api/graphql

OAuth Tokens

If you have an OAuth app configured with the user:all scope, you can use OAuth Bearer tokens:

BASH
curl -H 'Authorization: Bearer YOUR_OAUTH_TOKEN'
-d '{"query": "query { currentUser { username } }"}'
https://sourcegraph.example.com/.api/graphql

Both authentication methods will return a response like this:

JSON
{"data": {"currentUser": {"username": "YOUR_USERNAME"}}}

For automated scripts, CI/CD pipelines, and production integrations, use service accounts instead of personal access tokens. Service accounts are designed specifically for programmatic API access and provide better security and audit capabilities.

Documentation & tooling

API console and documentation

Sourcegraph includes a built-in API console that lets you write queries and view debug API documentation in your browser.

You can find the debug API console at any time by going to Settings, and then clicking Debug console from the left sidebar, or by visiting it directly at https://sourcegraph.example.com/debug/console.

If you have not yet set up a Sourcegraph server, you can also test out the API on the Sourcegraph.com debug console (which always uses the latest version of the API).

To access the documentation, click Docs on the right-hand side of the debug console page.

Sudo access tokens

Site admins may create access tokens with the special site-admin:sudo scope, which allows the holder to perform any action as any other user.

BASH
curl -H 'Authorization: token-sudo user="SUDO_TO_USERNAME",token="YOUR_TOKEN"'
-d '{"query": "query { currentUser { username } }"}'
https://sourcegraph.example.com/.api/graphql

This scope is useful when building Sourcegraph integrations with external services where the service needs to communicate with Sourcegraph and does not want to force each user to individually authenticate to Sourcegraph.

Using the API via the Sourcegraph CLI

A command line interface to Sourcegraph's API is available. Today, it is roughly the same as using the API via curl (see below), but it offers a few nice things:

• Allows you to easily compose queries from scripts, e.g. without worrying about escaping JSON input to curl properly.
• Reads your access token and Sourcegraph server endpoint from a config file (or env var).
• Pipe multi-line GraphQL queries into it easily.
• Get any API query written using the CLI as a curl command using the src api -get-curl flag.

To learn more, see sourcegraph/src-cli

Using the API via curl

The entire API can be used via curl (or any HTTP library), just the same as any other GraphQL API. For example:

BASH
curl -H 'Authorization: token YOUR_TOKEN'
-d '{"query":"query($query: String!) { search(query: $query) { results { matchCount } } }","variables":{"query":"Router"}}'
https://sourcegraph.com/.api/graphql

i.e. you just need to send the Authorization header and a JSON object like {"query": "my query string", "variables": {"var1": "val1"}}.

Cost Limits

To ensure system performance and stability, configurable GraphQL query cost limitations have been implemented. This feature is crucial for preventing resource exhaustion due to extensive or overly complex queries. The default configuration looks as follows, and can be modified in site configuration:

SHELL
  "rateLimits": {
    "graphQLMaxAliases": 500,
    "graphQLMaxDepth": 30,
    "graphQLMaxFieldCount": 500000
  },

GraphQLMaxDepth

• Default Value: 30
• Limits the maximum depth of nested objects in GraphQL queries, preventing deep queries that consume excessive resources.

GraphQLMaxFieldCount

• Default Value: 500,000
• Restricts the number of fields in a GraphQL response to avoid overly broad queries. Use pagination where available to manage large data sets effectively.

GraphQLMaxAliases

• Default Value: 500
• Sets a cap on the number of aliases in a single GraphQL query, mitigating the risk of resource-intensive queries due to excessive aliasing.

GraphqlMaxDuplicateFieldCount

• Default Value: 500
• Limits the number of duplicate fields in a GraphQL query to prevent queries with unnecessary duplication from consuming excessive resources.

GraphqlMaxUniqueFieldCount

• Default Value: 500
• Restricts the number of unique fields in a GraphQL query to prevent queries with unnecessary broadness from consuming excessive resources.