Skip to content

Commit 7116841

Browse files
jamesmcnamarajamesmcnamara
committed
formatting
1 parent a4fa203 commit 7116841

File tree

4 files changed

+5391
-6366
lines changed

4 files changed

+5391
-6366
lines changed

‎docs/deep-search/api.mdx‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# Deep Search API
2+
3+
<p className="subtitle">Programmatic access to Sourcegraph's agentic code search capabilities.</p>
4+
5+
<Callout type="note">
6+
The Deep Search API is available in Sourcegraph version 6.7+. This API
7+
allows you to programmatically create and manage Deep Search
8+
conversations.
9+
</Callout>
10+
11+
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.
12+
13+
## Authentication
14+
15+
All API requests require authentication using a Sourcegraph access token. You can generate an access token from your user settings.
16+
17+
```bash
18+
# Set your access token
19+
export SRC_ACCESS_TOKEN="your-token-here"
20+
```
21+
22+
## Base URL
23+
24+
All Deep Search API endpoints are prefixed with `/.api/deepsearch/v1` and require the `X-Requested-With` header to identify the client:
25+
26+
```bash
27+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \
28+
-H 'Accept: application/json' \
29+
-H 'Content-Type: application/json' \
30+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
31+
-H 'X-Requested-With: my-client 1.0.0'
32+
```
33+
34+
<Callout type="note">
35+
The `X-Requested-With` header is required and should include your client
36+
name and version number.
37+
</Callout>
38+
39+
## Creating conversations
40+
41+
Create a new Deep Search conversation by asking a question:
42+
43+
```bash
44+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \
45+
-H 'Accept: application/json' \
46+
-H 'Content-Type: application/json' \
47+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
48+
-H 'X-Requested-With: my-client 1.0.0' \
49+
-d '{"question":"Does github.com/sourcegraph/sourcegraph have a README?"}'
50+
```
51+
52+
The API returns a complete conversation object including the generated answer:
53+
54+
```json
55+
{
56+
"id": 332,
57+
"questions": [
58+
{
59+
"id": 4978,
60+
"conversation_id": 332,
61+
"question": "Does github.com/sourcegraph/sourcegraph have a README?",
62+
"status": "completed",
63+
"title": "Check for README in sourcegraph/sourcegraph",
64+
"answer": "Yes, [github.com/sourcegraph/sourcegraph](/github.com/sourcegraph/sourcegraph/) has a [README.md](/github.com/sourcegraph/sourcegraph/-/blob/README.md) file in the root directory.",
65+
"sources": [
66+
{
67+
"type": "Repository",
68+
"link": "/github.com/sourcegraph/sourcegraph",
69+
"label": "github.com/sourcegraph/sourcegraph"
70+
}
71+
],
72+
"suggested_followups": [
73+
"What is the purpose of the README.md file in the sourcegraph repository?"
74+
]
75+
}
76+
],
77+
"created_at": "2025-08-18T21:16:49Z",
78+
"updated_at": "2025-08-18T21:16:49Z",
79+
"user_id": 1,
80+
"read_token": "fb1f21bb-07e5-48ff-a4cf-77bd2502c8a8",
81+
"share_url": "https://your-sourcegraph-instance.com/deepsearch/fb1f21bb-07e5-48ff-a4cf-77bd2502c8a8"
82+
}
83+
```
84+
85+
## Asynchronous processing
86+
87+
For complex questions that might take longer to process, you can request asynchronous processing by adding the `Prefer: respond-async` header:
88+
89+
```bash
90+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \
91+
-H 'Accept: application/json' \
92+
-H 'Content-Type: application/json' \
93+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
94+
-H 'X-Requested-With: my-client 1.0.0' \
95+
-H 'Prefer: respond-async' \
96+
-d '{"question":"Analyze the authentication patterns across all our microservices"}'
97+
```
98+
99+
This returns a `202 Accepted` status with the conversation object showing a `processing` status. You can then poll the conversation endpoint to check for completion:
100+
101+
```bash
102+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/333' \
103+
-H 'Accept: application/json' \
104+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
105+
-H 'X-Requested-With: my-client 1.0.0'
106+
```
107+
108+
## Adding follow-up questions
109+
110+
Continue a conversation by adding follow-up questions:
111+
112+
```bash
113+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/332/questions' \
114+
-H 'Accept: application/json' \
115+
-H 'Content-Type: application/json' \
116+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
117+
-H 'X-Requested-With: my-client 1.0.0' \
118+
-d '{"question":"What does the README file contain?"}'
119+
```
120+
121+
## Listing conversations
122+
123+
Get all your conversations with optional filtering:
124+
125+
```bash
126+
# List all conversations
127+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \
128+
-H 'Accept: application/json' \
129+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
130+
-H 'X-Requested-With: my-client 1.0.0'
131+
132+
# List with pagination and filtering
133+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1?page_first=10&sort=created_at' \
134+
-H 'Accept: application/json' \
135+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
136+
-H 'X-Requested-With: my-client 1.0.0'
137+
```
138+
139+
Available query parameters:
140+
141+
- `filter_id` - Filter by conversation ID
142+
- `filter_user_id` - Filter by user ID
143+
- `page_first` - Number of results per page
144+
- `page_after` - Pagination cursor
145+
- `sort` - Sort order: `created_at`, `-created_at`, `updated_at`, `-updated_at`
146+
147+
## Managing conversations
148+
149+
**Get a specific conversation:**
150+
151+
```bash
152+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/332' \
153+
-H 'Accept: application/json' \
154+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
155+
-H 'X-Requested-With: my-client 1.0.0'
156+
```
157+
158+
**Delete a conversation:**
159+
160+
```bash
161+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/332' \
162+
-X DELETE \
163+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
164+
-H 'X-Requested-With: my-client 1.0.0'
165+
```
166+
167+
**Cancel a processing question:**
168+
169+
```bash
170+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/332/questions/4978/cancel' \
171+
-X POST \
172+
-H 'Accept: application/json' \
173+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
174+
-H 'X-Requested-With: my-client 1.0.0'
175+
```
176+
177+
## Response structure
178+
179+
**Conversation object:**
180+
181+
- `id` - Unique conversation identifier
182+
- `questions` - Array of questions and answers
183+
- `created_at`/`updated_at` - Timestamps
184+
- `user_id` - Owner user ID
185+
- `read_token` - Token for sharing access
186+
- `share_url` - URL for sharing the conversation
187+
188+
**Question object:**
189+
190+
- `id` - Unique question identifier
191+
- `question` - The original question text
192+
- `status` - Processing status: `pending`, `processing`, `completed`, `failed`
193+
- `title` - Generated title for the question
194+
- `answer` - The AI-generated answer (when completed)
195+
- `sources` - Array of sources used to generate the answer
196+
- `suggested_followups` - Suggested follow-up questions
197+
198+
## Error handling
199+
200+
The API returns standard HTTP status codes with descriptive error messages:
201+
202+
- `200` - Success
203+
- `202` - Accepted (for async requests)
204+
- `400` - Bad Request
205+
- `401` - Unauthorized
206+
- `404` - Not Found
207+
- `500` - Internal Server Error

‎docs/deep-search/index.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,3 +63,7 @@ Conversation sharing is disabled by default. To enable conversation sharing, ask
6363

6464
### Custom model configuration and BYOK (Bring Your Own Key)
6565
Deep Search is only available to customers using Sourcegraph’s built-in model gateway. Customers who configure and access their own models via BYOK cannot use the Deep Search feature.
66+
67+
## API access
68+
69+
For programmatic access to Deep Search functionality, see the [Deep Search API documentation](/deep-search/api).

0 commit comments

Comments
 (0)