From 43c6dd2592392a1f4fdc1da520c6c80f6b33afc6 Mon Sep 17 00:00:00 2001 From: Robert Lin Date: Sun, 22 Feb 2026 16:18:22 -0500 Subject: [PATCH 1/3] api: prune GraphQL docs, add warnings, add new API --- docs/api/graphql/examples.mdx | 13 - docs/api/graphql/index.mdx | 27 +- .../managing-code-insights-with-api.mdx | 374 ------------------ .../managing-search-contexts-with-api.mdx | 195 --------- docs/api/graphql/search.mdx | 26 -- docs/api/index.mdx | 34 +- docs/api/stream-api/index.mdx | 7 +- docs/code-insights/references/index.mdx | 1 - .../how-to/create-search-context-graphql.mdx | 112 ------ docs/code-search/how-to/index.mdx | 2 +- docs/code-search/working/search-contexts.mdx | 4 - docs/deep-search/api.mdx | 299 -------------- docs/deep-search/index.mdx | 12 +- .../getting-started/github-vs-sourcegraph.mdx | 2 +- docs/tutorials/index.mdx | 6 +- src/data/navigation.ts | 12 +- src/data/redirects.ts | 49 ++- 17 files changed, 99 insertions(+), 1076 deletions(-) delete mode 100644 docs/api/graphql/examples.mdx delete mode 100644 docs/api/graphql/managing-code-insights-with-api.mdx delete mode 100644 docs/api/graphql/managing-search-contexts-with-api.mdx delete mode 100644 docs/api/graphql/search.mdx delete mode 100644 docs/code-search/how-to/create-search-context-graphql.mdx delete mode 100644 docs/deep-search/api.mdx diff --git a/docs/api/graphql/examples.mdx b/docs/api/graphql/examples.mdx deleted file mode 100644 index 63e8712b5..000000000 --- a/docs/api/graphql/examples.mdx +++ /dev/null @@ -1,13 +0,0 @@ -# Sourcegraph GraphQL API examples - -This page demonstrates a few example GraphQL queries for the [Sourcegraph GraphQL API](/api/graphql/). For help with the API, you can use `Ctrl + space` to trigger tooltips. - -| GraphQL query | Description | Example use case | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Get the contents of a file on the default branch]() | Returns the file contents. | Quickly fetch file contents without cloning a repository or hitting your code host API (which is usually slower or more rate-limited than Sourcegraph). | -| [Perform a search query and get results]() | Returns the search result metadata (whether or not the search result limit was hit, if the search timed out, etc.) and the actual results of the search query, which can be one of three types: Repository, FileMatch, or CommitSearchResult. | Search for a new framework or API that you are using (or have deprecated) and determine all of the repositories that haven't yet been migrated. | -| [Compare 2 commits]() | Returns a list of changes between 2 commits. | Scan diffs between the old and new versions of a deployed service for changes that might indicate an incompatibility (e.g., in a service discovery manifest). | -| [List the first 1,000 repositories]() | Returns the name, description, and URL of the first 1,000 repositories on the Sourcegraph server (in order of their creation date). | - | -| [List all files in a repository]() | Returns every file in the repository, its path (relative to the repository root), whether or not it is a directory or plain file, and what the URL path to the file is. | List all of the files in each repository of your organization (when combined with the "List the first 1000 repositories" example above) to determine which of your repositories are missing important files like READMEs, LICENSEs, and Dockerfiles. | -| [List the languages used in a repository]() | Returns the primary language of the repository as well as a list of all the languages used in the repository. | List all of the languages in each repository of your organization (when combined with the "List the first 1000 repositories" example above) to determine how many repos use each language across your entire organization. | -| [Current month's active users]() | Returns the current month's active users (total count and usernames) and their last active time. | - | diff --git a/docs/api/graphql/index.mdx b/docs/api/graphql/index.mdx index 2b300af90..b0014510c 100644 --- a/docs/api/graphql/index.mdx +++ b/docs/api/graphql/index.mdx @@ -2,19 +2,20 @@ seoPriority: 0.8 --- -# Sourcegraph GraphQL API +# Sourcegraph GraphQL debug API -The Sourcegraph GraphQL API is a rich API that exposes data related to the code available on a Sourcegraph instance. +The Sourcegraph GraphQL API is a debug API that can be used for Sourcegraph diagnostics and simple tooling. -The Sourcegraph GraphQL API supports the following types of queries: - -- Full-text and regexp code search -- Rich git-level metadata, including commits, branches, blame information, and file tree data -- Repository and user metadata + + The GraphQL API is intended primarily for debugging use cases. It does not + have backwards-compatibility guarantees, and may not remain stable across + Sourcegraph releases. For more information, please refer to the [Sourcegraph + API page](/api). + - The API is under active development. Backwards compatibility will be - maintained in most cases. + For code search integrations, we currently recommend using the [stream + search API](/api/stream-api/). ## Quickstart @@ -75,10 +76,6 @@ always uses the latest version of the API). To access the documentation, click **Docs** on the right-hand side of the API console page. -### Search - -See [additional documentation about search GraphQL API](/api/graphql/search). - ### Sudo access tokens Site admins may create access tokens with the special `site-admin:sudo` scope, which allows the holder to perform any action as any other user. @@ -114,10 +111,6 @@ https://sourcegraph.com/.api/graphql i.e. you just need to send the `Authorization` header and a JSON object like `{"query": "my query string", "variables": {"var1": "val1"}}`. -## Examples - -See "[Sourcegraph GraphQL API examples](/api/graphql/examples)". - ## Cost Limits To ensure system performance and stability, configurable GraphQL query cost limitations have been implemented. This feature is crucial for preventing resource exhaustion due to extensive or overly complex queries. The default configuration looks as follows, and can be modified in site configuration: diff --git a/docs/api/graphql/managing-code-insights-with-api.mdx b/docs/api/graphql/managing-code-insights-with-api.mdx deleted file mode 100644 index aaaa122d8..000000000 --- a/docs/api/graphql/managing-code-insights-with-api.mdx +++ /dev/null @@ -1,374 +0,0 @@ -# Managing Code Insights with the API - -Learn how to manage [Code Insights](/code-insights/) on private Sourcegraph instances with the API. If you haven't used the API before, learn more about [the GraphQL API and how to use it](/api/graphql/). - -This page is meant as a guide for common use cases. You can find all of GraphQL documentation in the [API Console](/api/graphql/#api-console). - -## Prerequisites - -The Code Insights GraphQL API is available on Sourcegraph versions 3.35.1+. - -Note: If Code Insights setting storage is enabled, (`ENABLE_CODE_INSIGHTS_SETTINGS_STORAGE:true`) any changes made via the API will be periodically overwritten by insights stored in settings. This is an unlikely scenario. - -## Permissions and visibility - -Note: there are no separate read/write permissions at this time, so if a user has permission to view an insight they can also edit and delete it. - -When a user creates a Code Insight, that user will automatically be granted permission to view that insight. Besides this one case of insight-level permissions, all permissions exist on [dashboards](/code-insights/explanations/viewing-code-insights#insights-dashboards). This means that in order for another user to view an insight via the API, that insight must first be attached to a dashboard with either organization or global permissions. - -See [Managing Dashboards](#managing-dashboards) below for more information. - -## Just-in-time vs persisted insights - -Some insights generate and persist time series data, while others calculate their data just-in-time on page load. Currently, line chart insights will be persisted, while the language statistics pie charts that run over a single repository will be generated just-in-time. - -## Creating a persisted insight - -To create a Code Insight that will generate and persist time series data, use the mutation below. - -Important: Specify the list of repositories that the insight should run over in `repositoryScope.repositories` or leave it empty to specify that the query should be run across all repositories. - -```gql -mutation CreateLineChartSearchInsight($input: LineChartSearchInsightInput!) { - createLineChartSearchInsight(input: $input) { - view { - id - } - } -} -``` - -Example variables: - -```json -{ - "input": { - "options": { - "title": "Javascript to Typescript migration" - }, - "dataSeries": [ - { - "query": "lang:javascript", - "options": { - "label": "javascript", - "lineColor": "#6495ED" - }, - "repositoryScope": { - "repositories": [] - }, - "timeScope": { - "stepInterval": { - "unit": "MONTH", - "value": 1 - } - } - }, - { - "query": "lang:typescript", - "options": { - "label": "typescript", - "lineColor": "#DE3163" - }, - "repositoryScope": { - "repositories": [] - }, - "timeScope": { - "stepInterval": { - "unit": "MONTH", - "value": 1 - } - } - } - ] - } -} -``` - -## Creating a pie chart insight - -Pie chart insights show language usage across a specified repository. Because this type of chart has not yet been generalized to other use cases, the `query` field in the input is not used. To create one, use the mutation below. - -```gql -mutation CreatePieChartSearchInsight($input: PieChartSearchInsightInput!) { - createPieChartSearchInsight(input: $input) { - view { - id - } - } -} -``` - -Example variables: - -```json -{ - "input": { - "query": "", - "repositoryScope": { - "repositories": ["sourcegraph/sourcegraph"] - }, - "presentationOptions": { - "title": "Language usage for Sourcegraph", - "otherThreshold": 0.3 - } - } -} -``` - -## Reading a single Code Insight - -Use the query below to read a Code Insight by `id`. `filters` are optional, and if provided will filter the aggregated time series to specific repositories. - -You can find an insight's `id` if you visit the edit page for the insight. The edit page URL will be of the form `https://sourcegraph.yourcompany.com/insights/edit/aW5zaWdodF92aWV3OiIyM2hiYzNNclB2bDBtajlLTTZTUlBpWVlhZWQi?dashboardId=all` where the `id` is `aW5zaWdodF92aWV3OiIyM2hiYzNNclB2bDBtajlLTTZTUlBpWVlhZWQi`. Alternatively, you can list all insights using this graphQL API. - -Notes on the return object: - -- `dataSeries.status` is useful to guage the progress of the series point generation. More information can be found in the [API Console Documentation](/api/graphql/#api-console) -- The `dataSeries`, `dataSeriesDefinitions` and `seriesPresentation` arrays each store different information about the same series. The `seriesId` field on each can be used to match them up. - - `dataSeries` contains the calculated time series data - - `dataSeriesDefinitions` contains the definition for the series, such as the query and time interval - - `seriesPresentation` contains presentation options such as the title and line color - -```gql -query InsightViews($id: ID, $filters: InsightViewFiltersInput) { - insightViews(id: $id, filters: $filters) { - nodes { - id - dataSeries { - label - points { - dateTime - value - } - status { - pendingJobs - completedJobs - failedJobs - backfillQueuedAt - } - } - dataSeriesDefinitions { - ... on SearchInsightDataSeriesDefinition { - seriesId - query - repositoryScope { - repositories - } - timeScope { - ... on InsightIntervalTimeScope { - unit - value - } - } - } - } - presentation { - ... on LineChartInsightViewPresentation { - title - seriesPresentation { - seriesId - label - color - } - } - ... on PieChartInsightViewPresentation { - title - otherThreshold - } - } - } - } -} -``` - -Example variables: - -```json -{ - "id": "aW5zaWdodF92aWV3OiIyMkVIR2pXOTFkSzNOanpmM2hyWnU3WDJwMlgi", - "filters": { - "includeRepoRegex": "sourcegraph/sourcegraph", - "excludeRepoRegex": "sourcegraph/handbook" - } -} -``` - -## List Code Insights - -The query below will list all of the Code Insights that you can see based on [permissions](#permissions-and-visibility). The query and return object is the same as for reading a single Code Insight. All input parameters are optional, and can be used for cursor-based pagination and repository filtering. - -```gql -query InsightViews( - $first: Int - $after: String - $filters: InsightViewFiltersInput -) { - insightViews(first: $first, after: $after, filters: $filters) { - nodes { - id - } - pageInfo { - endCursor - hasNextPage - } - } -} -``` - -Example variables: - -```json -{ - "first": 10, - "after": "aW5zaWdodF92aWV3OiIyM1l3WHpmSkVhY2Juc0RvWVE5N0FtRU9Wbkki" -} -``` - -## Updating a Code Insight - -Below is a GraphQL mutation that updates an existing Code Insight. The format is almost identical to the creation mutation, except that it now takes an `id`. The input object must be complete as it will completely overwrite the existing Code Insight. - -Important: series are added, updated, and deleted from the insight as follows: - -- A `dataSeries` without a `seriesId` or with an unknown `seriesId` will be treated as a new series and be added to the insight. -- A `dataSeries` with a `seriesId` that already exists for this insight will be updated in place. -- Any `dataSeries` that previously existed on the insight but are NOT included in the update **will be deleted.** - -```gql -mutation UpdateLineChartSearchInsight( - $id: ID! - $input: UpdateLineChartSearchInsightInput! -) { - updateLineChartSearchInsight(id: $id, input: $input) { - view { - id - } - } -} -``` - -Example variables: - -This is an example of updating the Code Insight from the creation mutation example. This updates `options.title`, the `dataSeries.timeScope.stepInterval` of the existing javascript series, and deletes the typescript series by omiting it. - -```json -{ - "id": "[INSIGHT_ID]", - "input": { - "presentationOptions": { - "title": "Javascript weekly" - }, - "viewControls": { - "seriesDisplayOptions": {}, - "filters": {} - }, - "dataSeries": [ - { - "seriesId": "[SERIES_ID]", - "query": "lang:javascript", - "options": { - "label": "javascript", - "lineColor": "#6495ED" - }, - "repositoryScope": { - "repositories": [] - }, - "timeScope": { - "stepInterval": { - "unit": "WEEK", - "value": 1 - } - } - } - ] - } -} -``` - -## Deleting a Code Insight - -Below is a GraphQL mutation that deletes a Code Insight by ID. - -```gql -mutation DeleteInsightView($id: ID!) { - deleteInsightView(id: $id) { - alwaysNil - } -} -``` - -Example variables: - -```json -{ - "id": "aW5zaWdodF92aWV3OiIyMkVIR2pXOTFkSzNOanpmM2hyWnU3WDJwMlgi" -} -``` - -## Managing dashboards - -### Creating a dashboard - -Below is a GraphQL mutation that creates a dashboard with global permissions, meaning all users can view this dashboard and all of its insights. - -```gql -mutation CreateInsightsDashboard($input: CreateInsightsDashboardInput!) { - createInsightsDashboard(input: $input) { - dashboard { - id - } - } -} -``` - -Example variables: - -```json -{ - "input": { - "title": "Global insights dashboard", - "grants": { - "users": [], - "organizations": [], - "global": true - } - } -} -``` - -### Adding and removing Code Insights from a dashboard - -Use the following mutations to add and remove insights from dashboards: - -```gql -mutation AddInsightViewToDashboard($input: AddInsightViewToDashboardInput!) { - addInsightViewToDashboard(input: $input) { - dashboard { - id - } - } -} -``` - -```gql -mutation RemoveInsightViewFromDashboard( - $input: RemoveInsightViewFromDashboardInput! -) { - removeInsightViewFromDashboard(input: $input) { - dashboard { - id - } - } -} -``` - -Example variables: - -```json -{ - "input": { - "insightViewId": "aW5zaWdodF92aWV3OiIyMkVIR2pXOTFkSzNOanpmM2hyWnU3WDJwMlgi", - "dashboardId": "ZGFzaGJvYXJkOnsiSWRUeXBlIjoiY3VzdG9tIiwiQXJnIjoxNDV9" - } -} -``` diff --git a/docs/api/graphql/managing-search-contexts-with-api.mdx b/docs/api/graphql/managing-search-contexts-with-api.mdx deleted file mode 100644 index 1734ea750..000000000 --- a/docs/api/graphql/managing-search-contexts-with-api.mdx +++ /dev/null @@ -1,195 +0,0 @@ -# Managing search contexts with the API - -Learn how to manage [search contexts](/code-search/working/search-contexts) on private Sourcegraph instances with the API. If you haven't used the API before, learn more about [the GraphQL API and how to use it](/api/graphql/). - -## Prerequisites - -- Search contexts and search context management are [enabled in global settings](/code-search/features#search-contexts). - -### Permissions and visibility overview - -To read and write search contexts through the API you will need appropriate permissions. The permissions are determined based on the individual search context's namespace and its visibility (private or public). - -**Read** permissions (view contents, use in searches): - -- **Public** search contexts are available to all users - - On Sourcegraph.com, unauthenticated visitors can also see public search contexts -- **Private** search contexts - - With user namespace: only available to the user - - With organization namespace: only available to users in the organization - - With global (instance-level) namespace: only available to site-admins - -**Write** permissions (create, update, delete): - -- Site-admins have write access to all public search contexts and all global (instance-level) search contexts -- A regular user has write access to its search contexts and its organization's search contexts - -## Create a context - -Below is a GraphQL query that creates a new search context. To populate the `searchContext.namespace` property, you will have to query the API beforehand to retrieve the user or organization ID. - -If `searchContext.namespace` is not specified or `null` then the context is created in the global (instance-level) namespace. -To specify search context repositories you will need their ids. Similar to the `namespace` property you will need to retrieve them from the API before creating the context. - -```gql -mutation CreateSearchContext( - $searchContext: SearchContextInput! - $repositories: [SearchContextRepositoryRevisionsInput!]! -) { - createSearchContext( - searchContext: $searchContext - repositories: $repositories - ) { - id - spec - } -} -``` - -Example variables: - -```json -{ - "searchContext": { - "name": "MySearchContext", - "description": "A description of my search context", - "namespace": "user-id", - "public": true - }, - "repositories": [ - { - "repositoryID": "repo-id", - "revisions": ["main", "branch-1"] - } - ] -} -``` - -## Read a single context - -Below is a GraphQL query that fetches a single search context by ID. - -```gql -query ReadSearchContext($id: ID!) { - node(id: $id) { - ... on SearchContext { - id - spec - } - } -} -``` - -Example variables: - -```json -{"id": "search-context-id"} -``` - -## List available contexts - -Below is a GraphQL query that fetches all available search contexts and allows filtering by multiple parameters. The `namespaces` array allows filtering by one or multiple namespace ids (user or organization id). -To include global (instance-level) contexts you can specify `null` as one of the ids. If the `namespaces` array is omitted or empty, then no filtering by namespace is applied and all available contexts are returned. -The `query` parameter allows filtering by search context spec. - -```gql -query ListSearchContexts( - $first: Int! - $after: String - $query: String - $namespaces: [ID] - $orderBy: SearchContextsOrderBy - $descending: Boolean -) { - searchContexts( - first: $first - after: $after - query: $query - namespaces: $namespaces - orderBy: $orderBy - descending: $descending - ) { - nodes { - id - spec - } - pageInfo { - hasNextPage - endCursor - } - totalCount - } -} -``` - -Example variables: - -Query with these variables will return the first 50 search contexts ordered by search context `updatedAt` timestamp ascending. The results will be filtered to include only -global contexts (`null`), `organization1` contexts (`organization1-id`), and `user1` contexts (`user1-id`). - -```json -{ - "first": 50, - "namespaces": [null, "organization1-id", "user1-id"], - "orderBy": "SEARCH_CONTEXT_UPDATED_AT" -} -``` - -## Update a context - -Below is a GraphQL query that updates an existing search context. You cannot update a search context namespace. -You have to provide the full search context and all repositories with revisions you want to keep on each update. - -```gql -mutation UpdateSearchContext( - $id: ID! - $searchContext: SearchContextEditInput! - $repositories: [SearchContextRepositoryRevisionsInput!]! -) { - updateSearchContext( - id: $id - searchContext: $searchContext - repositories: $repositories - ) { - id - spec - } -} -``` - -Example variables: - -```json -{ - "id": "search-context-id-to-update", - "searchContext": { - "name": "MyUpdatedSearchContext", - "description": "An updated description of my search context", - "public": false - }, - "repositories": [ - { - "repositoryID": "repo-id", - "revisions": ["main", "branch-1", "branch-2"] - } - ] -} -``` - -## Delete a context - -Below is a GraphQL query that deletes a search context by ID. - -```gql -mutation DeleteSearchContext($id: ID!) { - deleteSearchContext(id: $id) { - alwaysNil - } -} -``` - -Example variables: - -```json -{"id": "search-context-id-to-delete"} -``` diff --git a/docs/api/graphql/search.mdx b/docs/api/graphql/search.mdx deleted file mode 100644 index d55f71f8c..000000000 --- a/docs/api/graphql/search.mdx +++ /dev/null @@ -1,26 +0,0 @@ -# Sourcegraph search GraphQL API - -This page adds some additional depth and context to Sourcegraph's search GraphQL API. - -## Search Pagination in GraphQL API - -Sourcegraph does not support pagination for search results when using the GraphQL search API due to the dynamic nature of search queries. The order of results may vary each time you run a search, making traditional pagination unreliable. - -Instead, we recommend using the [stream search API](/api/stream-api/) for scenarios where you need to run a long query and receive continuous results. This enables you to execute long-running queries. - -## `src` CLI usage (easier than GraphQL) - -Putting together a comprehensive GraphQL search query can be difficult. For this reason, we created the [`src` CLI tool](https://sourcegraph.com/github.com/sourcegraph/src-cli) which allows you to simply run a search query and get the JSON results without constructing the GraphQL query: - -``` -export SRC_ENDPOINT=https://sourcegraph.com -export SRC_ACCESS_TOKEN=secret - -src search -json 'repo:pallets/flask error' -``` - -You can then consume the JSON output directly, add `--get-curl` to get a `curl` execution line, and more. See [the `src` CLI tool](https://sourcegraph.com/github.com/sourcegraph/src-cli) for more details. - -## Incomplete search results when using Graphql - -Sometimes, users find discrepancies in the number of results returned on UI compared to Graphql for the same query. This can be avoided by adding `"count:all" ` to the query used in Graphql. This ensures all the matching records are being fetched via Graphql. diff --git a/docs/api/index.mdx b/docs/api/index.mdx index 34b1004d4..287d82af4 100644 --- a/docs/api/index.mdx +++ b/docs/api/index.mdx @@ -1,8 +1,30 @@ -# API Documentation +# Sourcegraph API -Sourcegraph exposes the following APIs: +Starting in Sourcegraph 7.0, a new versioned external API is being introduced for custom integrations. The currently available API surface can be seen in `/api-reference` (e.g. `https://sourcegraph.example.com/api-reference`). From this page, integrators can view the available operations and download the OpenAPI schema. We are committed to supporting integrations built on top of these new APIs with backwards compatibility and migration assistance for breaking changes. -- [Sourcegraph GraphQL API](/api/graphql/), for accessing data stored or computed by Sourcegraph -- [Sourcegraph Analytics API](/analytics/api/), for accessing your Sourcegraph Analytics data -- [Sourcegraph Stream API](/api/stream-api/), for consuming search results as a stream of events -- [Sourcegraph MCP Server](/api/mcp/), for connecting AI agents and applications to Sourcegraph's code search capabilities + + 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. + + +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 +- [Sourcegraph MCP server](/api/mcp/), for connecting AI agents and applications to Sourcegraph's code search capabilities +- [Sourcegraph Analytics API](/analytics/api/), for accessing your Sourcegraph Analytics data + +For diagnostics use cases, the [Sourcegraph GraphQL debug API](/api/graphql/) is also available without any compatibility guarauntees. + + +

The Sourcegraph GraphQL API is gradually being phased out as an API for + external integrations starting in Sourcegraph 7.0. The GraphQL API will + remain available, but it does not have any compatibility guarantees, unlike + the new API available in Sourcegraph 7.0 at `/api-reference`.

+ +

If you have a + use case that is not currently served by the new Sourcegraph API, please + reach out at support@sourcegraph.com.

+ + diff --git a/docs/api/stream-api/index.mdx b/docs/api/stream-api/index.mdx index 32c3d16cb..86261c829 100644 --- a/docs/api/stream-api/index.mdx +++ b/docs/api/stream-api/index.mdx @@ -2,11 +2,10 @@ seoPriority: 1.0 --- -# Sourcegraph Stream API +# Sourcegraph streaming search API -With the Stream API you can consume search results and related metadata as -a stream of events. The Sourcegraph UI calls the Stream API for all interactive searches. -Compared to our [GraphQL API](/api/graphql/), it offers shorter times to first results and +With the streaming search API you can consume search results and related metadata as +a stream of events. The Sourcegraph UI calls the streaming search API for all interactive searches. It offers shorter times to first results and supports running exhaustive searches returning a large volume of results without putting pressure on the backend. diff --git a/docs/code-insights/references/index.mdx b/docs/code-insights/references/index.mdx index e60269b27..f063348db 100644 --- a/docs/code-insights/references/index.mdx +++ b/docs/code-insights/references/index.mdx @@ -6,6 +6,5 @@ The following is a list of reference documents for Code Insights: - [Common reasons code insights may not match search results](/code-insights/references/common-reasons-code-insights-may-not-match-search-results) - [Incomplete data points](/code-insights/references/incomplete-data-points) - [Licensing and limited access](/code-insights/references/license) -- [Managing code insights with the API](/api/graphql/managing-code-insights-with-api) - [Requirements](/code-insights/references/requirements) - [Code Insight repository scope](/code-insights/references/repository-scope) diff --git a/docs/code-search/how-to/create-search-context-graphql.mdx b/docs/code-search/how-to/create-search-context-graphql.mdx deleted file mode 100644 index 1cb153cb2..000000000 --- a/docs/code-search/how-to/create-search-context-graphql.mdx +++ /dev/null @@ -1,112 +0,0 @@ -# How to create a search context with the GraphQL API - -This document will take you through how to create a search context for your user with Sourcegraph's GraphQL API. - -## Prerequisites - -- This document assumes that you have a private Sourcegraph instance -- Assumes you are creating a Private search context with a user namespace which is only available to the user -- For more information on available permissions and ways to alter the following examples, please see [Managing search contexts with api - permissions and visibility overview](/api/graphql/managing-search-contexts-with-api#permissions-and-visibility-overview) - -## Steps to create - -Step 1: Add to global configuration (must be site-admin): - -```json -{ - "experimentalFeatures": { - "showSearchContext": true - } -} -``` - -Step 2: Make sure you have added code hosts: [Add repositories (from code hosts) to Sourcegraph](/admin/repo/add) - -Step 3: Follow the steps to [Generate an access token for GraphQL](/api/graphql#quickstart) if you already haven't - -Step 4: Navigate to the API console on your instance, replacing sourcegraph.example with the correct string for your instance URL. - -- Example: `https://sourcegraph.example.com/api/console` - -Step 5: Query your user namespace id and save the value - -- The name: will be your Sourcegraph instance login name - Example: - -```json -query { - namespaceByName(name: "my_login_name") { - id - } -} -``` - -Step 6: Query your desired repo id and save the value. - -- It should be whatever the URL is for that repo. - Example: - -```json -query { - repository(name: "github.com/org_name/repo_name") { - id - } -} -``` - -Step 7: Take the values from steps 5 and 6 and put them into the example variables from our docs here: - -- [Managing search contexts with API - Create a context](/api/graphql/managing-search-contexts-with-api#create-a-context) - -Run this with no changes: - -```json -mutation CreateSearchContext( - $searchContext: SearchContextInput! - $repositories: [SearchContextRepositoryRevisionsInput!]! -) { - createSearchContext(searchContext: $searchContext, repositories: $repositories) { - id - spec - } -} -``` - -Then in the Query Variables section on the bottom of the GraphQL API page, use this variables example, changing at least the name and description: - -```json -{ - "searchContext": { - "name": "MySearchContext", - "description": "A description of my search context", - "namespace": "user-id-from-step-5", - "public": true - }, - "repositories": [ - { - "repositoryID": "repo-id-from-step-6", - "revisions": ["main", "branch-1"] - } - ] -} -``` - -Step 8: Run the query, that should create a search context and the output will look something like: - -```json -{ - "data": { - "createSearchContext": { - "id": "V2VhcmNoQ29udGV4dDoiQGdpc2VsbGUvTXlTZWFyY2hDb250ZXh0MiI=", - "spec": "@my_login_name/MySearchContext" - } - } -} -``` - -Step 9: Go to the main search page and you should see the new Search context as part of the search bar! - -## Further resources - -- [Using and creating search contexts](/code-search/working/search-contexts) -- [Sourcegraph - Administration Config](/admin) diff --git a/docs/code-search/how-to/index.mdx b/docs/code-search/how-to/index.mdx index e6e4c49dd..3b6d68f18 100644 --- a/docs/code-search/how-to/index.mdx +++ b/docs/code-search/how-to/index.mdx @@ -1,4 +1,4 @@ # How-to guides - [Switch from Oracle OpenGrok to Sourcegraph](/code-search/how-to/opengrok) -- [How to create a search context with the GraphQL API](/code-search/how-to/create-search-context-graphql) +- [How to create a search context with the GraphQL API](/api/graphql) diff --git a/docs/code-search/working/search-contexts.mdx b/docs/code-search/working/search-contexts.mdx index 397487988..6e5bbc766 100644 --- a/docs/code-search/working/search-contexts.mdx +++ b/docs/code-search/working/search-contexts.mdx @@ -139,7 +139,3 @@ If you're an admin, to enable this feature for all users set `experimentalFeatur ### Creating search contexts from search results You can now create new search contexts right from the search results page. Once you've enabled query-based search contexts you'll see a Create context button above the search results. - -## Managing search contexts with the API - -Learn how to [manage search contexts with the GraphQL API](/api/graphql/managing-search-contexts-with-api). diff --git a/docs/deep-search/api.mdx b/docs/deep-search/api.mdx deleted file mode 100644 index 602961421..000000000 --- a/docs/deep-search/api.mdx +++ /dev/null @@ -1,299 +0,0 @@ ---- -preview: true ---- - -# Deep Search API - -

- Programmatic access to Sourcegraph's agentic code search capabilities. -

- - - The **experimental** Deep Search API is available in Sourcegraph version - 6.7+. This API allows you to programmatically create and manage Deep Search - conversations. - - We are looking for feedback on the API and its usage. Please let us know your - thoughts and suggestions. - - - -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 - -All API requests require authentication using a Sourcegraph access token. You can generate an access token from your user settings. - -```bash -# Set your access token -export SRC_ACCESS_TOKEN="your-token-here" -``` - -## Base URL - -All Deep Search API endpoints are prefixed with `/.api/deepsearch/v1` and require the `X-Requested-With` header to identify the client: - -```bash -curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H "Authorization: token $SRC_ACCESS_TOKEN" \ - -H 'X-Requested-With: my-client 1.0.0' -``` - - - The `X-Requested-With` header is required and should include your client - name and version number. - - -## Creating conversations - -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. - -Create a new Deep Search conversation by asking a question: - -```bash -curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H "Authorization: token $SRC_ACCESS_TOKEN" \ - -H 'X-Requested-With: my-client 1.0.0' \ - -d '{"question":"Does github.com/sourcegraph/sourcegraph have a README?"}' -``` - -The API returns a conversation object with the question initially in `processing` status: - -```json -{ - "id": 140, - "questions": [ - { - "id": 163, - "conversation_id": 140, - "question": "Does github.com/sourcegraph/sourcegraph have a README?", - "created_at": "2025-09-24T08:14:06Z", - "updated_at": "2025-09-24T08:14:06Z", - "status": "processing", - "turns": [ - { - "reasoning": "Does github.com/sourcegraph/sourcegraph have a README?", - "timestamp": 1758701646, - "role": "user" - } - ], - "stats": { - "time_millis": 0, - "tool_calls": 0, - "total_input_tokens": 0, - "cached_tokens": 0, - "cache_creation_input_tokens": 0, - "prompt_tokens": 0, - "completion_tokens": 0, - "total_tokens": 0, - "credits": 0 - }, - "suggested_followups": null - } - ], - "created_at": "2025-09-24T08:14:06Z", - "updated_at": "2025-09-24T08:14:06Z", - "user_id": 1, - "read_token": "caebeb05-7755-4f89-834f-e3ee4a6acb25", - "share_url": "https://your-sourcegraph-instance.com/deepsearch/caebeb05-7755-4f89-834f-e3ee4a6acb25" -} -``` - -To get the completed answer, poll the conversation endpoint: - -```bash -curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140' \ - -H 'Accept: application/json' \ - -H "Authorization: token $SRC_ACCESS_TOKEN" \ - -H 'X-Requested-With: my-client 1.0.0' -``` - -Once processing is complete, the response will include the answer: - -```json -{ - "id": 140, - "questions": [ - { - "id": 163, - "conversation_id": 140, - "question": "Does github.com/sourcegraph/sourcegraph have a README?", - "created_at": "2025-09-24T08:14:06Z", - "updated_at": "2025-09-24T08:14:15Z", - "status": "completed", - "title": "GitHub README check", - "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.", - "sources": [ - { - "type": "Repository", - "link": "/github.com/sourcegraph/sourcegraph", - "label": "github.com/sourcegraph/sourcegraph" - } - ], - "stats": { - "time_millis": 6369, - "tool_calls": 1, - "total_input_tokens": 13632, - "cached_tokens": 12359, - "cache_creation_input_tokens": 13625, - "prompt_tokens": 11, - "completion_tokens": 156, - "total_tokens": 13694, - "credits": 2 - }, - "suggested_followups": [ - "What information does the README.md file contain?", - "Are there other important documentation files in the repository?" - ] - } - ], - "created_at": "2025-09-24T08:14:06Z", - "updated_at": "2025-09-24T08:14:15Z", - "user_id": 1, - "read_token": "caebeb05-7755-4f89-834f-e3ee4a6acb25", - "viewer": {"is_owner": true}, - "quota_usage": { - "total_quota": 0, - "quota_limit": -1, - "reset_time": "2025-10-01T00:00:00Z" - }, - "share_url": "https://sourcegraph.test:3443/deepsearch/caebeb05-7755-4f89-834f-e3ee4a6acb25" -} -``` - -## Adding follow-up questions - -Continue a conversation by adding follow-up questions. The `conversation_id` in the request body must match the conversation ID in the URL: - -```bash -curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140/questions' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H "Authorization: token $SRC_ACCESS_TOKEN" \ - -H 'X-Requested-With: my-client 1.0.0' \ - -d '{"conversation_id":140,"question":"What does the README file contain?"}' -``` - -## Listing conversations - -Get all your conversations with optional filtering: - -```bash -# List all conversations -curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1' \ - -H 'Accept: application/json' \ - -H "Authorization: token $SRC_ACCESS_TOKEN" \ - -H 'X-Requested-With: my-client 1.0.0' - -# List with pagination and filtering -curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1?page_first=10&sort=created_at' \ - -H 'Accept: application/json' \ - -H "Authorization: token $SRC_ACCESS_TOKEN" \ - -H 'X-Requested-With: my-client 1.0.0' -``` - -Available query parameters: - -- `filter_id` - Filter by conversation ID -- `filter_user_id` - Filter by user ID -- `filter_read_token` - Access conversations via read token (requires sharing to be enabled) -- `filter_is_starred` - Filter by starred conversations (`true` or `false`) -- `page_first` - Number of results per page -- `page_after` - Pagination cursor -- `sort` - Sort order: `id`, `-id`, `created_at`, `-created_at`, `updated_at`, `-updated_at` (default: `-updated_at`) - -## Managing conversations - -**Get a specific conversation:** - -```bash -curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140' \ - -H 'Accept: application/json' \ - -H "Authorization: token $SRC_ACCESS_TOKEN" \ - -H 'X-Requested-With: my-client 1.0.0' -``` - -**Delete a conversation:** - -```bash -curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140' \ - -X DELETE \ - -H "Authorization: token $SRC_ACCESS_TOKEN" \ - -H 'X-Requested-With: my-client 1.0.0' -``` - -**Cancel a processing question:** - -```bash -curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1/140/questions/163/cancel' \ - -X POST \ - -H 'Accept: application/json' \ - -H "Authorization: token $SRC_ACCESS_TOKEN" \ - -H 'X-Requested-With: my-client 1.0.0' -``` - -## Accessing conversations via read tokens - -You can retrieve a conversation using its read token with the `filter_read_token` query parameter. - -Each conversation includes a `read_token` field that allows accessing the conversation. -The read token is also visible in the web client URL and in the `share_url` field. -Note that you can only access other users' conversations via read tokens if sharing is enabled on your Sourcegraph instance. - -```bash -curl 'https://your-sourcegraph-instance.com/.api/deepsearch/v1?filter_read_token=5d9aa113-c511-4687-8b71-dbc2dd733c03' \ - -H 'Accept: application/json' \ - -H "Authorization: token $SRC_ACCESS_TOKEN" \ - -H 'X-Requested-With: my-client 1.0.0' -``` - -## Response structure - -**Conversation object:** - -- `id` - Unique conversation identifier -- `questions` - Array of questions and answers -- `created_at`/`updated_at` - Timestamps -- `user_id` - Owner user ID -- `read_token` - Token for sharing access -- `share_url` - URL for sharing the conversation - -**Question object:** - -- `id` - Unique question identifier -- `question` - The original question text -- `status` - Processing status: `pending`, `processing`, `completed` -- `error` - Error details if the question processing encountered an issue -- `title` - Generated title for the question -- `answer` - The AI-generated answer (when completed) -- `sources` - Array of sources used to generate the answer -- `suggested_followups` - Suggested follow-up questions - -If a question fails to process, the `status` will be `completed` and the `error` field will be populated, for example: - -```json -{ - "status": "completed", - "error": { - "title": "Token limit reached", - "kind": "TokenLimitExceeded", - "message": "The search exceeded the maximum token limit...", - "details": "Additional context about the error" - } -} -``` - -## Error handling - -The API returns standard HTTP status codes with descriptive error messages: - -- `200` - Success -- `202` - Accepted (for async requests) -- `400` - Bad Request -- `401` - Unauthorized -- `404` - Not Found -- `500` - Internal Server Error diff --git a/docs/deep-search/index.mdx b/docs/deep-search/index.mdx index 500a873f6..ebf56cef9 100644 --- a/docs/deep-search/index.mdx +++ b/docs/deep-search/index.mdx @@ -6,7 +6,12 @@ seoPriority: 1.0 Supported on [Enterprise Starter](/pricing/plans/enterprise-starter) and - [Enterprise](/pricing/plans/enterprise) plans. For new customers, the [Enterprise AI Terms of Use](https://sourcegraph.com/terms/ai-terms) apply and Deep Search is enabled by default. For existing customers with licenses predating the AI terms, Deep Search can be enabled after signing the AI terms addendum - please contact your account team for assistance. Deep Search is not supported for BYOK customers. + [Enterprise](/pricing/plans/enterprise) plans. For new customers, the + [Enterprise AI Terms of Use](https://sourcegraph.com/terms/ai-terms) apply + and Deep Search is enabled by default. For existing customers with licenses + predating the AI terms, Deep Search can be enabled after signing the AI + terms addendum - please contact your account team for assistance. Deep + Search is not supported for BYOK customers. Available on the Web. @@ -93,7 +98,10 @@ Deep Search is only available to customers using the [Sourcegraph Model Provider Customers can request access to [Enterprise Portal](/admin/enterprise-portal#deep-search-usage-monitoring) to monitor Deep Search usage and quota limits.. - ## Architecture Learn about how Deep Search fits into Sourcegraph in the [architecture overview](/admin/architecture#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. diff --git a/docs/getting-started/github-vs-sourcegraph.mdx b/docs/getting-started/github-vs-sourcegraph.mdx index 107639077..a153aac76 100644 --- a/docs/getting-started/github-vs-sourcegraph.mdx +++ b/docs/getting-started/github-vs-sourcegraph.mdx @@ -308,7 +308,7 @@ Sourcegraph’s [editor integrations](/integration/editor) let you search and na ### API -GitHub has a REST API for web clients, but it is not yet documented. On the other hand, Sourcegraph offers different APIs that help you access code-related data available on a Sourcegraph instance. The [GraphQL API](/api/graphql) accesses data stored and computed by Sourcegraph. This API can [fetch](/api/graphql/examples) file contents without cloning a repository or search for a new API and determine all of the repositories that haven’t migrated to it yet. The [Stream API](/api/stream-api) supports consuming search results as a stream of events and it can be used to [search](/api/stream-api#example-curl) over all indexed repositories. Lastly, use the [interactive API explorer](https://sourcegraph.com/api/console#%7B%22query%22%3A%22%23%20Type%20queries%20here%2C%20with%20completion%2C%20validation%2C%20and%20hovers.%5Cn%23%5Cn%23%20Here's%20an%20example%20query%20to%20get%20you%20started%3A%5Cn%5Cnquery%20%7B%5Cn%20%20currentUser%20%7B%5Cn%20%20%20%20username%5Cn%20%20%7D%5Cn%20%20repositories%28first%3A%201%29%20%7B%5Cn%20%20%20%20nodes%20%7B%5Cn%20%20%20%20%20%20name%5Cn%20%20%20%20%7D%5Cn%20%20%7D%5Cn%7D%5Cn%22%7D) to build and test your API queries. +GitHub has a REST API for web clients, but it is not yet documented. On the other hand, Sourcegraph offers different APIs that help you access code-related data available on a Sourcegraph instance. The [GraphQL API](/api/graphql) accesses data stored and computed by Sourcegraph. This API can [fetch](/api/graphql) file contents without cloning a repository or search for a new API and determine all of the repositories that haven’t migrated to it yet. The [Stream API](/api/stream-api) supports consuming search results as a stream of events and it can be used to [search](/api/stream-api#example-curl) over all indexed repositories. Lastly, use the [interactive API explorer](https://sourcegraph.com/api/console#%7B%22query%22%3A%22%23%20Type%20queries%20here%2C%20with%20completion%2C%20validation%2C%20and%20hovers.%5Cn%23%5Cn%23%20Here's%20an%20example%20query%20to%20get%20you%20started%3A%5Cn%5Cnquery%20%7B%5Cn%20%20currentUser%20%7B%5Cn%20%20%20%20username%5Cn%20%20%7D%5Cn%20%20repositories%28first%3A%201%29%20%7B%5Cn%20%20%20%20nodes%20%7B%5Cn%20%20%20%20%20%20name%5Cn%20%20%20%20%7D%5Cn%20%20%7D%5Cn%7D%5Cn%22%7D) to build and test your API queries. | **Features** | **GitHub** | **Sourcegraph** | | --------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------- | diff --git a/docs/tutorials/index.mdx b/docs/tutorials/index.mdx index 113690eef..cc0321b6b 100644 --- a/docs/tutorials/index.mdx +++ b/docs/tutorials/index.mdx @@ -108,11 +108,7 @@ Full [search query syntax](/code-search/queries). ## The Sourcegraph API -| Topic | Content Type | Description | -| ------------------------------------------------------------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [GraphQL API](/api/graphql/) | Reference | The Sourcegraph GraphQL API is a rich API that exposes data related to the code available on a Sourcegraph instance. | -| [GraphQL Examples](/api/graphql/managing-search-contexts-with-api) | Reference | This page demonstrates a few example GraphQL queries for the Sourcegraph GraphQL API. | -| [Streaming API](/api/stream-api/) | Reference | With the Stream API you can consume search results and related metadata as a stream of events. The Sourcegraph UI calls the Stream API for all interactive searches. Compared to our GraphQL API, it offers shorter times to first results and supports running exhaustive searches returning a large volume of results without putting pressure on the backend. | +See [the Sourcegraph API page](/api). ## Search Notebooks diff --git a/src/data/navigation.ts b/src/data/navigation.ts index 4254dabe2..a802b9fe9 100644 --- a/src/data/navigation.ts +++ b/src/data/navigation.ts @@ -411,7 +411,7 @@ export const navigation: NavigationItem[] = [ { title: 'CODEOWNERS Format', href: '/code-ownership/codeowners-format' - }, + } ] }, { @@ -464,14 +464,10 @@ export const navigation: NavigationItem[] = [ title: 'APIs', href: '/api/graphql', sections: [ - {title: 'GraphQL API', href: '/api/graphql'}, - {title: 'Stream API', href: '/api/stream-api'}, + {title: 'Sourcegraph API', href: '/api'}, + {title: 'Streaming search API', href: '/api/stream-api'}, {title: 'Analytics API', href: '/analytics/api'}, - { - title: 'Deep Search API', - href: '/deep-search/api', - preview: true - } + {title: 'Debug API', href: '/api/graphql'} ] }, { diff --git a/src/data/redirects.ts b/src/data/redirects.ts index 923504a75..564ad1848 100644 --- a/src/data/redirects.ts +++ b/src/data/redirects.ts @@ -6328,7 +6328,8 @@ const redirectsData = [ }, { source: '/admin/updates/docker_compose', - destination: 'https://sourcegraph.com/changelog/self-hosted/docker-compose', + destination: + 'https://sourcegraph.com/changelog/self-hosted/docker-compose', permanent: true }, { @@ -7049,7 +7050,8 @@ const redirectsData = [ }, { source: '/self-hosted/updates/docker_compose', - destination: 'https://sourcegraph.com/changelog/self-hosted/docker-compose', + destination: + 'https://sourcegraph.com/changelog/self-hosted/docker-compose', permanent: true }, { @@ -7082,7 +7084,8 @@ const redirectsData = [ // Self-hosted update pages moved to /changelog/self-hosted/ { source: '/self-hosted/updates/docker-compose', - destination: 'https://sourcegraph.com/changelog/self-hosted/docker-compose', + destination: + 'https://sourcegraph.com/changelog/self-hosted/docker-compose', permanent: true }, { @@ -7099,27 +7102,57 @@ const redirectsData = [ { source: '/own', destination: '/code-ownership', - permanant: true, + permanant: true }, { source: '/own/assigned-ownership', destination: '/code-ownership', - permanant: true, + permanant: true }, { source: '/own/configuration-reference', destination: '/code-ownership', - permanant: true, + permanant: true }, { source: '/own/codeowners-ingestion', destination: '/code-ownership', - permanant: true, + permanant: true }, { source: '/own/codeowners-format', destination: '/code-ownership/codeowners-format', - permanant: true, + permanant: true + }, + { + source: '/api/graphql/examples', + destination: '/api/graphql', + permanent: true + }, + { + source: '/api/graphql/search', + destination: '/api/stream-api', + permanent: true + }, + { + source: '/api/graphql/managing-code-insights-with-api', + destination: '/api/graphql', + permanent: true + }, + { + source: '/api/graphql/managing-search-contexts-with-api', + destination: '/api/graphql', + permanent: true + }, + { + source: '/code-search/how-to/create-search-context-graphql', + destination: '/api', + permanent: true + }, + { + source: '/deep-search/api', + destination: '/api', + permanent: true } ]; From b2617559a489729c9ceea6362cfa95b63c9352d5 Mon Sep 17 00:00:00 2001 From: Robert Lin Date: Sun, 22 Feb 2026 18:34:19 -0500 Subject: [PATCH 2/3] gentler wording --- docs/api/index.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/api/index.mdx b/docs/api/index.mdx index 287d82af4..6570dad67 100644 --- a/docs/api/index.mdx +++ b/docs/api/index.mdx @@ -18,10 +18,11 @@ For specific types of integrations, Sourcegraph also offers the following APIs: For diagnostics use cases, the [Sourcegraph GraphQL debug API](/api/graphql/) is also available without any compatibility guarauntees. -

The Sourcegraph GraphQL API is gradually being phased out as an API for - external integrations starting in Sourcegraph 7.0. The GraphQL API will - remain available, but it does not have any compatibility guarantees, unlike - the new API available in Sourcegraph 7.0 at `/api-reference`.

+

The Sourcegraph GraphQL API has historically been an internal interface + without formal compatibility guarantees. For external integrations, + Sourcegraph 7.0 introduces a new, supported API at `/api-reference`. + The GraphQL API remains available, but we recommend migrating to the + new API for a stable integration experience.

If you have a use case that is not currently served by the new Sourcegraph API, please From 0d9d5ba162149ebb4fb791e79b9bfaa72d7a93bd Mon Sep 17 00:00:00 2001 From: Robert Lin Date: Wed, 25 Feb 2026 07:49:32 -0800 Subject: [PATCH 3/3] Apply suggestion from @bobheadxi --- 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 6570dad67..ddf8b2742 100644 --- a/docs/api/index.mdx +++ b/docs/api/index.mdx @@ -1,6 +1,6 @@ # Sourcegraph API -Starting in Sourcegraph 7.0, a new versioned external API is being introduced for custom integrations. The currently available API surface can be seen in `/api-reference` (e.g. `https://sourcegraph.example.com/api-reference`). From this page, integrators can view the available operations and download the OpenAPI schema. We are committed to supporting integrations built on top of these new APIs with backwards compatibility and migration assistance for breaking changes. +Starting in [Sourcegraph 7.0, a new versioned external API is being introduced for custom integrations](https://sourcegraph.com/changelog/sourcegraph-api). The currently available API surface can be seen in `/api-reference` (e.g. `https://sourcegraph.example.com/api-reference`). From this page, integrators can view the available operations and download the OpenAPI schema. We are committed to supporting integrations built on top of these new APIs with backwards compatibility and migration assistance for breaking changes. The new Sourcegraph API is a work in progress, and capabilities are