Skip to content

Commit 109e190

Browse files
bobheadxibobheadxi
authored
deepsearch: bring back legacy API page (#1642)
Customer is asking for it and in hindsight, better to have it and add a big warning than delete it so fast, oops
1 parent be71dfb commit 109e190

2 files changed

Lines changed: 300 additions & 5 deletions

File tree

‎docs/deep-search/api.mdx‎

Lines changed: 300 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,300 @@
1+
---
2+
preview: true
3+
---
4+
5+
# Deep Search API
6+
7+
<Callout type="warning">
8+
<p>
9+
The **experimental** Deep Search API has been **deprecated** as of
10+
Sourcegraph 7.0. In Sourcegraph 7.0, [a new versioned Sourcegraph API is
11+
being introduced for custom
12+
integrations](https://sourcegraph.com/changelog/sourcegraph-api),
13+
available at `/api-reference` (e.g.
14+
`https://sourcegraph.example.com/api-reference`). This experimental Deep
15+
Search API remains available, but we recommend migrating to the new API
16+
for a stable integration experience. If you need migration assistance,
17+
please reach out at support@sourcegraph.com.
18+
</p>
19+
<p>Learn more about the Sourcegraph API [here](/api).</p>
20+
</Callout>
21+
22+
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.
23+
24+
## Authentication
25+
26+
All API requests require authentication using a Sourcegraph access token. You can generate an access token from your user settings.
27+
28+
```bash
29+
# Set your access token
30+
export SRC_ACCESS_TOKEN="your-token-here"
31+
```
32+
33+
## Base URL
34+
35+
All Deep Search API endpoints are prefixed with `/.api/deepsearch/v1` and require the `X-Requested-With` header to identify the client:
36+
37+
```bash
38+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \
39+
-H 'Accept: application/json' \
40+
-H 'Content-Type: application/json' \
41+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
42+
-H 'X-Requested-With: my-client 1.0.0'
43+
```
44+
45+
<Callout type="note">
46+
The `X-Requested-With` header is required and should include your client
47+
name and version number.
48+
</Callout>
49+
50+
## Creating conversations
51+
52+
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.
53+
54+
Create a new Deep Search conversation by asking a question:
55+
56+
```bash
57+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \
58+
-H 'Accept: application/json' \
59+
-H 'Content-Type: application/json' \
60+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
61+
-H 'X-Requested-With: my-client 1.0.0' \
62+
-d '{"question":"Does github.com/sourcegraph/sourcegraph have a README?"}'
63+
```
64+
65+
The API returns a conversation object with the question initially in `processing` status:
66+
67+
```json
68+
{
69+
"id": 140,
70+
"questions": [
71+
{
72+
"id": 163,
73+
"conversation_id": 140,
74+
"question": "Does github.com/sourcegraph/sourcegraph have a README?",
75+
"created_at": "2025-09-24T08:14:06Z",
76+
"updated_at": "2025-09-24T08:14:06Z",
77+
"status": "processing",
78+
"turns": [
79+
{
80+
"reasoning": "Does github.com/sourcegraph/sourcegraph have a README?",
81+
"timestamp": 1758701646,
82+
"role": "user"
83+
}
84+
],
85+
"stats": {
86+
"time_millis": 0,
87+
"tool_calls": 0,
88+
"total_input_tokens": 0,
89+
"cached_tokens": 0,
90+
"cache_creation_input_tokens": 0,
91+
"prompt_tokens": 0,
92+
"completion_tokens": 0,
93+
"total_tokens": 0,
94+
"credits": 0
95+
},
96+
"suggested_followups": null
97+
}
98+
],
99+
"created_at": "2025-09-24T08:14:06Z",
100+
"updated_at": "2025-09-24T08:14:06Z",
101+
"user_id": 1,
102+
"read_token": "caebeb05-7755-4f89-834f-e3ee4a6acb25",
103+
"share_url": "https://your-sourcegraph-instance.com/deepsearch/caebeb05-7755-4f89-834f-e3ee4a6acb25"
104+
}
105+
```
106+
107+
To get the completed answer, poll the conversation endpoint:
108+
109+
```bash
110+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140' \
111+
-H 'Accept: application/json' \
112+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
113+
-H 'X-Requested-With: my-client 1.0.0'
114+
```
115+
116+
Once processing is complete, the response will include the answer:
117+
118+
```json
119+
{
120+
"id": 140,
121+
"questions": [
122+
{
123+
"id": 163,
124+
"conversation_id": 140,
125+
"question": "Does github.com/sourcegraph/sourcegraph have a README?",
126+
"created_at": "2025-09-24T08:14:06Z",
127+
"updated_at": "2025-09-24T08:14:15Z",
128+
"status": "completed",
129+
"title": "GitHub README check",
130+
"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.",
131+
"sources": [
132+
{
133+
"type": "Repository",
134+
"link": "/github.com/sourcegraph/sourcegraph",
135+
"label": "github.com/sourcegraph/sourcegraph"
136+
}
137+
],
138+
"stats": {
139+
"time_millis": 6369,
140+
"tool_calls": 1,
141+
"total_input_tokens": 13632,
142+
"cached_tokens": 12359,
143+
"cache_creation_input_tokens": 13625,
144+
"prompt_tokens": 11,
145+
"completion_tokens": 156,
146+
"total_tokens": 13694,
147+
"credits": 2
148+
},
149+
"suggested_followups": [
150+
"What information does the README.md file contain?",
151+
"Are there other important documentation files in the repository?"
152+
]
153+
}
154+
],
155+
"created_at": "2025-09-24T08:14:06Z",
156+
"updated_at": "2025-09-24T08:14:15Z",
157+
"user_id": 1,
158+
"read_token": "caebeb05-7755-4f89-834f-e3ee4a6acb25",
159+
"viewer": {"is_owner": true},
160+
"quota_usage": {
161+
"total_quota": 0,
162+
"quota_limit": -1,
163+
"reset_time": "2025-10-01T00:00:00Z"
164+
},
165+
"share_url": "https://sourcegraph.test:3443/deepsearch/caebeb05-7755-4f89-834f-e3ee4a6acb25"
166+
}
167+
```
168+
169+
## Adding follow-up questions
170+
171+
Continue a conversation by adding follow-up questions. The `conversation_id` in the request body must match the conversation ID in the URL:
172+
173+
```bash
174+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140/questions' \
175+
-H 'Accept: application/json' \
176+
-H 'Content-Type: application/json' \
177+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
178+
-H 'X-Requested-With: my-client 1.0.0' \
179+
-d '{"conversation_id":140,"question":"What does the README file contain?"}'
180+
```
181+
182+
## Listing conversations
183+
184+
Get all your conversations with optional filtering:
185+
186+
```bash
187+
# List all conversations
188+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \
189+
-H 'Accept: application/json' \
190+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
191+
-H 'X-Requested-With: my-client 1.0.0'
192+
193+
# List with pagination and filtering
194+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1?page_first=10&sort=created_at' \
195+
-H 'Accept: application/json' \
196+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
197+
-H 'X-Requested-With: my-client 1.0.0'
198+
```
199+
200+
Available query parameters:
201+
202+
- `filter_id` - Filter by conversation ID
203+
- `filter_user_id` - Filter by user ID
204+
- `filter_read_token` - Access conversations via read token (requires sharing to be enabled)
205+
- `filter_is_starred` - Filter by starred conversations (`true` or `false`)
206+
- `page_first` - Number of results per page
207+
- `page_after` - Pagination cursor
208+
- `sort` - Sort order: `id`, `-id`, `created_at`, `-created_at`, `updated_at`, `-updated_at` (default: `-updated_at`)
209+
210+
## Managing conversations
211+
212+
**Get a specific conversation:**
213+
214+
```bash
215+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140' \
216+
-H 'Accept: application/json' \
217+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
218+
-H 'X-Requested-With: my-client 1.0.0'
219+
```
220+
221+
**Delete a conversation:**
222+
223+
```bash
224+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140' \
225+
-X DELETE \
226+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
227+
-H 'X-Requested-With: my-client 1.0.0'
228+
```
229+
230+
**Cancel a processing question:**
231+
232+
```bash
233+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140/questions/163/cancel' \
234+
-X POST \
235+
-H 'Accept: application/json' \
236+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
237+
-H 'X-Requested-With: my-client 1.0.0'
238+
```
239+
240+
## Accessing conversations via read tokens
241+
242+
You can retrieve a conversation using its read token with the `filter_read_token` query parameter.
243+
244+
Each conversation includes a `read_token` field that allows accessing the conversation.
245+
The read token is also visible in the web client URL and in the `share_url` field.
246+
Note that you can only access other users' conversations via read tokens if sharing is enabled on your Sourcegraph instance.
247+
248+
```bash
249+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1?filter_read_token=5d9aa113-c511-4687-8b71-dbc2dd733c03' \
250+
-H 'Accept: application/json' \
251+
-H "Authorization: token $SRC_ACCESS_TOKEN" \
252+
-H 'X-Requested-With: my-client 1.0.0'
253+
```
254+
255+
## Response structure
256+
257+
**Conversation object:**
258+
259+
- `id` - Unique conversation identifier
260+
- `questions` - Array of questions and answers
261+
- `created_at`/`updated_at` - Timestamps
262+
- `user_id` - Owner user ID
263+
- `read_token` - Token for sharing access
264+
- `share_url` - URL for sharing the conversation
265+
266+
**Question object:**
267+
268+
- `id` - Unique question identifier
269+
- `question` - The original question text
270+
- `status` - Processing status: `pending`, `processing`, `completed`
271+
- `error` - Error details if the question processing encountered an issue
272+
- `title` - Generated title for the question
273+
- `answer` - The AI-generated answer (when completed)
274+
- `sources` - Array of sources used to generate the answer
275+
- `suggested_followups` - Suggested follow-up questions
276+
277+
If a question fails to process, the `status` will be `completed` and the `error` field will be populated, for example:
278+
279+
```json
280+
{
281+
"status": "completed",
282+
"error": {
283+
"title": "Token limit reached",
284+
"kind": "TokenLimitExceeded",
285+
"message": "The search exceeded the maximum token limit...",
286+
"details": "Additional context about the error"
287+
}
288+
}
289+
```
290+
291+
## Error handling
292+
293+
The API returns standard HTTP status codes with descriptive error messages:
294+
295+
- `200` - Success
296+
- `202` - Accepted (for async requests)
297+
- `400` - Bad Request
298+
- `401` - Unauthorized
299+
- `404` - Not Found
300+
- `500` - Internal Server Error

‎src/data/redirects.ts‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7149,11 +7149,6 @@ const redirectsData = [
71497149
destination: '/api',
71507150
permanent: true
71517151
},
7152-
{
7153-
source: '/deep-search/api',
7154-
destination: '/api',
7155-
permanent: true
7156-
}
71577152
];
71587153

71597154
const updatedRedirectsData = redirectsData.map(redirect => {

0 commit comments

Comments
 (0)