feat/externalapi: Add API migration guide

docs/deep-search/api.mdx

@@ -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
@@ -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
@@ -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
+
+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.
+
+### 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`)
+- [ ] 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**.

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