GraphQL API

The Sourcegraph GraphQL API provides broad access to data stored and computed by your Sourcegraph instance. It is primarily intended for diagnostics and simple tooling.

The GraphQL API is an internal interface without formal backwards-compatibility guarantees. It may change across Sourcegraph releases. For external integrations, use the REST API introduced in Sourcegraph 7.0. If your use case is not yet covered by the REST API, contact support@sourcegraph.com.

For code search integrations, use the streaming search API instead. It is purpose-built for consuming search results and is the same API used by the Sourcegraph UI.

Endpoint

POST https://sourcegraph.example.com/.api/graphql

Send requests as JSON with a query field (the GraphQL query string) and an optional variables field.

Authentication

Access token
OAuth token
Sudo token

Generate a personal access token under Settings > Access tokens, then pass it in the Authorization header:

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

If you have an OAuth application configured with the user:all scope, use a Bearer token:

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

OAuth access tokens are short-lived. Refresh them proactively using your refresh token before the expires_in deadline.

Site admins can use the site-admin:sudo scope to act as any user. This is useful for service integrations where users should not need to authenticate individually:

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

A successful authentication check returns:

{"data": {"currentUser": {"username": "your-username"}}}

Example queries

Verify authentication

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

Search for code

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

Look up a repository

curl -H "Authorization: token YOUR_TOKEN" \
  -d '{
    "query": "query { repository(name: \"github.com/sourcegraph/sourcegraph\") { name description defaultBranch { name } } }"
  }' \
  https://sourcegraph.example.com/.api/graphql

Read a file

curl -H "Authorization: token YOUR_TOKEN" \
  -d '{
    "query": "query { repository(name: \"github.com/sourcegraph/sourcegraph\") { commit(rev: \"HEAD\") { file(path: \"README.md\") { content } } } }"
  }' \
  https://sourcegraph.example.com/.api/graphql

API console

Sourcegraph ships with a built-in API console where you can write queries and browse the schema interactively.

Navigate to Settings > Debug console in your Sourcegraph instance, or visit https://sourcegraph.example.com/debug/console directly.
Click Docs on the right side of the console to browse the schema documentation.
You can also use the Sourcegraph.com debug console to test against the latest API version.

Sourcegraph CLI

The src-cli provides a command-line interface to the GraphQL API. It reads your access token and instance URL from a config file or environment variables, handles JSON escaping, and lets you pipe multi-line queries easily.

# Get a curl equivalent for any query
src api -get-curl -query 'query { currentUser { username } }'

Query cost limits

To protect system stability, Sourcegraph enforces limits on GraphQL query complexity. These defaults can be adjusted in site configuration under rateLimits.

Setting	Default	Description
`graphQLMaxDepth`	30	Maximum nesting depth of objects in a query
`graphQLMaxFieldCount`	500,000	Maximum number of fields in a response
`graphQLMaxAliases`	500	Maximum number of aliases in a single query
`graphqlMaxDuplicateFieldCount`	500	Maximum duplicate fields in a query
`graphqlMaxUniqueFieldCount`	500	Maximum unique fields in a query

Use pagination where available to stay within the graphQLMaxFieldCount limit when working with large data sets.

Administration

Integrations & API

Endpoint

Authentication

Example queries

Verify authentication

Search for code

Look up a repository

Read a file

API console

Sourcegraph CLI

Query cost limits

​Endpoint

​Authentication

​Example queries

​Verify authentication

​Search for code

​Look up a repository

​Read a file

​API console

​Sourcegraph CLI

​Query cost limits

Endpoint

Authentication

Example queries

Verify authentication

Search for code

Look up a repository

Read a file

API console

Sourcegraph CLI

Query cost limits