g-despot · Oct 1, 2026 · Oct 5, 2026 · Oct 6, 2026
diff --git a/_includes/graphql-deprecation.mdx b/_includes/graphql-deprecation.mdx
@@ -0,0 +1,9 @@
+:::warning The GraphQL API is deprecated
+
+Weaviate Cloud switches off the GraphQL API on **April 1, 2027**. New Weaviate Cloud clusters are already created with GraphQL disabled. Self-hosted Weaviate will disable it by default in an upcoming minor release and remove it later.
+
+{/* TODO(ivan): Q1. Replace "an upcoming minor release" with the version once Dirk confirms. */}
+
+Use a [client library](/weaviate/client-libraries), the [web client](/weaviate/client-libraries/typescript/web-client) or the REST Search API instead. See [Migrating from the GraphQL API](/weaviate/api/graphql/migration).
+
+:::
diff --git a/docs/cloud/faq.mdx b/docs/cloud/faq.mdx
@@ -111,7 +111,11 @@ Each user can have one (1) free cluster, and by default each organization can ha
 <details>
 <summary> Answer </summary>
 
-New Weaviate Cloud clusters are created with GraphQL disabled (the `DISABLE_GRAPHQL` environment variable is set to `true`). To query your data, use one of these alternatives:
+New Weaviate Cloud clusters are created with GraphQL disabled (the `DISABLE_GRAPHQL` environment variable is set to `true`). The GraphQL API is deprecated, and Weaviate Cloud switches it off on existing clusters on **April 1, 2027**. See [Migrating from the GraphQL API](/weaviate/api/graphql/migration).
+
+{/* TODO(ivan): Q7. Confirm whether existing clusters can turn GraphQL off early, and whether extensions exist. */}
+
+To query your data, use one of these alternatives:
 
 - A [client library](/weaviate/client-libraries) for your programming language.
 - The [REST Search endpoints](/weaviate/api/rest).

diff --git a/docs/cloud/manage-clusters/default-settings.mdx b/docs/cloud/manage-clusters/default-settings.mdx
@@ -29,6 +29,10 @@ import AdvancedOptions from "/docs/cloud/img/weaviate-cloud-cluster-advanced-set
 | `CORS_ALLOW_ORIGIN` | Yes | https://console.weaviate.cloud | Yes (to allow any) |
 | [`REPLICATION_MINIMUM_FACTOR`](/deploy/configuration/env-vars/index.md#REPLICATION_MINIMUM_FACTOR) | Yes | 3 (for HA clusters) | No |
 
+The GraphQL API is deprecated. Weaviate Cloud switches it off on existing clusters on April 1, 2027. See [Migrating from the GraphQL API](/weaviate/api/graphql/migration).
+
+{/* TODO(ivan): Q7. Confirm Weaviate Cloud sets DISABLE_GRAPHQL to true on existing clusters at the switch-off, or uses another mechanism. */}
+
 The user configurable settings appear as toggles in the `Advanced configuration` section of the cluster `Dashboard`: `Enable MCP Read-Only`, `Enable auto schema generation`, and `Allow all CORS origins`.
 
 <div class="row">

diff --git a/docs/deploy/configuration/env-vars/index.md b/docs/deploy/configuration/env-vars/index.md
@@ -41,7 +41,7 @@ import APITable from '@site/src/components/APITable';
 | `DEFAULT_VECTOR_INDEX` | Default vector index type for new collections (and named vectors), used when the collection definition does not specify one. An explicit `vectorIndexType` in the collection definition still takes precedence. Available values: `hnsw`, `flat`, `dynamic`, and `hfresh`. Runtime-configurable. Default: `hnsw`<br/>Added in `v1.37.3` | `string` | `flat` |
 | `DEFAULT_VECTORIZER_MODULE` | Default vectorizer module - can be overridden by the vectorizer in the collection definition. | `string` | `text2vec-contextionary` |
 | `API_BASED_MODULES_DISABLED` | Weaviate automatically enables the usage of all [API-based modules](../../../weaviate/model-providers/index.md#api-based). Set this variable to `true` in order to limit access and only allow specific modules through the [`ENABLE_MODULES`](#ENABLE_MODULES) variable. Default: `false`<br/> Added in `v1.33` | `boolean` | `true` |
-| `DISABLE_GRAPHQL` | Disable the GraphQL API (default: `false`). When `true`, the `/v1/graphql` endpoint is not served. New [Weaviate Cloud](/cloud/manage-clusters/default-settings) clusters are created with this set to `true`. See [Can I use GraphQL with Weaviate Cloud?](/cloud/faq#graphql) for the alternatives. | `boolean` | `true` |
+| `DISABLE_GRAPHQL` | Disable the GraphQL API (default: `false`). **The GraphQL API is deprecated.** The default will change to `true` in an upcoming minor release. See [Migrating from the GraphQL API](/weaviate/api/graphql/migration). When `true`, the `/v1/graphql` endpoint is not served. New [Weaviate Cloud](/cloud/manage-clusters/default-settings) clusters are created with this set to `true`. See [Can I use GraphQL with Weaviate Cloud?](/cloud/faq#graphql) for the alternatives. | `boolean` | `true` |
 | `DISABLE_LAZY_LOAD_SHARDS` | When `false`, enable lazy shard loading to improve mean time to recovery in multi-tenant deployments. **Deprecated in `v1.36.6`.** Use `LAZY_LOAD_SHARD_COUNT_THRESHOLD` and `LAZY_LOAD_SHARD_SIZE_THRESHOLD_GB` instead. Weaviate now auto-detects when lazy loading is needed per collection. | `string` | `false` |
 | `DISABLE_STARTUP_BANNER` | Disable the banner Weaviate logs shortly after startup (`action=banner`, with the version, the link to [Improve your cluster](/improve-your-cluster), and this node's `/v1/meta` URL), and its repeat every `BANNER_INTERVAL`. The banner runs only while telemetry is enabled, because it fetches its art from weaviate.io, so a cluster with `DISABLE_TELEMETRY=true` never logs one. It is an `info` entry, so `LOG_LEVEL=warning` or stricter hides it as well. Default: `false`<br/>Added in `v1.39.4` | `boolean` | `true` |
 | `DISABLE_TELEMETRY` | Disable [telemetry](/deploy/configuration/telemetry.md) data collection | boolean | `false` |

diff --git a/docs/weaviate/api/graphql/additional-operators.md b/docs/weaviate/api/graphql/additional-operators.md
@@ -5,6 +5,11 @@ description: "Syntax reference for additional operators that extend query functi
 image: og/docs/api.jpg
 # tags: ['graphql', 'additional operators']
 ---
+
+import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx';
+
+<GraphQLDeprecation />
+
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import TryEduDemo from '/_includes/try-on-edu-demo.mdx';

diff --git a/docs/weaviate/api/graphql/additional-properties.md b/docs/weaviate/api/graphql/additional-properties.md
@@ -5,6 +5,10 @@ description: "GraphQL API guide for accessing metadata and additional properties
 image: og/docs/api.jpg
 ---
 
+import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx';
+
+<GraphQLDeprecation />
+
 import SkipLink from '/src/components/SkipValidationLink'
 import TryEduDemo from '/_includes/try-on-edu-demo.mdx';
 

diff --git a/docs/weaviate/api/graphql/aggregate.md b/docs/weaviate/api/graphql/aggregate.md
@@ -6,6 +6,10 @@ image: og/docs/api.jpg
 # tags: ['graphql', 'aggregate', 'aggregate{}', 'meta']
 ---
 
+import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx';
+
+<GraphQLDeprecation />
+
 import FilteredTextBlock from '@site/src/components/Documentation/FilteredTextBlock';
 
 import TryEduDemo from '/_includes/try-on-edu-demo.mdx';

diff --git a/docs/weaviate/api/graphql/explore.md b/docs/weaviate/api/graphql/explore.md
@@ -6,6 +6,10 @@ image: og/docs/api.jpg
 # tags: ['graphql', 'explore{}']
 ---
 
+import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx';
+
+<GraphQLDeprecation />
+
 :::note Vector spaces and Explore
 
 The `Explore` function is disabled where multiple inference (e.g. `text2vec-xxx`) modules are enabled.

diff --git a/docs/weaviate/api/graphql/filters.md b/docs/weaviate/api/graphql/filters.md
@@ -6,6 +6,9 @@ image: og/docs/api.jpg
 # tags: ['graphql', 'filters']
 ---
 
+import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx';
+
+<GraphQLDeprecation />
 
 import TryEduDemo from '/_includes/try-on-edu-demo.mdx';
 

diff --git a/docs/weaviate/api/graphql/get.md b/docs/weaviate/api/graphql/get.md
@@ -6,6 +6,10 @@ image: og/docs/api.jpg
 # tags: ['graphql', 'get{}']
 ---
 
+import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx';
+
+<GraphQLDeprecation />
+
 import FilteredTextBlock from '@site/src/components/Documentation/FilteredTextBlock';
 
 import TryEduDemo from '/_includes/try-on-edu-demo.mdx';

diff --git a/docs/weaviate/api/graphql/index.md b/docs/weaviate/api/graphql/index.md
@@ -1,23 +1,20 @@
 ---
-title: Search (GraphQL | gRPC)
+title: GraphQL API (deprecated)
 sidebar_position: 0
-description: "GraphQL and gRPC API documentation for flexible querying and data retrieval in Weaviate."
+description: "Reference for Weaviate's deprecated GraphQL query API, and where to find its replacements."
 image: og/docs/api.jpg
 # tags: ['GraphQL references']
 ---
 
-:::note GraphQL on Weaviate Cloud
-New Weaviate Cloud clusters are created with GraphQL disabled (the `DISABLE_GRAPHQL` environment variable is set to `true`). To query your data on Weaviate Cloud, use a [client library](../../client-libraries/index.mdx) or the [REST Search endpoints](/weaviate/api/rest).
-:::
-
-## API
+import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx';
 
-Weaviate offers [GraphQL](https://graphql.org/) and gRPC APIs for queries.
+<GraphQLDeprecation />
 
-We recommend using a Weaviate [client library](../../client-libraries/index.mdx), which abstracts away the underlying API calls and makes it easier to integrate Weaviate into your application.
+## API
 
-However, you can query Weaviate directly using GraphQL with a POST request to the `/graphql` endpoint, or write your own `gRPC` calls based on the [gRPC](../grpc.md) protobuf specification.
+This section is the reference for Weaviate's [GraphQL](https://graphql.org/) query API. To search your data, use a Weaviate [client library](../../client-libraries/index.mdx). The current Python, TypeScript, Java and C# clients query over the [gRPC API](../grpc.md).
 
+To move existing GraphQL queries to a client library, the web client or the REST Search API, see [Migrating from the GraphQL API](./migration.mdx).
 
 ## All references
 
@@ -34,10 +31,6 @@ All references have their individual subpages. Click on one of the references be
 
 ## GraphQL API
 
-### Why GraphQL?
-
-GraphQL is a query language built on using graph data structures. It is an efficient method of data retrieval and mutation, since it mitigates the common over-fetching and under-fetching problems of other query languages.
-
 :::tip GraphQL is case-sensitive
 GraphQL is case-sensitive ([reference](https://spec.graphql.org/June2018/#sec-Names)), so make sure to use the correct casing when writing your queries.
 :::

diff --git a/docs/weaviate/api/graphql/migration.mdx b/docs/weaviate/api/graphql/migration.mdx
@@ -1,16 +1,28 @@
 ---
 title: Migrating from the GraphQL API
-description: "How to express your existing GraphQL Get and Aggregate queries with the Weaviate client libraries, the browser client, or the REST Search API."
+description: "The GraphQL API is deprecated. How to find your GraphQL usage and move Get and Aggregate queries to the Weaviate client libraries, the browser client, or the REST Search API."
 image: og/docs/api.jpg
-unlisted: true
 ---
 
 import SkipLink from '/src/components/SkipValidationLink'
 
+## What is changing and when
+
+The GraphQL API is deprecated as of October 12, 2026. Nothing changes on that day, and existing clusters keep working. Weaviate Cloud switches GraphQL off on April 1, 2027, and self-hosted Weaviate will disable it by default in an upcoming minor release.
+
+{/* TODO(ivan): Q1. Replace "an upcoming minor release" with the version once Dirk confirms. */}
+
+| Stage | Weaviate Cloud | Self-hosted |
+| --- | --- | --- |
+| **Deprecated**, October 12, 2026 | Existing clusters keep working. New clusters are created with GraphQL disabled, as they already are today. | Nothing changes. |
+| **Disabled by default** | Already the case for new clusters. | In an upcoming minor release. You can turn GraphQL back on. |
+| **Switched off or removed** | Switched off on all clusters on April 1, 2027. | Removed in a later release. |
+
 ## Who this guide is for
 
-This guide is for developers who have working GraphQL `Get` and `Aggregate` queries and want to express the same searches through one of Weaviate's other query APIs. Typical reasons to be here:
+This guide is for developers who have working GraphQL `Get` and `Aggregate` queries and need to express the same searches through one of Weaviate's other query APIs. Typical reasons to be here:
 
+- The GraphQL API is **deprecated**. Code that still sends GraphQL queries stops working once GraphQL is disabled, so it needs to move before [the dates above](#what-is-changing-and-when).
 - You are moving an application to a **new Weaviate Cloud cluster**, which is created with **GraphQL disabled**.
 - You are building in the **browser** or on an edge runtime, where a plain gRPC client cannot run.
 - You maintain an **HTTP-only stack**, such as a no-code or BI tool, or a language without an official Weaviate client such as PHP or Ruby.
@@ -27,12 +39,65 @@ Start at the top of this table and take the first row that describes your stack.
 The three paths are at three different maturity levels. Check the **Status** column before you commit to one.
 :::
 
+{/* TODO(ivan): Q5. Confirm the Preview, Alpha and beta labels below are still right on October 12, 2026. */}
+
 | Path | Status | Availability |
 | --- | --- | --- |
-| **Official client libraries** | Generally available | Python, JavaScript/TypeScript, Java, and C# are generally available while the Go client v6 is currently in [beta release](https://github.com/weaviate/weaviate-go-client/releases/tag/v6.0.0-beta.3). Earlier versions of the Go client rely on GraphQL. |
+| **Official client libraries** | Generally available | Python, JavaScript/TypeScript, Java, and C# are generally available while the Go client v6 is currently in [beta release](https://github.com/weaviate/weaviate-go-client/releases/tag/v6.0.0-beta.3). The current stable Go client, `v5`, relies on GraphQL. |
 | **`@weaviate/web`** (browser and edge) | **Alpha** | `3.15.0-alpha.6`. Requires Weaviate `v1.38.3` or later. See the [web client page](../../client-libraries/typescript/web-client.mdx). |
 | **REST Search API** | **Preview** | Enabled by default from `v1.39.7`. In `v1.39.0` through `v1.39.6` it needs [`EXPERIMENTAL_REST_SEARCH_ENABLED`](/deploy/configuration/env-vars/index.md#EXPERIMENTAL_REST_SEARCH_ENABLED) set to `true`. See [REST Search API](#rest-search-api). |
 
+## Do you need to migrate
+
+You need to migrate if any part of your application sends GraphQL to Weaviate. The two checks below tell you whether it does, and let you prove it before GraphQL is switched off.
+
+### Find your GraphQL usage
+
+GraphQL can reach Weaviate in three ways, and an older client can send it without you writing a single query.
+
+<details>
+  <summary>Where GraphQL hides, and which client versions use it</summary>
+
+Your code sends GraphQL queries if it does any of the following:
+
+- **Calls the endpoint directly.** It sends HTTP requests to `/v1/graphql` or `/v1/graphql/batch`, for example with `curl` or a generic HTTP library.
+- **Uses a raw GraphQL helper.** Some clients can pass a GraphQL query string straight to the server. These helpers always use GraphQL, whatever the client generation.
+- **Uses an older client generation.** Older clients build their queries as GraphQL under the hood. The Go client does this in its current stable generation too.
+
+Check each client your code uses against this table:
+
+| Client | Queries over gRPC from | Still uses GraphQL when |
+| --- | --- | --- |
+| Python `weaviate-client` | Search: `v4.4.0`. Aggregate: `v4.11.0`, against Weaviate `v1.29.0` or later | Aggregate and `len(collection)` fall back to GraphQL on Weaviate older than `v1.29.0`. `client.graphql_raw_query()` always uses GraphQL. |
+| TypeScript `weaviate-client` | Search: `v3.0.0`. Aggregate: `v3.4.0`, against Weaviate `v1.29.0` or later | Aggregate falls back to GraphQL on Weaviate older than `v1.29.0`. The bundled legacy `weaviateV2` client (`client.graphql.*`) always uses GraphQL. |
+| Java `io.weaviate:client6` | `6.0.0` | Never. |
+| C# | `1.0.0` | Never. |
+| Go `weaviate-go-client/v5` (current stable) | Never | Always. `client.GraphQL().Get()`, `.Aggregate()`, `.Explore()` and `.Raw()` are its search API. |
+| Go v6 (pre-release) | `v6.0.0-beta.3`. Aggregate covers over-all and near-vector only | Never. No generative search yet at this tag. |
+
+</details>
+
+### Test with GraphQL disabled
+
+A test instance with GraphQL switched off proves that your application no longer depends on it.
+
+<details>
+  <summary>How to switch GraphQL off, and what a disabled endpoint returns</summary>
+
+Run your application against an instance with GraphQL switched off before you rely on it. On a non-production self-hosted instance, set the [`DISABLE_GRAPHQL`](/deploy/configuration/env-vars/index.md#DISABLE_GRAPHQL) environment variable to `true`. It is also available as the `disable_graphql` [runtime configuration](/deploy/configuration/env-vars/runtime-config.md) key.
+
+With GraphQL disabled, `POST /v1/graphql` and `POST /v1/graphql/batch` return HTTP `422` with this body:
+
+```json
+{"error":[{"message":"graphql api is disabled"}]}
+```
+
+Authorization runs first, so a caller without read permission gets `403` instead. The Python client and the current Go client return an error that carries the same status code and message.
+
+A new Weaviate Cloud cluster is already in this state, so you can also test against one.
+
+</details>
+
 ## Client libraries (recommended)
 
 The client libraries cover every `Get` and `Aggregate` construct shown on this page, so each one has a direct equivalent. They query over gRPC, and give you typed results and generated request objects.
@@ -221,9 +286,22 @@ One more request limit worth knowing: in `v1.39`, `limit`, `offset`, and their s
 
 </details>
 
+## GraphQL features without an equivalent
+
+These GraphQL features have no equivalent in the gRPC API, the client libraries or the REST Search API today:
+
+- `Explore`
+- `ask`, from the `qna` modules
+- Summarization, from the `sum-transformers` module
+- Named entity recognition, from the `ner-transformers` module
+- `spellCheck`
+- The `_additional` properties `featureProjection`, `semanticPath`, `interpretation` and `classification`
+
+{/* TODO(ivan): Q3. State what happens to these features once Dirk confirms. Until then, keep "no equivalent today". */}
+
 ## Further resources
 
-- [Search (GraphQL | gRPC)](./index.md) - the GraphQL and gRPC search API reference
+- [GraphQL API (deprecated)](./index.md) - the GraphQL API reference
 - [gRPC-Web](../grpc.md#grpc-web) - the browser-reachable gRPC interface
 - [Client libraries](../../client-libraries/index.mdx) - installation and connection for each language
 - [Web client](../../client-libraries/typescript/web-client.mdx) - install steps and browser notes for `@weaviate/web`

diff --git a/docs/weaviate/api/graphql/search-operators.md b/docs/weaviate/api/graphql/search-operators.md
@@ -6,6 +6,10 @@ image: og/docs/api.jpg
 # tags: ['graphql', 'search operators']
 ---
 
+import GraphQLDeprecation from '/_includes/graphql-deprecation.mdx';
+
+<GraphQLDeprecation />
+
 import SearchOperators from '/_includes/feature-notes/search-operators.mdx';