# Sourcegraph GraphQL debug API

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

<Callout type="warning">
	The GraphQL API is intended primarily for debugging use cases. It does not
	have backwards-compatibility guarantees, and may not remain stable across
	Sourcegraph releases. For more information, please refer to the [Sourcegraph
	API page](/api).
</Callout>

<Callout type="note">
	For code search integrations, we currently recommend using the [stream
	search API](/api/stream-api/).
</Callout>

## 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](/admin/oauth-apps) 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"}}}
```

<Callout type="note">
	OAuth access tokens are always short-lived and must be refreshed using
	refresh tokens before expiration. Check the `expires_in` field and refresh
	proactively.
</Callout>

For automated scripts, CI/CD pipelines, and production integrations, use [service accounts](/admin/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](https://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](https://sourcegraph.com/github.com/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:

```
  "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.