Deep Search API

Programmatic access to Sourcegraph's agentic code search capabilities.

The Deep Search API is available in Sourcegraph version 6.7+. This API allows you to programmatically create and manage Deep Search conversations.

The Deep Search API provides programmatic access to Sourcegraph's agentic code search capabilities. Use this API to integrate Deep Search into your development workflows, build custom tools, or automate code analysis tasks.

Authentication

All API requests require authentication using a Sourcegraph access token. You can generate an access token from your user settings.

BASH
# Set your access token
export SRC_ACCESS_TOKEN="your-token-here"

Base URL

All Deep Search API endpoints are prefixed with /.api/deepsearch/v1 and require the X-Requested-With header to identify the client:

BASH
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: token $SRC_ACCESS_TOKEN" \
  -H 'X-Requested-With: my-client 1.0.0'

The X-Requested-With header is required and should include your client name and version number.

Creating conversations

All Deep Search conversations are processed asynchronously. When you create a conversation, the API will return immediately with a conversation object containing the question in processing status.

Create a new Deep Search conversation by asking a question:

BASH
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: token $SRC_ACCESS_TOKEN" \
  -H 'X-Requested-With: my-client 1.0.0' \
  -d '{"question":"Does github.com/sourcegraph/sourcegraph have a README?"}'

The API returns a conversation object with the question initially in processing status:

JSON
{
  "id": 140,
  "questions": [
    {
      "id": 163,
      "conversation_id": 140,
      "question": "Does github.com/sourcegraph/sourcegraph have a README?",
      "created_at": "2025-09-24T08:14:06Z",
      "updated_at": "2025-09-24T08:14:06Z",
      "status": "processing",
      "turns": [
        {
          "reasoning": "Does github.com/sourcegraph/sourcegraph have a README?",
          "timestamp": 1758701646,
          "role": "user"
        }
      ],
      "stats": {
        "time_millis": 0,
        "tool_calls": 0,
        "total_input_tokens": 0,
        "cached_tokens": 0,
        "cache_creation_input_tokens": 0,
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "total_tokens": 0,
        "credits": 0
      },
      "suggested_followups": null
    }
  ],
  "created_at": "2025-09-24T08:14:06Z",
  "updated_at": "2025-09-24T08:14:06Z",
  "user_id": 1,
  "read_token": "caebeb05-7755-4f89-834f-e3ee4a6acb25",
  "share_url": "https://your-sourcegraph-instance.com/deepsearch/caebeb05-7755-4f89-834f-e3ee4a6acb25"
}

To get the completed answer, poll the conversation endpoint:

BASH
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140' \
  -H 'Accept: application/json' \
  -H "Authorization: token $SRC_ACCESS_TOKEN" \
  -H 'X-Requested-With: my-client 1.0.0'

Once processing is complete, the response will include the answer:

JSON
{
  "id": 140,
  "questions": [
    {
      "id": 163,
      "conversation_id": 140,
      "question": "Does github.com/sourcegraph/sourcegraph have a README?",
      "created_at": "2025-09-24T08:14:06Z",
      "updated_at": "2025-09-24T08:14:15Z",
      "status": "completed",
      "title": "GitHub README check",
      "answer": "Yes, [github.com/sourcegraph/sourcegraph](https://sourcegraph.test:3443/github.com/sourcegraph/sourcegraph) has a [README.md](https://sourcegraph.test:3443/github.com/sourcegraph/sourcegraph/-/blob/README.md) file in the root directory.",
      "sources": [
        {
          "type": "Repository",
          "link": "/github.com/sourcegraph/sourcegraph",
          "label": "github.com/sourcegraph/sourcegraph"
        }
      ],
      "stats": {
        "time_millis": 6369,
        "tool_calls": 1,
        "total_input_tokens": 13632,
        "cached_tokens": 12359,
        "cache_creation_input_tokens": 13625,
        "prompt_tokens": 11,
        "completion_tokens": 156,
        "total_tokens": 13694,
        "credits": 2
      },
      "suggested_followups": [
        "What information does the README.md file contain?",
        "Are there other important documentation files in the repository?"
      ]
    }
  ],
  "created_at": "2025-09-24T08:14:06Z",
  "updated_at": "2025-09-24T08:14:15Z",
  "user_id": 1,
  "read_token": "caebeb05-7755-4f89-834f-e3ee4a6acb25",
  "viewer": { "is_owner": true },
  "quota_usage": {
    "total_quota": 0,
    "quota_limit": -1,
    "reset_time": "2025-10-01T00:00:00Z"
  },
  "share_url": "https://sourcegraph.test:3443/deepsearch/caebeb05-7755-4f89-834f-e3ee4a6acb25"
}

Adding follow-up questions

Continue a conversation by adding follow-up questions:

BASH
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140/questions' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: token $SRC_ACCESS_TOKEN" \
  -H 'X-Requested-With: my-client 1.0.0' \
  -d '{"question":"What does the README file contain?"}'

Listing conversations

Get all your conversations with optional filtering:

BASH
# List all conversations
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \
  -H 'Accept: application/json' \
  -H "Authorization: token $SRC_ACCESS_TOKEN" \
  -H 'X-Requested-With: my-client 1.0.0'
 
# List with pagination and filtering
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1?page_first=10&sort=created_at' \
  -H 'Accept: application/json' \
  -H "Authorization: token $SRC_ACCESS_TOKEN" \
  -H 'X-Requested-With: my-client 1.0.0'

Available query parameters:

filter_id - Filter by conversation ID
filter_user_id - Filter by user ID
filter_read_token - Access conversations via read token (requires sharing to be enabled)
filter_is_starred - Filter by starred conversations (true or false)
page_first - Number of results per page
page_after - Pagination cursor
sort - Sort order: id, -id, created_at, -created_at, updated_at, -updated_at (default: -updated_at)

Managing conversations

Get a specific conversation:

BASH
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140' \
  -H 'Accept: application/json' \
  -H "Authorization: token $SRC_ACCESS_TOKEN" \
  -H 'X-Requested-With: my-client 1.0.0'

Delete a conversation:

BASH
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140' \
  -X DELETE \
  -H "Authorization: token $SRC_ACCESS_TOKEN" \
  -H 'X-Requested-With: my-client 1.0.0'

Cancel a processing question:

BASH
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140/questions/163/cancel' \
  -X POST \
  -H 'Accept: application/json' \
  -H "Authorization: token $SRC_ACCESS_TOKEN" \
  -H 'X-Requested-With: my-client 1.0.0'

Accessing conversations via read tokens

You can retrieve a conversation using its read token with the filter_read_token query parameter.

Each conversation includes a read_token field that allows accessing the conversation. The read token is also visible in the web client URL and in the share_url field. Note that you can only access other users' conversations via read tokens if sharing is enabled on your Sourcegraph instance.

BASH
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1?filter_read_token=5d9aa113-c511-4687-8b71-dbc2dd733c03' \
  -H 'Accept: application/json' \
  -H "Authorization: token $SRC_ACCESS_TOKEN" \
  -H 'X-Requested-With: my-client 1.0.0'

Response structure

Conversation object:

id - Unique conversation identifier
questions - Array of questions and answers
created_at/updated_at - Timestamps
user_id - Owner user ID
read_token - Token for sharing access
share_url - URL for sharing the conversation

Question object:

id - Unique question identifier
question - The original question text
status - Processing status: pending, processing, completed, failed
title - Generated title for the question
answer - The AI-generated answer (when completed)
sources - Array of sources used to generate the answer
suggested_followups - Suggested follow-up questions

Error handling

The API returns standard HTTP status codes with descriptive error messages:

200 - Success
202 - Accepted (for async requests)
400 - Bad Request
401 - Unauthorized
404 - Not Found
500 - Internal Server Error