Documentation Index
Fetch the complete documentation index at: https://mintlify.com/sourcegraph/docs/llms.txt
Use this file to discover all available pages before exploring further.
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
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
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
{"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 |
graphQLMaxFieldCount limit when working with large data sets.