Skip to content

feat/externalapi: Add API migration guide #1644

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
julialeex wants to merge 15 commits into
base: main
Choose a base branch
from
+68 −4
Open

feat/externalapi: Add API migration guide #1644

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
c7c808a
doc update
julialeex Feb 26, 2026
cd4f7ab
Update index.mdx
julialeex Feb 26, 2026
f8033d0
Update index.mdx
julialeex Feb 26, 2026
eb8c3c3
add image
julialeex Feb 26, 2026
a3d72d0
fix
julialeex Feb 26, 2026
62a15a4
Merge branch 'main' into jlxu/api_migration
julialeex Feb 26, 2026
0af6822
address PR comments
julialeex Feb 26, 2026
c32d658
move the doc location
julialeex Feb 26, 2026
db91b6d
update link
julialeex Feb 26, 2026
7a54074
Merge branch 'main' into jlxu/api_migration
julialeex Feb 26, 2026
3200794
AI-assisted migration
julialeex Feb 26, 2026
7e8a679
fix
julialeex Feb 26, 2026
9fb583d
Merge branch 'main' into jlxu/api_migration
julialeex Feb 26, 2026
19d2f3f
address pr comments
julialeex Feb 26, 2026
c12e7ac
Apply suggestion from @bobheadxi
julialeex Feb 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 65 additions & 3 deletions docs/deep-search/api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ preview: true
<Callout type="warning">
<p>
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
Expand All @@ -19,6 +19,12 @@ preview: true
<p>Learn more about the Sourcegraph API [here](/api).</p>
</Callout>

<Callout type="info">
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.
</Callout>

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
Expand Down Expand Up @@ -298,3 +304,59 @@ The API returns standard HTTP status codes with descriptive error messages:
- `401` - Unauthorized
- `404` - Not Found
- `500` - Internal Server Error

## Migrating to the New Sourcegraph API
Copy link
Member

@bobheadxi bobheadxi Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we put this at the top?

Copy link
Contributor Author

@julialeex julialeex Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think having this at the very end of the page makes the flow better? I added a new callout at the top; however, let me know if you still want this section at the top.

Copy link
Member

@bobheadxi bobheadxi Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think having the migration at the top sets the expectations right when you land on the page, that we want you to migrate - a link is easy to miss/ignore


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.

![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"`

### 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.
Copy link
Member

@bobheadxi bobheadxi Feb 26, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you also try with just this prompt? Curious if it works also 😁

Migrate the Deep Search API calls in this project from the deprecated /.api/deepsearch/v1 endpoints to the new Sourcegraph /api/deepsearch.v1.Service/ endpoints.

The main file to update is src/sourcegraph/deep-search/index.ts. Use the attached OpenAPI schema (@sourcesourcegraph-openapi.json) as the specification for the new API.

Also, did you try running the extension to make sure the migrated changes work correctly? happy to pair to try that out

Copy link
Contributor Author

@julialeex julialeex Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just tried this prompt, down to pair later

Copy link
Member

@stefanhengl stefanhengl Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we tell them to point the agent to this doc page to? Meaning, should we treat this page as one giant migration prompt for humans and agents?

Copy link
Member

@bobheadxi bobheadxi Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah, though i worry it's a bit large since it includes the old schema

we should also remove the preview status of this page too, since it's currently hidden by default, to make it easier for the agent to access. with the migration guide on top and all the warnings i think it's fine for it to be discoverable


### 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` |

### 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`)
Copy link
Member

@stefanhengl stefanhengl Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not clear to me what that means? Why is it /-/? We are not switching to resource names but to rpc / operations on resources.

- [ ] 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**.
4 changes: 3 additions & 1 deletion docs/deep-search/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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

Expand Down