APIs

Weaviate provides multiple Application Programming Interfaces (APIs) to interact with the database, manage instances, and perform searches. Weaviate exposes three main APIs:

• RESTful API: Enables almost complete management of a Weaviate instance.

  • Includes operations for managing collections (creating, reading, updating, deleting collections and their definitions), performing basic CRUD (Create, Read, Update, Delete) operations on individual data objects, checking node status, backups, and managing cluster health.
  • The machine-readable specification behind this reference is published at https://docs.weaviate.io/openapi.json. See Machine-readable API specification below.
  • The reference also lists the REST Search API (the /v1/search/{collection}/... and /v1/aggregate/{collection} endpoints), a preview feature for stacks that cannot run a client library. It is enabled by default from v1.39.7. In v1.39.0 through v1.39.6 it is disabled unless EXPERIMENTAL_REST_SEARCH_ENABLED is set to true, and rejects requests with a 422 status. See the migration guide.

• gRPC API: The search API, used by the client libraries.

  • Covers search, filtering, aggregation, and batch data imports. It leverages Protocol Buffers for faster serialization, lower latency, and efficient data streaming compared to traditional REST/JSON communication.

• GraphQL API (deprecated): A query API for search and aggregation.

  • Deprecated. Weaviate Cloud switches it off on May 1, 2027. New Weaviate Cloud clusters are already created with GraphQL disabled.
  • To move existing queries, see Migrating from the GraphQL API.

Machine-readable API specification

The RESTful API reference is rendered from the same specification file that Weaviate builds its REST server from: the request handlers, models, and generated Go client are all produced from it. The specification therefore defines the API rather than describing it after the fact.

For tools, code generators, and agents, that specification is published at the conventional discovery URL https://docs.weaviate.io/openapi.json, which is where most tooling looks for it. The document is written in Swagger 2.0 (OpenAPI 2.0) format, not OpenAPI 3.x, so a consumer that only accepts 3.x needs to convert it first.

Alternative URL, versioning, and scope

/openapi.json serves a rewrite of https://docs.weaviate.io/specs/weaviate-openapi.json. Both URLs return the same document, so request whichever suits your tooling.

The published document is a copy of the specification taken from a Weaviate release branch, and it is updated periodically rather than on every release. Read its info.version field to see which Weaviate version it describes, and compare that with the version you are running.

The specification describes the REST API only. The GraphQL and gRPC search APIs are documented separately, and Weaviate's gRPC service is defined by its protocol buffer files rather than by this document.

Client libraries and API usage

Weaviate offers official client libraries for these programming languages:

• Python
• TypeScript/JavaScript
• Go
• Java
• C#

TIP: Using the official client libraries for interacting with Weaviate

The client libraries abstract away the complexities of making direct REST or gRPC calls. You interact with Weaviate using idiomatic methods and objects in your preferred language.

The current Python, TypeScript, Java, C# and Go client libraries send search and query operations over gRPC. See Find your GraphQL usage.

Questions and feedback

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.