From c7c808ad3a82b79e5557b4eb8106bcff172eace7 Mon Sep 17 00:00:00 2001 From: julialeex Date: Wed, 25 Feb 2026 23:56:34 -0500 Subject: [PATCH 01/12] doc update --- docs/api/index.mdx | 6 +- docs/api/migration/index.mdx | 330 +++++++++++++++++++++++++++++++++++ 2 files changed, 334 insertions(+), 2 deletions(-) create mode 100644 docs/api/migration/index.mdx diff --git a/docs/api/index.mdx b/docs/api/index.mdx index ddf8b2742..124a4a488 100644 --- a/docs/api/index.mdx +++ b/docs/api/index.mdx @@ -5,10 +5,12 @@ Starting in [Sourcegraph 7.0, a new versioned external API is being introduced f The new Sourcegraph API is a work in progress, and capabilities are gradually being ported over. If you have an integration you'd like to build - that is not currently served by the new Sourcegraph API, please reach out at - support@sourcegraph.com. + that is not currently served by the new Sourcegraph API, or migrate to the new Sourcegraph API, you can learn more about it in [our migration guide](/api/migration/). Please reach out at + support@sourcegraph.com if you need more help. +If you're migrating from the experimental Deep Search API or GraphQL API, see [Upgrading to the Sourcegraph /api/ endpoints](/api/migration/). + For specific types of integrations, Sourcegraph also offers the following APIs: - [Sourcegraph streaming search API](/api/stream-api/), for consuming search results as a stream of events diff --git a/docs/api/migration/index.mdx b/docs/api/migration/index.mdx new file mode 100644 index 000000000..2c9e897ac --- /dev/null +++ b/docs/api/migration/index.mdx @@ -0,0 +1,330 @@ +# Upgrading to the new Sourcegraph API + +Starting in Sourcegraph 7.0, Sourcegraph introduces a new, versioned API at `/api/`. **The new API provides stable, supported endpoints** for functionality previously served by the experimental Deep Search API (`/.api/deepsearch/v1`) and the GraphQL API (`/.api/graphql`). + +Two services are available today: + +- **`deepsearch.v1.Service`** — replaces the experimental `/.api/deepsearch/v1` endpoints (create conversations, poll for results, manage follow-ups) +- **`users.v1.Service`** — replaces GraphQL user queries and mutations (get, list, update, delete users) + +Additional services for code search, repositories, git metadata, Batch Changes, and other functionality will be introduced over time. + +An interactive API reference is available at `/api-reference` on your Sourcegraph instance (e.g. `https://sourcegraph.example.com/api-reference`), where you can view all operations and download the OpenAPI schema. + +## What changed + +1. **Protocol**: REST / GraphQL → [ConnectRPC](https://connectrpc.com/) (always POST with JSON) +2. **Base URL**: `/.api/deepsearch/v1/...` and `/.api/graphql` → `/api/{service}/...` +3. **Auth header**: `Authorization: token ` → `Authorization: Bearer ` +4. **Token scopes**: Any access token → token with `externalapi:read` / `externalapi:write` scope +5. **`X-Requested-With` header**: No longer required +6. **Resource identifiers**: Numeric IDs (`140`) → resource names (`users/-/conversations/140`) +7. **Status field** (Deep Search): `status: "processing"` → `state: "STATE_PROCESSING"` + +## Why migrate + +- **Stability guarantees** — the new API is versioned with backwards compatibility commitments +- **Interactive documentation** — explore and test at `/api-reference` +- **OpenAPI schema** — generate typed clients in any language +- **Scoped tokens** — finer-grained access control with `externalapi:read` / `externalapi:write` + +## Endpoint mapping + +### Deep Search (`/.api/deepsearch/v1` → `deepsearch.v1.Service`) + +| Operation | Old endpoint | New endpoint | +|---|---|---| +| Create conversation | `POST /.api/deepsearch/v1` | `POST /api/deepsearch.v1.Service/CreateConversation` | +| Get conversation | `GET /.api/deepsearch/v1/{id}` | `POST /api/deepsearch.v1.Service/GetConversation` | +| List conversations | `GET /.api/deepsearch/v1` | `POST /api/deepsearch.v1.Service/ListConversationSummaries` | +| Add follow-up | `POST /.api/deepsearch/v1/{id}/questions` | `POST /api/deepsearch.v1.Service/AddConversationQuestion` | +| Cancel question | `POST /.api/deepsearch/v1/{id}/questions/{qid}/cancel` | `POST /api/deepsearch.v1.Service/CancelConversation` | +| Delete conversation | `DELETE /.api/deepsearch/v1/{id}` | `POST /api/deepsearch.v1.Service/DeleteConversation` | + +### User management (`/.api/graphql` → `users.v1.Service`) + +| Operation | GraphQL | New endpoint | +|---|---|---| +| Get user | `query { user(username: "alice") { ... } }` | `POST /api/users.v1.Service/GetUser` | +| List users | `query { users { nodes { ... } } }` | `POST /api/users.v1.Service/ListUsers` | +| Update user | `mutation { updateUser(...) { ... } }` | `POST /api/users.v1.Service/UpdateUser` | +| Delete users | `mutation { deleteUser(...) { ... } }` | `POST /api/users.v1.Service/BatchDeleteUsers` | +| Undelete users | *(not available in GraphQL)* | `POST /api/users.v1.Service/BatchUndeleteUsers` | + +## Migration by example (Python) + +### Deep Search: Create a conversation + +**Before:** + +```python +import requests + +resp = requests.post( + "https://sourcegraph.example.com/.api/deepsearch/v1", + headers={ + "Authorization": f"token {TOKEN}", + "X-Requested-With": "my-client 1.0.0", + }, + json={"question": "Does the repo have a README?"}, +) +conversation = resp.json() +conversation_id = conversation["id"] +``` + +**After:** + +```python +import requests + +resp = requests.post( + "https://sourcegraph.example.com/api/deepsearch.v1.Service/CreateConversation", + headers={ + "Authorization": f"Bearer {TOKEN}", + "Content-Type": "application/json", + }, + json={"question": "Does the repo have a README?"}, +) +conversation = resp.json() +conversation_name = conversation["name"] # e.g. "users/1/conversations/140" +``` + +**With curl:** + +```bash +# Before +curl 'https://sourcegraph.example.com/.api/deepsearch/v1' \ + -H "Authorization: token $TOKEN" \ + -H 'X-Requested-With: my-client 1.0.0' \ + -H 'Content-Type: application/json' \ + -d '{"question":"Does the repo have a README?"}' + +# After +curl 'https://sourcegraph.example.com/api/deepsearch.v1.Service/CreateConversation' \ + -H "Authorization: Bearer $TOKEN" \ + -H 'Content-Type: application/json' \ + -d '{"question":"Does the repo have a README?"}' +``` + +### Deep Search: Poll for the result + +The polling workflow is the same — keep calling until the status indicates completion. The only changes are the URL, method, and status field name. + +**Before:** + +```python +import time + +while True: + resp = requests.get( + f"https://sourcegraph.example.com/.api/deepsearch/v1/{conversation_id}", + headers={ + "Authorization": f"token {TOKEN}", + "X-Requested-With": "my-client 1.0.0", + }, + ) + data = resp.json() + if data["questions"][0]["status"] == "completed": + print(data["questions"][0]["answer"]) + break + time.sleep(2) +``` + +**After:** + +```python +import time + +while True: + resp = requests.post( + "https://sourcegraph.example.com/api/deepsearch.v1.Service/GetConversation", + headers={ + "Authorization": f"Bearer {TOKEN}", + "Content-Type": "application/json", + }, + json={"name": conversation_name}, + ) + data = resp.json() + if data["state"] == "STATE_COMPLETED": + print(data["questions"][0]["answer"]) + break + time.sleep(2) +``` + +### Deep Search: Add a follow-up question + +**Before:** + +```python +resp = requests.post( + f"https://sourcegraph.example.com/.api/deepsearch/v1/{conversation_id}/questions", + headers={ + "Authorization": f"token {TOKEN}", + "X-Requested-With": "my-client 1.0.0", + }, + json={ + "conversation_id": conversation_id, + "question": "What does the README contain?", + }, +) +``` + +**After:** + +```python +resp = requests.post( + "https://sourcegraph.example.com/api/deepsearch.v1.Service/AddConversationQuestion", + headers={ + "Authorization": f"Bearer {TOKEN}", + "Content-Type": "application/json", + }, + json={ + "parent": conversation_name, + "question": "What does the README contain?", + }, +) +``` + +### User management: Get a user + +**Before (GraphQL):** + +```python +import requests + +resp = requests.post( + "https://sourcegraph.example.com/.api/graphql", + headers={ + "Authorization": f"token {TOKEN}", + }, + json={ + "query": 'query { user(username: "alice") { id username displayName } }', + }, +) +user = resp.json()["data"]["user"] +``` + +**After:** + +```python +import requests + +resp = requests.post( + "https://sourcegraph.example.com/api/users.v1.Service/GetUser", + headers={ + "Authorization": f"Bearer {TOKEN}", + "Content-Type": "application/json", + }, + json={"name": "users/alice"}, +) +user = resp.json() +``` + +**With curl:** + +```bash +# Before (GraphQL) +curl 'https://sourcegraph.example.com/.api/graphql' \ + -H "Authorization: token $TOKEN" \ + -H 'Content-Type: application/json' \ + -d '{"query":"query { user(username: \"alice\") { id username displayName } }"}' + +# After +curl 'https://sourcegraph.example.com/api/users.v1.Service/GetUser' \ + -H "Authorization: Bearer $TOKEN" \ + -H 'Content-Type: application/json' \ + -d '{"name":"users/alice"}' +``` + +### User management: List users + +**Before (GraphQL):** + +```python +resp = requests.post( + "https://sourcegraph.example.com/.api/graphql", + headers={ + "Authorization": f"token {TOKEN}", + }, + json={ + "query": "query { users { nodes { id username displayName } } }", + }, +) +users = resp.json()["data"]["users"]["nodes"] +``` + +**After:** + +```python +resp = requests.post( + "https://sourcegraph.example.com/api/users.v1.Service/ListUsers", + headers={ + "Authorization": f"Bearer {TOKEN}", + "Content-Type": "application/json", + }, + json={}, +) +users = resp.json()["users"] +``` + +## Response field mapping + +### Deep Search + +| Old field | New field | +|---|---| +| `id: 140` | `name: "users/1/conversations/140"` | +| `status: "processing"` | `state: "STATE_PROCESSING"` | +| `status: "completed"` | `state: "STATE_COMPLETED"` | +| `questions[].answer` | `questions[].answer` (unchanged) | +| `read_token` | Not exposed | +| `share_url` | Not exposed | + +### User management + +| GraphQL field | New field | +|---|---| +| `id` (opaque GraphQL ID) | `name: "users/alice"` | +| `username` | `username` (unchanged) | +| `displayName` | `display_name` | +| `avatarURL` | `avatar_uri` | +| `createdAt` | `create_time` | +| `updatedAt` | `update_time` | + +## Features not yet in the new API + +The following features from the old API do not have equivalents in the new API yet, but are planned to be supported in future versions: + +- Starring conversations +- Read token rotation and sharing via tokens +- Bulk delete of all conversations +- SSE streaming of question processing progress +- Code search, repository, git metadata, and Batch Changes operations (currently GraphQL-only) + +If you depend on any of these, please reach out at **support@sourcegraph.com**. + +## Migration checklist + +- [ ] Generate a new access token with `externalapi:read` / `externalapi:write` scopes +- [ ] Update `Authorization` header from `token ` to `Bearer ` +- [ ] Remove the `X-Requested-With` header +- [ ] Update Deep Search endpoint URLs from `/.api/deepsearch/v1/...` to `/api/deepsearch.v1.Service/...` +- [ ] Update user management calls from `/.api/graphql` to `/api/users.v1.Service/...` +- [ ] Change all HTTP methods to `POST` +- [ ] Update resource identifiers from numeric IDs to resource names (e.g. `users/-/conversations/140`) +- [ ] Update status checks from `"completed"` to `"STATE_COMPLETED"` (Deep Search) +- [ ] Test end-to-end + +## Other Sourcegraph APIs + +The existing Sourcegraph GraphQL API and experimental `/.api/deepsearch/` API remain available, but we recommend migrating to the new API at `/api/` for a stable integration experience. If you need features added to the new Sourcegraph API endpoints for your use cases, please reach out at **support@sourcegraph.com**. + +The following APIs continue to work as before and are **not deprecated at this time**: + +- **[GraphQL debug API](/api/graphql/)** (`/.api/graphql`) — code search, repositories, git metadata, Batch Changes, and all other functionality not yet covered by `/api/`. To reflect the GraphQL API's intended purpose, we have renamed it in our documentation and UI to the **Debug API** (or **Debug console**). New `/api/` equivalents will be introduced over time, and we recommend migrating to them as they become available. +- **[Stream API](/api/stream-api/)** (`/.api/search/stream`) — streaming search results +- **[Analytics API](/analytics/api/)** (`analytics.sourcegraph.com`) — usage metrics and reporting + +## Need help? + +If you have questions about the migration or need features not yet available in the new API, reach out at **support@sourcegraph.com**. From cd4f7ab4d19073593df6a49d4edac30b12510e65 Mon Sep 17 00:00:00 2001 From: julialeex Date: Thu, 26 Feb 2026 10:07:58 -0500 Subject: [PATCH 02/12] Update index.mdx --- docs/api/index.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/api/index.mdx b/docs/api/index.mdx index 124a4a488..b678c02b0 100644 --- a/docs/api/index.mdx +++ b/docs/api/index.mdx @@ -9,8 +9,6 @@ Starting in [Sourcegraph 7.0, a new versioned external API is being introduced f support@sourcegraph.com if you need more help. -If you're migrating from the experimental Deep Search API or GraphQL API, see [Upgrading to the Sourcegraph /api/ endpoints](/api/migration/). - For specific types of integrations, Sourcegraph also offers the following APIs: - [Sourcegraph streaming search API](/api/stream-api/), for consuming search results as a stream of events From f8033d0186b4e32d1ced072731a61897b1c21730 Mon Sep 17 00:00:00 2001 From: julialeex Date: Thu, 26 Feb 2026 10:12:50 -0500 Subject: [PATCH 03/12] Update index.mdx --- docs/api/migration/index.mdx | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/api/migration/index.mdx b/docs/api/migration/index.mdx index 2c9e897ac..b9010752a 100644 --- a/docs/api/migration/index.mdx +++ b/docs/api/migration/index.mdx @@ -7,8 +7,6 @@ Two services are available today: - **`deepsearch.v1.Service`** — replaces the experimental `/.api/deepsearch/v1` endpoints (create conversations, poll for results, manage follow-ups) - **`users.v1.Service`** — replaces GraphQL user queries and mutations (get, list, update, delete users) -Additional services for code search, repositories, git metadata, Batch Changes, and other functionality will be introduced over time. - An interactive API reference is available at `/api-reference` on your Sourcegraph instance (e.g. `https://sourcegraph.example.com/api-reference`), where you can view all operations and download the OpenAPI schema. ## What changed @@ -305,15 +303,15 @@ If you depend on any of these, please reach out at **support@sourcegraph.com**. ## Migration checklist -- [ ] Generate a new access token with `externalapi:read` / `externalapi:write` scopes -- [ ] Update `Authorization` header from `token ` to `Bearer ` -- [ ] Remove the `X-Requested-With` header -- [ ] Update Deep Search endpoint URLs from `/.api/deepsearch/v1/...` to `/api/deepsearch.v1.Service/...` -- [ ] Update user management calls from `/.api/graphql` to `/api/users.v1.Service/...` -- [ ] Change all HTTP methods to `POST` -- [ ] Update resource identifiers from numeric IDs to resource names (e.g. `users/-/conversations/140`) -- [ ] Update status checks from `"completed"` to `"STATE_COMPLETED"` (Deep Search) -- [ ] Test end-to-end +[ ] Generate a new access token with `externalapi:read` / `externalapi:write` scopes +[ ] Update `Authorization` header from `token ` to `Bearer ` +[ ] Remove the `X-Requested-With` header +[ ] Update Deep Search endpoint URLs from `/.api/deepsearch/v1/...` to `/api/deepsearch.v1.Service/...` +[ ] Update user management calls from `/.api/graphql` to `/api/users.v1.Service/...` +[ ] Change all HTTP methods to `POST` +[ ] Update resource identifiers from numeric IDs to resource names (e.g. `users/-/conversations/140`) +[ ] Update status checks from `"completed"` to `"STATE_COMPLETED"` (Deep Search) +[ ] Test end-to-end ## Other Sourcegraph APIs From eb8c3c33ce5e163b0373126eed45cad74e1216be Mon Sep 17 00:00:00 2001 From: julialeex Date: Thu, 26 Feb 2026 10:17:48 -0500 Subject: [PATCH 04/12] add image --- docs/api/migration/index.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/api/migration/index.mdx b/docs/api/migration/index.mdx index b9010752a..b20222a99 100644 --- a/docs/api/migration/index.mdx +++ b/docs/api/migration/index.mdx @@ -9,6 +9,8 @@ Two services are available today: An interactive API reference is available at `/api-reference` on your Sourcegraph instance (e.g. `https://sourcegraph.example.com/api-reference`), where you can view all operations and download the OpenAPI schema. +![API reference](https://storage.googleapis.com/sourcegraph-assets/Docs/api-reference.png) + ## What changed 1. **Protocol**: REST / GraphQL → [ConnectRPC](https://connectrpc.com/) (always POST with JSON) From a3d72d012ccbede0bb8d17e3a0ece3fa25b5f929 Mon Sep 17 00:00:00 2001 From: julialeex Date: Thu, 26 Feb 2026 10:22:24 -0500 Subject: [PATCH 05/12] fix --- docs/api/migration/index.mdx | 80 ++++++++++++++++++------------------ 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/docs/api/migration/index.mdx b/docs/api/migration/index.mdx index b20222a99..35d829c9d 100644 --- a/docs/api/migration/index.mdx +++ b/docs/api/migration/index.mdx @@ -32,24 +32,24 @@ An interactive API reference is available at `/api-reference` on your Sourcegrap ### Deep Search (`/.api/deepsearch/v1` → `deepsearch.v1.Service`) -| Operation | Old endpoint | New endpoint | -|---|---|---| -| Create conversation | `POST /.api/deepsearch/v1` | `POST /api/deepsearch.v1.Service/CreateConversation` | -| Get conversation | `GET /.api/deepsearch/v1/{id}` | `POST /api/deepsearch.v1.Service/GetConversation` | -| List conversations | `GET /.api/deepsearch/v1` | `POST /api/deepsearch.v1.Service/ListConversationSummaries` | -| Add follow-up | `POST /.api/deepsearch/v1/{id}/questions` | `POST /api/deepsearch.v1.Service/AddConversationQuestion` | -| Cancel question | `POST /.api/deepsearch/v1/{id}/questions/{qid}/cancel` | `POST /api/deepsearch.v1.Service/CancelConversation` | -| Delete conversation | `DELETE /.api/deepsearch/v1/{id}` | `POST /api/deepsearch.v1.Service/DeleteConversation` | +| Operation | Old endpoint | New endpoint | +| ------------------- | ------------------------------------------------------ | ----------------------------------------------------------- | +| Create conversation | `POST /.api/deepsearch/v1` | `POST /api/deepsearch.v1.Service/CreateConversation` | +| Get conversation | `GET /.api/deepsearch/v1/{id}` | `POST /api/deepsearch.v1.Service/GetConversation` | +| List conversations | `GET /.api/deepsearch/v1` | `POST /api/deepsearch.v1.Service/ListConversationSummaries` | +| Add follow-up | `POST /.api/deepsearch/v1/{id}/questions` | `POST /api/deepsearch.v1.Service/AddConversationQuestion` | +| Cancel question | `POST /.api/deepsearch/v1/{id}/questions/{qid}/cancel` | `POST /api/deepsearch.v1.Service/CancelConversation` | +| Delete conversation | `DELETE /.api/deepsearch/v1/{id}` | `POST /api/deepsearch.v1.Service/DeleteConversation` | ### User management (`/.api/graphql` → `users.v1.Service`) -| Operation | GraphQL | New endpoint | -|---|---|---| -| Get user | `query { user(username: "alice") { ... } }` | `POST /api/users.v1.Service/GetUser` | -| List users | `query { users { nodes { ... } } }` | `POST /api/users.v1.Service/ListUsers` | -| Update user | `mutation { updateUser(...) { ... } }` | `POST /api/users.v1.Service/UpdateUser` | -| Delete users | `mutation { deleteUser(...) { ... } }` | `POST /api/users.v1.Service/BatchDeleteUsers` | -| Undelete users | *(not available in GraphQL)* | `POST /api/users.v1.Service/BatchUndeleteUsers` | +| Operation | GraphQL | New endpoint | +| -------------- | ------------------------------------------- | ----------------------------------------------- | +| Get user | `query { user(username: "alice") { ... } }` | `POST /api/users.v1.Service/GetUser` | +| List users | `query { users { nodes { ... } } }` | `POST /api/users.v1.Service/ListUsers` | +| Update user | `mutation { updateUser(...) { ... } }` | `POST /api/users.v1.Service/UpdateUser` | +| Delete users | `mutation { deleteUser(...) { ... } }` | `POST /api/users.v1.Service/BatchDeleteUsers` | +| Undelete users | _(not available in GraphQL)_ | `POST /api/users.v1.Service/BatchUndeleteUsers` | ## Migration by example (Python) @@ -271,25 +271,25 @@ users = resp.json()["users"] ### Deep Search -| Old field | New field | -|---|---| -| `id: 140` | `name: "users/1/conversations/140"` | -| `status: "processing"` | `state: "STATE_PROCESSING"` | -| `status: "completed"` | `state: "STATE_COMPLETED"` | -| `questions[].answer` | `questions[].answer` (unchanged) | -| `read_token` | Not exposed | -| `share_url` | Not exposed | +| Old field | New field | +| ---------------------- | ----------------------------------- | +| `id: 140` | `name: "users/1/conversations/140"` | +| `status: "processing"` | `state: "STATE_PROCESSING"` | +| `status: "completed"` | `state: "STATE_COMPLETED"` | +| `questions[].answer` | `questions[].answer` (unchanged) | +| `read_token` | Not exposed | +| `share_url` | Not exposed | ### User management -| GraphQL field | New field | -|---|---| -| `id` (opaque GraphQL ID) | `name: "users/alice"` | -| `username` | `username` (unchanged) | -| `displayName` | `display_name` | -| `avatarURL` | `avatar_uri` | -| `createdAt` | `create_time` | -| `updatedAt` | `update_time` | +| GraphQL field | New field | +| ------------------------ | ---------------------- | +| `id` (opaque GraphQL ID) | `name: "users/alice"` | +| `username` | `username` (unchanged) | +| `displayName` | `display_name` | +| `avatarURL` | `avatar_uri` | +| `createdAt` | `create_time` | +| `updatedAt` | `update_time` | ## Features not yet in the new API @@ -305,15 +305,15 @@ If you depend on any of these, please reach out at **support@sourcegraph.com**. ## Migration checklist -[ ] Generate a new access token with `externalapi:read` / `externalapi:write` scopes -[ ] Update `Authorization` header from `token ` to `Bearer ` -[ ] Remove the `X-Requested-With` header -[ ] Update Deep Search endpoint URLs from `/.api/deepsearch/v1/...` to `/api/deepsearch.v1.Service/...` -[ ] Update user management calls from `/.api/graphql` to `/api/users.v1.Service/...` -[ ] Change all HTTP methods to `POST` -[ ] Update resource identifiers from numeric IDs to resource names (e.g. `users/-/conversations/140`) -[ ] Update status checks from `"completed"` to `"STATE_COMPLETED"` (Deep Search) -[ ] Test end-to-end +- [ ] Generate a new access token with `externalapi:read` / `externalapi:write` scopes +- [ ] Update `Authorization` header from `token ` to `Bearer ` +- [ ] Remove the `X-Requested-With` header +- [ ] Update Deep Search endpoint URLs from `/.api/deepsearch/v1/...` to `/api/deepsearch.v1.Service/...` +- [ ] Update user management calls from `/.api/graphql` to `/api/users.v1.Service/...` +- [ ] Change all HTTP methods to `POST` +- [ ] Update resource identifiers from numeric IDs to resource names (e.g. `users/-/conversations/140`) +- [ ] Update status checks from `"completed"` to `"STATE_COMPLETED"` (Deep Search) +- [ ] Test end-to-end ## Other Sourcegraph APIs From 0af6822a8057dd29a33bc5fd557d7d9314726aa7 Mon Sep 17 00:00:00 2001 From: julialeex Date: Thu, 26 Feb 2026 16:39:16 -0500 Subject: [PATCH 06/12] address PR comments --- docs/api/index.mdx | 2 +- docs/api/migration/index.mdx | 330 ----------------------------------- docs/deep-search/api.mdx | 197 ++++++++++++++++++++- 3 files changed, 195 insertions(+), 334 deletions(-) delete mode 100644 docs/api/migration/index.mdx diff --git a/docs/api/index.mdx b/docs/api/index.mdx index 5350307f6..8c4ff1582 100644 --- a/docs/api/index.mdx +++ b/docs/api/index.mdx @@ -5,7 +5,7 @@ Starting in [Sourcegraph 7.0](https://sourcegraph.com/changelog/releases/7.0), a The new Sourcegraph API is a work in progress, and capabilities are gradually being ported over. If you have an integration you'd like to build - that is not currently served by the new Sourcegraph API, or migrate to the new Sourcegraph API, you can learn more about it in [our migration guide](/api/migration/). Please reach out at + that is not currently served by the new Sourcegraph API, or migrate to the new Sourcegraph API, you can learn more about it in our [Deep Search API migration guide](/deep-search/api#upgrading-to-the-sourcegraph-api-endpoints). Please reach out at support@sourcegraph.com if you need more help. diff --git a/docs/api/migration/index.mdx b/docs/api/migration/index.mdx deleted file mode 100644 index 35d829c9d..000000000 --- a/docs/api/migration/index.mdx +++ /dev/null @@ -1,330 +0,0 @@ -# Upgrading to the new Sourcegraph API - -Starting in Sourcegraph 7.0, Sourcegraph introduces a new, versioned API at `/api/`. **The new API provides stable, supported endpoints** for functionality previously served by the experimental Deep Search API (`/.api/deepsearch/v1`) and the GraphQL API (`/.api/graphql`). - -Two services are available today: - -- **`deepsearch.v1.Service`** — replaces the experimental `/.api/deepsearch/v1` endpoints (create conversations, poll for results, manage follow-ups) -- **`users.v1.Service`** — replaces GraphQL user queries and mutations (get, list, update, delete users) - -An interactive API reference is available at `/api-reference` on your Sourcegraph instance (e.g. `https://sourcegraph.example.com/api-reference`), where you can view all operations and download the OpenAPI schema. - -![API reference](https://storage.googleapis.com/sourcegraph-assets/Docs/api-reference.png) - -## What changed - -1. **Protocol**: REST / GraphQL → [ConnectRPC](https://connectrpc.com/) (always POST with JSON) -2. **Base URL**: `/.api/deepsearch/v1/...` and `/.api/graphql` → `/api/{service}/...` -3. **Auth header**: `Authorization: token ` → `Authorization: Bearer ` -4. **Token scopes**: Any access token → token with `externalapi:read` / `externalapi:write` scope -5. **`X-Requested-With` header**: No longer required -6. **Resource identifiers**: Numeric IDs (`140`) → resource names (`users/-/conversations/140`) -7. **Status field** (Deep Search): `status: "processing"` → `state: "STATE_PROCESSING"` - -## Why migrate - -- **Stability guarantees** — the new API is versioned with backwards compatibility commitments -- **Interactive documentation** — explore and test at `/api-reference` -- **OpenAPI schema** — generate typed clients in any language -- **Scoped tokens** — finer-grained access control with `externalapi:read` / `externalapi:write` - -## Endpoint mapping - -### Deep Search (`/.api/deepsearch/v1` → `deepsearch.v1.Service`) - -| Operation | Old endpoint | New endpoint | -| ------------------- | ------------------------------------------------------ | ----------------------------------------------------------- | -| Create conversation | `POST /.api/deepsearch/v1` | `POST /api/deepsearch.v1.Service/CreateConversation` | -| Get conversation | `GET /.api/deepsearch/v1/{id}` | `POST /api/deepsearch.v1.Service/GetConversation` | -| List conversations | `GET /.api/deepsearch/v1` | `POST /api/deepsearch.v1.Service/ListConversationSummaries` | -| Add follow-up | `POST /.api/deepsearch/v1/{id}/questions` | `POST /api/deepsearch.v1.Service/AddConversationQuestion` | -| Cancel question | `POST /.api/deepsearch/v1/{id}/questions/{qid}/cancel` | `POST /api/deepsearch.v1.Service/CancelConversation` | -| Delete conversation | `DELETE /.api/deepsearch/v1/{id}` | `POST /api/deepsearch.v1.Service/DeleteConversation` | - -### User management (`/.api/graphql` → `users.v1.Service`) - -| Operation | GraphQL | New endpoint | -| -------------- | ------------------------------------------- | ----------------------------------------------- | -| Get user | `query { user(username: "alice") { ... } }` | `POST /api/users.v1.Service/GetUser` | -| List users | `query { users { nodes { ... } } }` | `POST /api/users.v1.Service/ListUsers` | -| Update user | `mutation { updateUser(...) { ... } }` | `POST /api/users.v1.Service/UpdateUser` | -| Delete users | `mutation { deleteUser(...) { ... } }` | `POST /api/users.v1.Service/BatchDeleteUsers` | -| Undelete users | _(not available in GraphQL)_ | `POST /api/users.v1.Service/BatchUndeleteUsers` | - -## Migration by example (Python) - -### Deep Search: Create a conversation - -**Before:** - -```python -import requests - -resp = requests.post( - "https://sourcegraph.example.com/.api/deepsearch/v1", - headers={ - "Authorization": f"token {TOKEN}", - "X-Requested-With": "my-client 1.0.0", - }, - json={"question": "Does the repo have a README?"}, -) -conversation = resp.json() -conversation_id = conversation["id"] -``` - -**After:** - -```python -import requests - -resp = requests.post( - "https://sourcegraph.example.com/api/deepsearch.v1.Service/CreateConversation", - headers={ - "Authorization": f"Bearer {TOKEN}", - "Content-Type": "application/json", - }, - json={"question": "Does the repo have a README?"}, -) -conversation = resp.json() -conversation_name = conversation["name"] # e.g. "users/1/conversations/140" -``` - -**With curl:** - -```bash -# Before -curl 'https://sourcegraph.example.com/.api/deepsearch/v1' \ - -H "Authorization: token $TOKEN" \ - -H 'X-Requested-With: my-client 1.0.0' \ - -H 'Content-Type: application/json' \ - -d '{"question":"Does the repo have a README?"}' - -# After -curl 'https://sourcegraph.example.com/api/deepsearch.v1.Service/CreateConversation' \ - -H "Authorization: Bearer $TOKEN" \ - -H 'Content-Type: application/json' \ - -d '{"question":"Does the repo have a README?"}' -``` - -### Deep Search: Poll for the result - -The polling workflow is the same — keep calling until the status indicates completion. The only changes are the URL, method, and status field name. - -**Before:** - -```python -import time - -while True: - resp = requests.get( - f"https://sourcegraph.example.com/.api/deepsearch/v1/{conversation_id}", - headers={ - "Authorization": f"token {TOKEN}", - "X-Requested-With": "my-client 1.0.0", - }, - ) - data = resp.json() - if data["questions"][0]["status"] == "completed": - print(data["questions"][0]["answer"]) - break - time.sleep(2) -``` - -**After:** - -```python -import time - -while True: - resp = requests.post( - "https://sourcegraph.example.com/api/deepsearch.v1.Service/GetConversation", - headers={ - "Authorization": f"Bearer {TOKEN}", - "Content-Type": "application/json", - }, - json={"name": conversation_name}, - ) - data = resp.json() - if data["state"] == "STATE_COMPLETED": - print(data["questions"][0]["answer"]) - break - time.sleep(2) -``` - -### Deep Search: Add a follow-up question - -**Before:** - -```python -resp = requests.post( - f"https://sourcegraph.example.com/.api/deepsearch/v1/{conversation_id}/questions", - headers={ - "Authorization": f"token {TOKEN}", - "X-Requested-With": "my-client 1.0.0", - }, - json={ - "conversation_id": conversation_id, - "question": "What does the README contain?", - }, -) -``` - -**After:** - -```python -resp = requests.post( - "https://sourcegraph.example.com/api/deepsearch.v1.Service/AddConversationQuestion", - headers={ - "Authorization": f"Bearer {TOKEN}", - "Content-Type": "application/json", - }, - json={ - "parent": conversation_name, - "question": "What does the README contain?", - }, -) -``` - -### User management: Get a user - -**Before (GraphQL):** - -```python -import requests - -resp = requests.post( - "https://sourcegraph.example.com/.api/graphql", - headers={ - "Authorization": f"token {TOKEN}", - }, - json={ - "query": 'query { user(username: "alice") { id username displayName } }', - }, -) -user = resp.json()["data"]["user"] -``` - -**After:** - -```python -import requests - -resp = requests.post( - "https://sourcegraph.example.com/api/users.v1.Service/GetUser", - headers={ - "Authorization": f"Bearer {TOKEN}", - "Content-Type": "application/json", - }, - json={"name": "users/alice"}, -) -user = resp.json() -``` - -**With curl:** - -```bash -# Before (GraphQL) -curl 'https://sourcegraph.example.com/.api/graphql' \ - -H "Authorization: token $TOKEN" \ - -H 'Content-Type: application/json' \ - -d '{"query":"query { user(username: \"alice\") { id username displayName } }"}' - -# After -curl 'https://sourcegraph.example.com/api/users.v1.Service/GetUser' \ - -H "Authorization: Bearer $TOKEN" \ - -H 'Content-Type: application/json' \ - -d '{"name":"users/alice"}' -``` - -### User management: List users - -**Before (GraphQL):** - -```python -resp = requests.post( - "https://sourcegraph.example.com/.api/graphql", - headers={ - "Authorization": f"token {TOKEN}", - }, - json={ - "query": "query { users { nodes { id username displayName } } }", - }, -) -users = resp.json()["data"]["users"]["nodes"] -``` - -**After:** - -```python -resp = requests.post( - "https://sourcegraph.example.com/api/users.v1.Service/ListUsers", - headers={ - "Authorization": f"Bearer {TOKEN}", - "Content-Type": "application/json", - }, - json={}, -) -users = resp.json()["users"] -``` - -## Response field mapping - -### Deep Search - -| Old field | New field | -| ---------------------- | ----------------------------------- | -| `id: 140` | `name: "users/1/conversations/140"` | -| `status: "processing"` | `state: "STATE_PROCESSING"` | -| `status: "completed"` | `state: "STATE_COMPLETED"` | -| `questions[].answer` | `questions[].answer` (unchanged) | -| `read_token` | Not exposed | -| `share_url` | Not exposed | - -### User management - -| GraphQL field | New field | -| ------------------------ | ---------------------- | -| `id` (opaque GraphQL ID) | `name: "users/alice"` | -| `username` | `username` (unchanged) | -| `displayName` | `display_name` | -| `avatarURL` | `avatar_uri` | -| `createdAt` | `create_time` | -| `updatedAt` | `update_time` | - -## Features not yet in the new API - -The following features from the old API do not have equivalents in the new API yet, but are planned to be supported in future versions: - -- Starring conversations -- Read token rotation and sharing via tokens -- Bulk delete of all conversations -- SSE streaming of question processing progress -- Code search, repository, git metadata, and Batch Changes operations (currently GraphQL-only) - -If you depend on any of these, please reach out at **support@sourcegraph.com**. - -## Migration checklist - -- [ ] Generate a new access token with `externalapi:read` / `externalapi:write` scopes -- [ ] Update `Authorization` header from `token ` to `Bearer ` -- [ ] Remove the `X-Requested-With` header -- [ ] Update Deep Search endpoint URLs from `/.api/deepsearch/v1/...` to `/api/deepsearch.v1.Service/...` -- [ ] Update user management calls from `/.api/graphql` to `/api/users.v1.Service/...` -- [ ] Change all HTTP methods to `POST` -- [ ] Update resource identifiers from numeric IDs to resource names (e.g. `users/-/conversations/140`) -- [ ] Update status checks from `"completed"` to `"STATE_COMPLETED"` (Deep Search) -- [ ] Test end-to-end - -## Other Sourcegraph APIs - -The existing Sourcegraph GraphQL API and experimental `/.api/deepsearch/` API remain available, but we recommend migrating to the new API at `/api/` for a stable integration experience. If you need features added to the new Sourcegraph API endpoints for your use cases, please reach out at **support@sourcegraph.com**. - -The following APIs continue to work as before and are **not deprecated at this time**: - -- **[GraphQL debug API](/api/graphql/)** (`/.api/graphql`) — code search, repositories, git metadata, Batch Changes, and all other functionality not yet covered by `/api/`. To reflect the GraphQL API's intended purpose, we have renamed it in our documentation and UI to the **Debug API** (or **Debug console**). New `/api/` equivalents will be introduced over time, and we recommend migrating to them as they become available. -- **[Stream API](/api/stream-api/)** (`/.api/search/stream`) — streaming search results -- **[Analytics API](/analytics/api/)** (`analytics.sourcegraph.com`) — usage metrics and reporting - -## Need help? - -If you have questions about the migration or need features not yet available in the new API, reach out at **support@sourcegraph.com**. diff --git a/docs/deep-search/api.mdx b/docs/deep-search/api.mdx index dfdcf0ee1..dea0d8aea 100644 --- a/docs/deep-search/api.mdx +++ b/docs/deep-search/api.mdx @@ -7,9 +7,9 @@ preview: true

The **experimental** Deep Search API has been **deprecated** as of - [Sourcegraph 7.0](https://sourcegraph.com/changelog/releases/7.0). In this release, [a new versioned Sourcegraph API is - being introduced for custom - integrations](https://sourcegraph.com/changelog/sourcegraph-api), + [Sourcegraph 7.0](https://sourcegraph.com/changelog/releases/7.0). In + this release, [a new versioned Sourcegraph API is being introduced for + custom integrations](https://sourcegraph.com/changelog/sourcegraph-api), available at `/api-reference` (e.g. `https://sourcegraph.example.com/api-reference`). This experimental Deep Search API remains available, but we recommend migrating to the new API @@ -298,3 +298,194 @@ The API returns standard HTTP status codes with descriptive error messages: - `401` - Unauthorized - `404` - Not Found - `500` - Internal Server Error + +## Upgrading to the Sourcegraph /api/ endpoints + +Starting in [Sourcegraph 7.0](/changelog/releases/7.0), Sourcegraph introduces a new, versioned [API](/api/) at `/api/`. **The new API provides stable, supported endpoints** for functionality previously served by this experimental Deep Search API. See the [Sourcegraph API changelog](/changelog/sourcegraph-api) for more details. + +An interactive API reference is available at `/api-reference` on your Sourcegraph instance (e.g. `https://sourcegraph.example.com/api-reference`), where you can view all operations and download the OpenAPI schema. + +![API reference](https://storage.googleapis.com/sourcegraph-assets/Docs/api-reference-dark.png) + +### What changed + +1. **Base URL**: `/.api/deepsearch/v1/...` → `/api/deepsearch.v1.Service/...` +2. **Token scopes**: Any access token → token with `externalapi:read` / `externalapi:write` scope +3. **`X-Requested-With` header**: No longer required +4. **Resource identifiers**: Numeric IDs (`140`) → resource names (`users/-/conversations/140`) +5. **Status field**: `status: "processing"` → `state: "STATE_PROCESSING"` + +### Why migrate + +- **Stability guarantees** — the new API is versioned with backwards compatibility commitments +- **Interactive documentation** — explore and test at `/api-reference` +- **OpenAPI schema** — generate typed clients in any language +- **Scoped tokens** — finer-grained access control with `externalapi:read` / `externalapi:write` + +### Endpoint mapping + +| Operation | Old endpoint | New endpoint | +| ------------------- | ------------------------------------------------------ | ----------------------------------------------------------- | +| Create conversation | `POST /.api/deepsearch/v1` | `POST /api/deepsearch.v1.Service/CreateConversation` | +| Get conversation | `GET /.api/deepsearch/v1/{id}` | `POST /api/deepsearch.v1.Service/GetConversation` | +| List conversations | `GET /.api/deepsearch/v1` | `POST /api/deepsearch.v1.Service/ListConversationSummaries` | +| Add follow-up | `POST /.api/deepsearch/v1/{id}/questions` | `POST /api/deepsearch.v1.Service/AddConversationQuestion` | +| Cancel question | `POST /.api/deepsearch/v1/{id}/questions/{qid}/cancel` | `POST /api/deepsearch.v1.Service/CancelConversation` | +| Delete conversation | `DELETE /.api/deepsearch/v1/{id}` | `POST /api/deepsearch.v1.Service/DeleteConversation` | + +### Migration examples + +#### Create a conversation + +**Before:** + +```python +import requests + +resp = requests.post( + "https://sourcegraph.example.com/.api/deepsearch/v1", + headers={ + "Authorization": f"token {TOKEN}", + "X-Requested-With": "my-client 1.0.0", + }, + json={"question": "Does the repo have a README?"}, +) +conversation = resp.json() +conversation_id = conversation["id"] +``` + +**After:** + +```python +import requests + +resp = requests.post( + "https://sourcegraph.example.com/api/deepsearch.v1.Service/CreateConversation", + headers={ + "Authorization": f"Bearer {TOKEN}", + "Content-Type": "application/json", + }, + json={"question": "Does the repo have a README?"}, +) +conversation = resp.json() +conversation_name = conversation["name"] # e.g. "users/1/conversations/140" +``` + +**With curl:** + +```bash +# Before +curl 'https://sourcegraph.example.com/.api/deepsearch/v1' \ + -H "Authorization: token $TOKEN" \ + -H 'X-Requested-With: my-client 1.0.0' \ + -H 'Content-Type: application/json' \ + -d '{"question":"Does the repo have a README?"}' + +# After +curl 'https://sourcegraph.example.com/api/deepsearch.v1.Service/CreateConversation' \ + -H "Authorization: Bearer $TOKEN" \ + -H 'Content-Type: application/json' \ + -d '{"question":"Does the repo have a README?"}' +``` + +#### Poll for the result + +The polling workflow is the same — keep calling until the status indicates completion. The only changes are the URL, method, and status field name. + +**Before:** + +```python +import time + +while True: + resp = requests.get( + f"https://sourcegraph.example.com/.api/deepsearch/v1/{conversation_id}", + headers={ + "Authorization": f"token {TOKEN}", + "X-Requested-With": "my-client 1.0.0", + }, + ) + data = resp.json() + if data["questions"][0]["status"] == "completed": + print(data["questions"][0]["answer"]) + break + time.sleep(2) +``` + +**After:** + +```python +import time + +while True: + resp = requests.post( + "https://sourcegraph.example.com/api/deepsearch.v1.Service/GetConversation", + headers={ + "Authorization": f"Bearer {TOKEN}", + "Content-Type": "application/json", + }, + json={"name": conversation_name}, + ) + data = resp.json() + if data["state"] == "STATE_COMPLETED": + print(data["questions"][0]["answer"]) + break + time.sleep(2) +``` + +#### Add a follow-up question + +**Before:** + +```python +resp = requests.post( + f"https://sourcegraph.example.com/.api/deepsearch/v1/{conversation_id}/questions", + headers={ + "Authorization": f"token {TOKEN}", + "X-Requested-With": "my-client 1.0.0", + }, + json={ + "conversation_id": conversation_id, + "question": "What does the README contain?", + }, +) +``` + +**After:** + +```python +resp = requests.post( + "https://sourcegraph.example.com/api/deepsearch.v1.Service/AddConversationQuestion", + headers={ + "Authorization": f"Bearer {TOKEN}", + "Content-Type": "application/json", + }, + json={ + "parent": conversation_name, + "question": "What does the README contain?", + }, +) +``` + +### Response field mapping + +| Old field | New field | +| ---------------------- | ----------------------------------- | +| `id: 140` | `name: "users/1/conversations/140"` | +| `status: "processing"` | `state: "STATE_PROCESSING"` | +| `status: "completed"` | `state: "STATE_COMPLETED"` | +| `questions[].answer` | `questions[].answer` (unchanged) | +| `read_token` | Not exposed | +| `share_url` | Not exposed | + +### Migration checklist + +- [ ] Generate a new access token with `externalapi:read` / `externalapi:write` scopes +- [ ] Remove the `X-Requested-With` header +- [ ] Update endpoint URLs from `/.api/deepsearch/v1/...` to `/api/deepsearch.v1.Service/...` +- [ ] Change all HTTP methods to `POST` +- [ ] Update resource identifiers from numeric IDs to resource names (e.g. `users/-/conversations/140`) +- [ ] Update status checks from `"completed"` to `"STATE_COMPLETED"` +- [ ] Test end-to-end + +If you have questions about the migration or need features not yet available in the new API, reach out at **support@sourcegraph.com**. From c32d658949c512ae267c9c32883802b9b7e01d50 Mon Sep 17 00:00:00 2001 From: julialeex Date: Thu, 26 Feb 2026 16:49:38 -0500 Subject: [PATCH 07/12] move the doc location --- docs/deep-search/api.mdx | 143 +-------------------------------------- 1 file changed, 1 insertion(+), 142 deletions(-) diff --git a/docs/deep-search/api.mdx b/docs/deep-search/api.mdx index dea0d8aea..bc2263687 100644 --- a/docs/deep-search/api.mdx +++ b/docs/deep-search/api.mdx @@ -299,7 +299,7 @@ The API returns standard HTTP status codes with descriptive error messages: - `404` - Not Found - `500` - Internal Server Error -## Upgrading to the Sourcegraph /api/ endpoints +## Migrating to the New Sourcegraph API Starting in [Sourcegraph 7.0](/changelog/releases/7.0), Sourcegraph introduces a new, versioned [API](/api/) at `/api/`. **The new API provides stable, supported endpoints** for functionality previously served by this experimental Deep Search API. See the [Sourcegraph API changelog](/changelog/sourcegraph-api) for more details. @@ -315,13 +315,6 @@ An interactive API reference is available at `/api-reference` on your Sourcegrap 4. **Resource identifiers**: Numeric IDs (`140`) → resource names (`users/-/conversations/140`) 5. **Status field**: `status: "processing"` → `state: "STATE_PROCESSING"` -### Why migrate - -- **Stability guarantees** — the new API is versioned with backwards compatibility commitments -- **Interactive documentation** — explore and test at `/api-reference` -- **OpenAPI schema** — generate typed clients in any language -- **Scoped tokens** — finer-grained access control with `externalapi:read` / `externalapi:write` - ### Endpoint mapping | Operation | Old endpoint | New endpoint | @@ -333,140 +326,6 @@ An interactive API reference is available at `/api-reference` on your Sourcegrap | Cancel question | `POST /.api/deepsearch/v1/{id}/questions/{qid}/cancel` | `POST /api/deepsearch.v1.Service/CancelConversation` | | Delete conversation | `DELETE /.api/deepsearch/v1/{id}` | `POST /api/deepsearch.v1.Service/DeleteConversation` | -### Migration examples - -#### Create a conversation - -**Before:** - -```python -import requests - -resp = requests.post( - "https://sourcegraph.example.com/.api/deepsearch/v1", - headers={ - "Authorization": f"token {TOKEN}", - "X-Requested-With": "my-client 1.0.0", - }, - json={"question": "Does the repo have a README?"}, -) -conversation = resp.json() -conversation_id = conversation["id"] -``` - -**After:** - -```python -import requests - -resp = requests.post( - "https://sourcegraph.example.com/api/deepsearch.v1.Service/CreateConversation", - headers={ - "Authorization": f"Bearer {TOKEN}", - "Content-Type": "application/json", - }, - json={"question": "Does the repo have a README?"}, -) -conversation = resp.json() -conversation_name = conversation["name"] # e.g. "users/1/conversations/140" -``` - -**With curl:** - -```bash -# Before -curl 'https://sourcegraph.example.com/.api/deepsearch/v1' \ - -H "Authorization: token $TOKEN" \ - -H 'X-Requested-With: my-client 1.0.0' \ - -H 'Content-Type: application/json' \ - -d '{"question":"Does the repo have a README?"}' - -# After -curl 'https://sourcegraph.example.com/api/deepsearch.v1.Service/CreateConversation' \ - -H "Authorization: Bearer $TOKEN" \ - -H 'Content-Type: application/json' \ - -d '{"question":"Does the repo have a README?"}' -``` - -#### Poll for the result - -The polling workflow is the same — keep calling until the status indicates completion. The only changes are the URL, method, and status field name. - -**Before:** - -```python -import time - -while True: - resp = requests.get( - f"https://sourcegraph.example.com/.api/deepsearch/v1/{conversation_id}", - headers={ - "Authorization": f"token {TOKEN}", - "X-Requested-With": "my-client 1.0.0", - }, - ) - data = resp.json() - if data["questions"][0]["status"] == "completed": - print(data["questions"][0]["answer"]) - break - time.sleep(2) -``` - -**After:** - -```python -import time - -while True: - resp = requests.post( - "https://sourcegraph.example.com/api/deepsearch.v1.Service/GetConversation", - headers={ - "Authorization": f"Bearer {TOKEN}", - "Content-Type": "application/json", - }, - json={"name": conversation_name}, - ) - data = resp.json() - if data["state"] == "STATE_COMPLETED": - print(data["questions"][0]["answer"]) - break - time.sleep(2) -``` - -#### Add a follow-up question - -**Before:** - -```python -resp = requests.post( - f"https://sourcegraph.example.com/.api/deepsearch/v1/{conversation_id}/questions", - headers={ - "Authorization": f"token {TOKEN}", - "X-Requested-With": "my-client 1.0.0", - }, - json={ - "conversation_id": conversation_id, - "question": "What does the README contain?", - }, -) -``` - -**After:** - -```python -resp = requests.post( - "https://sourcegraph.example.com/api/deepsearch.v1.Service/AddConversationQuestion", - headers={ - "Authorization": f"Bearer {TOKEN}", - "Content-Type": "application/json", - }, - json={ - "parent": conversation_name, - "question": "What does the README contain?", - }, -) -``` - ### Response field mapping | Old field | New field | From db91b6df1098d9e1c069516f80d5bcf75dbb14c1 Mon Sep 17 00:00:00 2001 From: julialeex Date: Thu, 26 Feb 2026 16:51:39 -0500 Subject: [PATCH 08/12] update link --- docs/api/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/index.mdx b/docs/api/index.mdx index 8c4ff1582..26608d7c0 100644 --- a/docs/api/index.mdx +++ b/docs/api/index.mdx @@ -5,7 +5,7 @@ Starting in [Sourcegraph 7.0](https://sourcegraph.com/changelog/releases/7.0), a The new Sourcegraph API is a work in progress, and capabilities are gradually being ported over. If you have an integration you'd like to build - that is not currently served by the new Sourcegraph API, or migrate to the new Sourcegraph API, you can learn more about it in our [Deep Search API migration guide](/deep-search/api#upgrading-to-the-sourcegraph-api-endpoints). Please reach out at + that is not currently served by the new Sourcegraph API, or migrate to the new Sourcegraph API, you can learn more about it in our [Deep Search API migration guide](/deep-search/api?preview#migrating-from-the-old-api-endpoints). Please reach out at support@sourcegraph.com if you need more help. From 3200794ec775442f546eade5e7635e11ce0d5659 Mon Sep 17 00:00:00 2001 From: julialeex Date: Thu, 26 Feb 2026 17:28:01 -0500 Subject: [PATCH 09/12] AI-assisted migration --- docs/deep-search/api.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/deep-search/api.mdx b/docs/deep-search/api.mdx index bc2263687..dd3b13a56 100644 --- a/docs/deep-search/api.mdx +++ b/docs/deep-search/api.mdx @@ -315,6 +315,12 @@ An interactive API reference is available at `/api-reference` on your Sourcegrap 4. **Resource identifiers**: Numeric IDs (`140`) → resource names (`users/-/conversations/140`) 5. **Status field**: `status: "processing"` → `state: "STATE_PROCESSING"` +### AI-assisted migration + +The fastest way to migrate is to give your AI coding agent the OpenAPI schema and let it update your code. You can download the schema from `/api-reference` on your Sourcegraph instance (e.g. `https://sourcegraph.example.com/api-reference`) — look for the **Download OpenAPI** button. Then tell your agent to migrate your Deep Search API calls to the new `/api/` equivalents. + +For a real-world example, see [this Amp thread](https://ampcode.com/threads/T-019c9bf7-e5bd-778e-b8c8-0796ce033784) migrating the [raycast-sourcegraph](https://github.com/bobheadxi/raycast-sourcegraph) extension from the old API to the new endpoints. + ### Endpoint mapping | Operation | Old endpoint | New endpoint | From 7e8a679ddb517d75621a71bb5d6d4c2b06b0fae3 Mon Sep 17 00:00:00 2001 From: julialeex Date: Thu, 26 Feb 2026 17:29:03 -0500 Subject: [PATCH 10/12] fix --- docs/api/index.mdx | 2 +- docs/deep-search/api.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/index.mdx b/docs/api/index.mdx index 26608d7c0..6d16416f6 100644 --- a/docs/api/index.mdx +++ b/docs/api/index.mdx @@ -5,7 +5,7 @@ Starting in [Sourcegraph 7.0](https://sourcegraph.com/changelog/releases/7.0), a The new Sourcegraph API is a work in progress, and capabilities are gradually being ported over. If you have an integration you'd like to build - that is not currently served by the new Sourcegraph API, or migrate to the new Sourcegraph API, you can learn more about it in our [Deep Search API migration guide](/deep-search/api?preview#migrating-from-the-old-api-endpoints). Please reach out at + that is not currently served by the new Sourcegraph API, or migrate to the new Sourcegraph API, you can learn more about it in our [Deep Search API migration guide](/deep-search/api#migrating-to-the-new-sourcegraph-api). Please reach out at support@sourcegraph.com if you need more help. diff --git a/docs/deep-search/api.mdx b/docs/deep-search/api.mdx index dd3b13a56..deaad59f2 100644 --- a/docs/deep-search/api.mdx +++ b/docs/deep-search/api.mdx @@ -301,7 +301,7 @@ The API returns standard HTTP status codes with descriptive error messages: ## Migrating to the New Sourcegraph API -Starting in [Sourcegraph 7.0](/changelog/releases/7.0), Sourcegraph introduces a new, versioned [API](/api/) at `/api/`. **The new API provides stable, supported endpoints** for functionality previously served by this experimental Deep Search API. See the [Sourcegraph API changelog](/changelog/sourcegraph-api) for more details. +Starting in [Sourcegraph 7.0](https://sourcegraph.com/changelog/releases/7.0), Sourcegraph introduces a new, versioned [API](/api/) at `/api/`. **The new API provides stable, supported endpoints** for functionality previously served by this experimental Deep Search API. See the [Sourcegraph API changelog](https://sourcegraph.com/changelog/sourcegraph-api) for more details. An interactive API reference is available at `/api-reference` on your Sourcegraph instance (e.g. `https://sourcegraph.example.com/api-reference`), where you can view all operations and download the OpenAPI schema. From 19d2f3f49a63f867b1f494c792e6e556f7cc0683 Mon Sep 17 00:00:00 2001 From: julialeex Date: Thu, 26 Feb 2026 18:03:11 -0500 Subject: [PATCH 11/12] address pr comments --- docs/api/index.mdx | 4 ++-- docs/deep-search/api.mdx | 6 ++++++ docs/deep-search/index.mdx | 2 +- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/api/index.mdx b/docs/api/index.mdx index 6d16416f6..a8d8894ee 100644 --- a/docs/api/index.mdx +++ b/docs/api/index.mdx @@ -5,8 +5,8 @@ Starting in [Sourcegraph 7.0](https://sourcegraph.com/changelog/releases/7.0), a The new Sourcegraph API is a work in progress, and capabilities are gradually being ported over. If you have an integration you'd like to build - that is not currently served by the new Sourcegraph API, or migrate to the new Sourcegraph API, you can learn more about it in our [Deep Search API migration guide](/deep-search/api#migrating-to-the-new-sourcegraph-api). Please reach out at - support@sourcegraph.com if you need more help. + that is not currently served by the new Sourcegraph API, please reach out at + support@sourcegraph.com. For specific types of integrations, Sourcegraph also offers the following APIs: diff --git a/docs/deep-search/api.mdx b/docs/deep-search/api.mdx index deaad59f2..760c7cf04 100644 --- a/docs/deep-search/api.mdx +++ b/docs/deep-search/api.mdx @@ -19,6 +19,12 @@ preview: true

Learn more about the Sourcegraph API [here](/api).

 + + If you're using the experimental Deep Search API, see the [migration + guide](/deep-search/api#migrating-to-the-new-sourcegraph-api) to upgrade to + the new `/api/` endpoints. + + 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 diff --git a/docs/deep-search/index.mdx b/docs/deep-search/index.mdx index 34c7bfcde..3d7bcc2eb 100644 --- a/docs/deep-search/index.mdx +++ b/docs/deep-search/index.mdx @@ -113,7 +113,7 @@ To learn more, refer to [Entitlements](/admin/entitlements) and the [Deep Search ## Integrations and APIs -Integrations can use [Sourcegraph APIs](/api), such as the new Sourcegraph API and MCP server, to interact with Deep Search. +Integrations can use [Sourcegraph APIs](/api), such as the [new Sourcegraph API](/deep-search/api) and MCP server, to interact with Deep Search. ## Architecture From c12e7ac92493ec718da0023ca67a9fd707369c32 Mon Sep 17 00:00:00 2001 From: julialeex Date: Fri, 27 Feb 2026 07:00:08 -0500 Subject: [PATCH 12/12] Apply suggestion from @bobheadxi Co-authored-by: Robert Lin --- docs/deep-search/index.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/deep-search/index.mdx b/docs/deep-search/index.mdx index 3d7bcc2eb..637105cad 100644 --- a/docs/deep-search/index.mdx +++ b/docs/deep-search/index.mdx @@ -113,7 +113,9 @@ To learn more, refer to [Entitlements](/admin/entitlements) and the [Deep Search ## Integrations and APIs -Integrations can use [Sourcegraph APIs](/api), such as the [new Sourcegraph API](/deep-search/api) and MCP server, to interact with Deep Search. +Integrations can use [Sourcegraph APIs](/api) and the [MCP server](/mcp) to interact with Deep Search. + +If you are using the experimental Deep Search API, please [follow our migration guide](/deep-search/api?preview). ## Architecture