Skip to content

Commit d45b5bb

Browse files
janhartmanjanhartman
authored
Remove sync API for Deep Search (#1362)
## Test plan I've verified the examples provided are accurate.
1 parent a48678b commit d45b5bb

File tree

1 file changed

+95
-48
lines changed

1 file changed

+95
-48
lines changed

‎docs/deep-search/api.mdx‎

Lines changed: 95 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,7 @@ curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \
3838

3939
## Creating conversations
4040

41-
<Callout type="note">
42-
Synchronous API calls currently have a **1 minute timeout**. For complex questions that might take longer to process, request [asynchronous processing](#asynchronous-processing) instead.
43-
</Callout>
41+
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.
4442

4543
Create a new Deep Search conversation by asking a question:
4644

@@ -53,68 +51,117 @@ curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \
5351
-d '{"question":"Does github.com/sourcegraph/sourcegraph have a README?"}'
5452
```
5553

56-
The API returns a complete conversation object including the generated answer:
54+
The API returns a conversation object with the question initially in `processing` status:
5755

5856
```json
5957
{
60-
"id": 332,
61-
"questions": [
62-
{
63-
"id": 4978,
64-
"conversation_id": 332,
65-
"question": "Does github.com/sourcegraph/sourcegraph have a README?",
66-
"status": "completed",
67-
"title": "Check for README in sourcegraph/sourcegraph",
68-
"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.",
69-
"sources": [
70-
{
71-
"type": "Repository",
72-
"link": "/github.com/sourcegraph/sourcegraph",
73-
"label": "github.com/sourcegraph/sourcegraph"
74-
}
75-
],
76-
"suggested_followups": [
77-
"What is the purpose of the README.md file in the sourcegraph repository?"
78-
]
79-
}
80-
],
81-
"created_at": "2025-08-18T21:16:49Z",
82-
"updated_at": "2025-08-18T21:16:49Z",
83-
"user_id": 1,
84-
"read_token": "fb1f21bb-07e5-48ff-a4cf-77bd2502c8a8",
85-
"share_url": "https://your-sourcegraph-instance.com/deepsearch/fb1f21bb-07e5-48ff-a4cf-77bd2502c8a8"
58+
"id": 140,
59+
"questions": [
60+
{
61+
"id": 163,
62+
"conversation_id": 140,
63+
"question": "Does github.com/sourcegraph/sourcegraph have a README?",
64+
"created_at": "2025-09-24T08:14:06Z",
65+
"updated_at": "2025-09-24T08:14:06Z",
66+
"status": "processing",
67+
"turns": [
68+
{
69+
"reasoning": "Does github.com/sourcegraph/sourcegraph have a README?",
70+
"timestamp": 1758701646,
71+
"role": "user"
72+
}
73+
],
74+
"stats": {
75+
"time_millis": 0,
76+
"tool_calls": 0,
77+
"total_input_tokens": 0,
78+
"cached_tokens": 0,
79+
"cache_creation_input_tokens": 0,
80+
"prompt_tokens": 0,
81+
"completion_tokens": 0,
82+
"total_tokens": 0,
83+
"credits": 0
84+
},
85+
"suggested_followups": null
86+
}
87+
],
88+
"created_at": "2025-09-24T08:14:06Z",
89+
"updated_at": "2025-09-24T08:14:06Z",
90+
"user_id": 1,
91+
"read_token": "caebeb05-7755-4f89-834f-e3ee4a6acb25",
92+
"share_url": "https://your-sourcegraph-instance.com/deepsearch/caebeb05-7755-4f89-834f-e3ee4a6acb25"
8693
}
8794
```
8895

89-
## Asynchronous processing
90-
91-
For complex questions that might take longer to process, you can request asynchronous processing by adding the `Prefer: respond-async` header:
96+
To get the completed answer, poll the conversation endpoint:
9297

9398
```bash
94-
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \
99+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140' \
95100
-H 'Accept: application/json' \
96-
-H 'Content-Type: application/json' \
97101
-H "Authorization: token $SRC_ACCESS_TOKEN" \
98-
-H 'X-Requested-With: my-client 1.0.0' \
99-
-H 'Prefer: respond-async' \
100-
-d '{"question":"Analyze the authentication patterns across all our microservices"}'
102+
-H 'X-Requested-With: my-client 1.0.0'
101103
```
102104

103-
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:
105+
Once processing is complete, the response will include the answer:
104106

105-
```bash
106-
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/333' \
107-
-H 'Accept: application/json' \
108-
-H "Authorization: token $SRC_ACCESS_TOKEN" \
109-
-H 'X-Requested-With: my-client 1.0.0'
107+
```json
108+
{
109+
"id": 140,
110+
"questions": [
111+
{
112+
"id": 163,
113+
"conversation_id": 140,
114+
"question": "Does github.com/sourcegraph/sourcegraph have a README?",
115+
"created_at": "2025-09-24T08:14:06Z",
116+
"updated_at": "2025-09-24T08:14:15Z",
117+
"status": "completed",
118+
"title": "GitHub README check",
119+
"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.",
120+
"sources": [
121+
{
122+
"type": "Repository",
123+
"link": "/github.com/sourcegraph/sourcegraph",
124+
"label": "github.com/sourcegraph/sourcegraph"
125+
}
126+
],
127+
"stats": {
128+
"time_millis": 6369,
129+
"tool_calls": 1,
130+
"total_input_tokens": 13632,
131+
"cached_tokens": 12359,
132+
"cache_creation_input_tokens": 13625,
133+
"prompt_tokens": 11,
134+
"completion_tokens": 156,
135+
"total_tokens": 13694,
136+
"credits": 2
137+
},
138+
"suggested_followups": [
139+
"What information does the README.md file contain?",
140+
"Are there other important documentation files in the repository?"
141+
]
142+
}
143+
],
144+
"created_at": "2025-09-24T08:14:06Z",
145+
"updated_at": "2025-09-24T08:14:15Z",
146+
"user_id": 1,
147+
"read_token": "caebeb05-7755-4f89-834f-e3ee4a6acb25",
148+
"viewer": { "is_owner": true },
149+
"quota_usage": {
150+
"total_quota": 0,
151+
"quota_limit": -1,
152+
"reset_time": "2025-10-01T00:00:00Z"
153+
},
154+
"share_url": "https://sourcegraph.test:3443/deepsearch/caebeb05-7755-4f89-834f-e3ee4a6acb25"
155+
}
110156
```
111157

158+
112159
## Adding follow-up questions
113160

114161
Continue a conversation by adding follow-up questions:
115162

116163
```bash
117-
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/332/questions' \
164+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140/questions' \
118165
-H 'Accept: application/json' \
119166
-H 'Content-Type: application/json' \
120167
-H "Authorization: token $SRC_ACCESS_TOKEN" \
@@ -153,7 +200,7 @@ Available query parameters:
153200
**Get a specific conversation:**
154201

155202
```bash
156-
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/332' \
203+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140' \
157204
-H 'Accept: application/json' \
158205
-H "Authorization: token $SRC_ACCESS_TOKEN" \
159206
-H 'X-Requested-With: my-client 1.0.0'
@@ -162,7 +209,7 @@ curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/332' \
162209
**Delete a conversation:**
163210

164211
```bash
165-
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/332' \
212+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140' \
166213
-X DELETE \
167214
-H "Authorization: token $SRC_ACCESS_TOKEN" \
168215
-H 'X-Requested-With: my-client 1.0.0'
@@ -171,7 +218,7 @@ curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/332' \
171218
**Cancel a processing question:**
172219

173220
```bash
174-
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/332/questions/4978/cancel' \
221+
curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140/questions/163/cancel' \
175222
-X POST \
176223
-H 'Accept: application/json' \
177224
-H "Authorization: token $SRC_ACCESS_TOKEN" \

0 commit comments

Comments
 (0)