Skip to main content
Sourcegraph exposes several APIs for building integrations, automating workflows, and connecting AI tools to your codebase.

REST API

A versioned, stable REST API introduced in Sourcegraph 7.0. Recommended for new integrations.

GraphQL API

A debug API for diagnostics and simple tooling. No backwards-compatibility guarantees.

Streaming search API

Consume search results as a real-time server-sent event stream. Used by the Sourcegraph UI.

MCP server

Connect AI agents and coding tools to Sourcegraph code search via the Model Context Protocol.

​
REST API

Starting in Sourcegraph 7.0, a versioned external REST API is available for building custom integrations. You can browse available operations and download the OpenAPI schema at /api-reference on your Sourcegraph instance (for example, https://sourcegraph.example.com/api-reference). Sourcegraph is committed to backwards compatibility for integrations built on this API, with migration assistance provided for any breaking changes.
The REST API is a work in progress. Capabilities are being ported over incrementally. If you need to build an integration that isn’t yet served by the REST API, contact [email protected].

​
Authentication

All Sourcegraph APIs use the same authentication methods.

​
Getting an access token

1

Open your user settings

Sign in to your Sourcegraph instance and click your avatar in the top-right corner. Select Settings.
2

Navigate to access tokens

In the left sidebar, click Access tokens.
3

Generate a new token

Click Generate new token, give it a descriptive name, select the required scopes, and click Generate token.
4

Copy the token

Copy the token immediately — it is only shown once. Store it in a secure location such as a secrets manager or environment variable.
For automated scripts, CI/CD pipelines, and production integrations, create a dedicated user account with the required permissions rather than using a personal access token. This provides better security and auditing.

​
Using your token

Pass your access token in the Authorization header on every request: 
curl -H "Authorization: token YOUR_TOKEN" \
  https://sourcegraph.example.com/.api/graphql
If you have an OAuth application configured with the user:all scope, you can use OAuth Bearer tokens instead: 
curl -H "Authorization: Bearer YOUR_OAUTH_TOKEN" \
  https://sourcegraph.example.com/.api/graphql
OAuth access tokens are short-lived. Check the expires_in field in the token response and refresh proactively using your refresh token before expiration.

​
Sudo tokens

Site admins can create access tokens with the site-admin:sudo scope, which allows performing actions as any user. This is useful for service integrations where individual users should not need to authenticate separately. 
curl -H 'Authorization: token-sudo user="USERNAME",token="YOUR_TOKEN"' \
  -d '{"query": "query { currentUser { username } }"}' \
  https://sourcegraph.example.com/.api/graphql

​
Base URL

Replace sourcegraph.example.com in all examples with your Sourcegraph instance URL. For Sourcegraph Cloud, use sourcegraph.com.
APIEndpoint
REST API referencehttps://sourcegraph.example.com/api-reference
GraphQL APIhttps://sourcegraph.example.com/.api/graphql
Streaming searchhttps://sourcegraph.example.com/.api/search/stream
MCP serverhttps://sourcegraph.example.com/.api/mcp

​
Choosing an API

Building a new integration?

Use the REST API. It has formal stability guarantees and backwards-compatibility commitments.

Consuming search results in real time?

Use the streaming search API. It’s how the Sourcegraph UI works and supports exhaustive searches over large result sets.

Connecting an AI agent or IDE?

Use the MCP server. It exposes Sourcegraph’s code search and navigation capabilities to any MCP-compatible AI tool.

Debugging or diagnostics?

Use the GraphQL API. It provides broad access to Sourcegraph data but without compatibility guarantees.

Build docs developers (and LLMs) love

Get started for freeTalk to us