--- title: "Weaviate REST API" url: https://docs.weaviate.io/weaviate/api/rest --- # Weaviate REST API - **OpenAPI Version:** `3.2.0` - **API Version:** `1.40.3` - **Contact:** Weaviate # Introduction Weaviate is an open source, AI-native vector database that helps developers create intuitive and reliable AI-powered applications. ### Base Path The base path for the Weaviate server is structured as `[YOUR-WEAVIATE-HOST]:[PORT]/v1`. As an example, if you wish to access the `schema` endpoint on a local instance, you would navigate to `http://localhost:8080/v1/schema`. Ensure you replace `[YOUR-WEAVIATE-HOST]` and `[PORT]` with your actual server host and port number respectively. ### Questions? If you have any comments or questions, please feel free to reach out to us at the community forum . ### Issues? If you find a bug or want to file a feature request, please open an issue on our GitHub repository for [Weaviate](https://github.com/weaviate/weaviate). ### Need more documentation? For a quickstart, code examples, concepts and more, please visit our [documentation page](https://docs.weaviate.io/weaviate). ## Servers - **URL:** `{protocol}://{WEAVIATE_HOSTNAME}:{PORT}/v1` - **Variables:** - `protocol` (default: `https`) - `WEAVIATE_HOSTNAME` (default: `localhost`): Weaviate server hostname - `PORT` (default: `8080`): Weaviate server port ## Authentication No authentication required. Or: - **oidc**: OAuth 2.0: implicit, authorize `http://to-be-configured-in-the-application-config` OIDC (OpenConnect ID - based on OAuth2) ## Operations by tag ### root The root of the API. Note the base url is `/v1`. Full reference: - `GET /`: List available endpoints ### schema Operations related to managing collections. In Weaviate, 'collections' (formerly called 'classes') store your data objects. Each collection has a definition that specifies its data structure (properties and their data types), vectorizer settings (how vectors are generated or managed), and indexing configuration (how data is indexed for efficient search). These endpoints allow you to create, retrieve, update, and delete collection definitions. For detailed usage and code examples on interacting with collections, see the documentation: [https://docs.weaviate.io/weaviate/manage-collections](https://docs.weaviate.io/weaviate/manage-collections). Full reference: - `GET /schema`: Get all collection definitions - `POST /schema`: Create a new collection - `GET /schema/{className}`: Get a single collection - `PUT /schema/{className}`: Update collection definition - `DELETE /schema/{className}`: Delete a collection (and all associated data) - `POST /schema/{className}/properties`: Add a property to a collection - `GET /schema/{className}/indexes`: Get index status for all properties of a collection - `PUT /schema/{className}/properties/{propertyName}/index/{indexName}`: Declaratively create or migrate a property's inverted index - `DELETE /schema/{className}/properties/{propertyName}/index/{indexName}`: Delete a property's inverted index - `POST /schema/{className}/properties/{propertyName}/index/{indexName}/rebuild`: Rebuild a property's inverted index with unchanged configuration - `POST /schema/{className}/properties/{propertyName}/index/{indexName}/cancel`: Cancel the in-flight reindex task on a property's inverted index - `POST /schema/{className}/properties/{propertyName}/tokenize`: Tokenize text using a property's configuration - `DELETE /schema/{className}/vectors/{vectorIndexName}/index`: Delete a collection's vector index. - `GET /schema/{className}/shards`: Get the shards status of a collection - `PUT /schema/{className}/shards/{shardName}`: Update a shard status - `GET /schema/{className}/tenants`: Get the list of tenants - `PUT /schema/{className}/tenants`: Update a tenant - `POST /schema/{className}/tenants`: Create a new tenant - `DELETE /schema/{className}/tenants`: Delete tenants - `GET /schema/{className}/tenants/{tenantName}`: Get a specific tenant - `HEAD /schema/{className}/tenants/{tenantName}`: Check if a tenant exists - `GET /aliases`: List aliases - `POST /aliases`: Create a new alias - `GET /aliases/{aliasName}`: Get an alias - `PUT /aliases/{aliasName}`: Update an alias - `DELETE /aliases/{aliasName}`: Delete an alias ### objects Operations for managing individual data objects. Objects are the primary units of data stored within Weaviate collections. Each object conforms to the data schema definition of its parent collection, containing specific properties (data fields). Objects have one or multiple associated vector embeddings and can link to other objects via cross-references. These endpoints allow you to perform CRUD (Create, Read, Update, Delete) operations on individual data objects. Full reference: - `GET /objects`: List objects - `POST /objects`: Create an object - `GET /objects/{id}`: Get an object - `PUT /objects/{id}`: Update an object - `DELETE /objects/{id}`: Delete an object - `HEAD /objects/{id}`: Check if an object exists - `PATCH /objects/{id}`: Patch an object - `GET /objects/{className}/{id}`: Get an object - `PUT /objects/{className}/{id}`: Replace an object - `DELETE /objects/{className}/{id}`: Delete an object - `HEAD /objects/{className}/{id}`: Check if an object exists - `PATCH /objects/{className}/{id}`: Patch an object - `PUT /objects/{id}/references/{propertyName}`: Replace object references - `POST /objects/{id}/references/{propertyName}`: Add an object reference - `DELETE /objects/{id}/references/{propertyName}`: Delete an object reference - `PUT /objects/{className}/{id}/references/{propertyName}`: Replace object references - `POST /objects/{className}/{id}/references/{propertyName}`: Add an object reference - `DELETE /objects/{className}/{id}/references/{propertyName}`: Delete an object reference - `POST /objects/validate`: Validate an object ### batch Operations for performing actions on multiple data items (objects or references) in a single API request. Batch operations significantly improve performance and efficiency, especially for bulk data imports or large-scale deletions, by reducing network overhead compared to sending individual requests. These endpoints allow for creating multiple objects or deleting objects based on filters. Full reference: - `POST /batch/objects`: Create objects in batch - `DELETE /batch/objects`: Delete objects in batch - `POST /batch/references`: Create cross-references in bulk ### search Operations for querying collections over REST. The near-text endpoint performs semantic vector search with server-side embedding of the query text; the bm25 endpoint performs keyword (BM25F) search over the searchable text properties. Each result carries the object's `id`, the selected `properties`, the selected `references` and, when requested, its retrieval `metadata`. Full reference: - `POST /search/{collection}/bm25`: Search a collection with bm25 - `POST /search/{collection}/hybrid`: Search a collection with hybrid - `POST /search/{collection}/near-object`: Search a collection with near-object - `POST /search/{collection}/near-text`: Search a collection with near-text - `POST /search/{collection}/near-vector`: Search a collection with near-vector ### aggregate Operations for aggregating over collections. The aggregate endpoint counts the objects that match an optional `where` filter, in total or grouped by a property's distinct values. Full reference: - `POST /aggregate/{collection}`: Aggregate over a collection ### backups Operations related to creating and managing backups of Weaviate data. This feature allows you to create snapshots of your collections and store them on external storage backends such as cloud object storage (S3, GCS, Azure) or a shared filesystem. These endpoints enable you to initiate backup and restore processes, monitor their status, list available backups on a backend, and cancel ongoing backups. Backups are essential for disaster recovery, data migration, and maintaining point-in-time copies of your vector database. Full reference: - `GET /backups/{backend}`: List all created backups - `POST /backups/{backend}`: Create a backup - `GET /backups/{backend}/{id}`: Get backup creation status - `DELETE /backups/{backend}/{id}`: Cancel a backup - `GET /backups/{backend}/{id}/restore`: Get backup restoration status - `POST /backups/{backend}/{id}/restore`: Restore from a backup - `DELETE /backups/{backend}/{id}/restore`: Cancel a backup restoration ### meta Retrieve information about the server such as the hostname, location, versions and modules. Full reference: - `GET /meta`: Get instance metadata ### cluster Retrieve Raft cluster statistics and node health information for the Weaviate database. Full reference: - `GET /cluster/statistics`: Get cluster statistics ### nodes Monitor node status, shard distribution, and resource statistics for the cluster or specific collections. Full reference: - `GET /nodes`: Get node status - `GET /nodes/{className}`: Get node status by collection ### well-known Standard discovery endpoints for health checks (liveness, readiness) and OpenID Connect configuration if [OIDC authentication](https://docs.weaviate.io/deploy/configuration/authentication#oidc-authentication) is enabled. Full reference: - `GET /.well-known/live`: Check application liveness - `GET /.well-known/ready`: Check application readiness - `GET /.well-known/openid-configuration`: Get OIDC configuration ### graphql Query data using the GraphQL query language. See the [Weaviate GraphQL documentation](https://docs.weaviate.io/weaviate/api/graphql) for query syntax details. Full reference: - `POST /graphql`: Perform a GraphQL query - `POST /graphql/batch`: Perform batched GraphQL queries ### export Operations for exporting Weaviate data to external storage backends (S3, GCS, Azure, or filesystem). The output file format is specified via the 'file_format' field (currently only 'parquet' is supported). Exports provide a way to extract your vector data and object properties into a standardized columnar format for data analysis, archival, or migration. Each collection is exported to a separate file containing object IDs, vectors, properties, and metadata. Full reference: - `POST /export/{backend}`: Start a new export - `GET /export/{backend}/{id}`: Get export status - `DELETE /export/{backend}/{id}`: Cancel an export ### authz Endpoints for managing Weaviate's Role-Based Access Control (RBAC) system. Access to Weaviate resources is granted through roles, which are collections of fine-grained permissions. **Permissions:** Define allowed actions (e.g., `read_data`, `create_collections`, `delete_users`) on specific resources. Resources can be specified broadly (e.g., all collections: `*`) or narrowly (e.g., a specific collection name, tenant pattern, user name, or role name). **Roles:** Are named sets of permissions. Managing roles involves creating roles with specific permissions, retrieving role definitions, deleting roles, and adding or removing permissions from existing roles. **Role assignment:** Roles grant their contained permissions to users or groups. These endpoints allow assigning roles to: * `db` users: Users managed directly by Weaviate via API or environment variables, authenticating with API keys. * `oidc` users: Users authenticated via an external OpenID Connect provider, managed externally but assigned roles within Weaviate. * OIDC `groups`: Users authenticated via OIDC who belong to a group automatically inherit roles assigned to that group. Operations also include revoking roles, checking if a role has a specific permission, listing roles assigned to a user, and listing users/groups assigned to a role. The authorization framework applies universally to both `db` and `oidc` users based on their assigned roles. Full reference: - `GET /authz/roles`: Get all roles - `POST /authz/roles`: Create new role - `POST /authz/roles/{id}/add-permissions`: Add permissions to a role - `POST /authz/roles/{id}/remove-permissions`: Remove permissions from a role - `GET /authz/roles/{id}`: Get a role - `DELETE /authz/roles/{id}`: Delete a role - `POST /authz/roles/{id}/has-permission`: Check whether a role possesses a permission - `GET /authz/roles/{id}/users`: Get users assigned to a role - `GET /authz/roles/{id}/user-assignments`: Get users assigned to a role - `GET /authz/roles/{id}/group-assignments`: Get groups that have a specific role assigned - `GET /authz/users/{id}/roles`: Get roles assigned to a user - `GET /authz/users/{id}/roles/{userType}`: Get roles assigned to a user - `POST /authz/users/{id}/assign`: Assign a role to a user - `POST /authz/users/{id}/revoke`: Revoke a role from a user - `POST /authz/groups/{id}/assign`: Assign a role to a group - `POST /authz/groups/{id}/revoke`: Revoke a role from a group - `GET /authz/groups/{id}/roles/{groupType}`: Get roles assigned to a specific group - `GET /authz/groups/{groupType}`: List all groups of a specific type ### users Endpoints for user account management in Weaviate. This includes operations specific to Weaviate-managed database users (`db` users), such as creation (which generates an API key), listing, deletion, activation/deactivation, and API key rotation. It also provides operations applicable to any authenticated user (`db` or `oidc`), like retrieving their own information (username and assigned roles). **User Types:** * **`db` users:** Managed entirely within Weaviate (creation, deletion, API keys). Use these endpoints for full lifecycle management. * **`oidc` users:** Authenticated via an external OpenID Connect provider. Their lifecycle (creation, credentials) is managed externally, but their role assignments *within Weaviate* are managed via the `authz` endpoints. Full reference: - `GET /users/own-info`: Get current user info - `GET /users/db`: List all users - `GET /users/db/{user_id}`: Get user info - `POST /users/db/{user_id}`: Create a new user - `DELETE /users/db/{user_id}`: Delete a user - `POST /users/db/{user_id}/rotate-key`: Rotate API key of a user - `POST /users/db/{user_id}/activate`: Activate a user - `POST /users/db/{user_id}/deactivate`: Deactivate a user ### classifications Perform classification operations. Full reference: - `POST /classifications/`: Start a classification - `GET /classifications/{id}`: Get classification status ### replication Operations related to managing data replication, including initiating and monitoring shard replica movements between nodes, querying current sharding states, and managing the lifecycle of replication tasks. Full reference: - `POST /replication/replicate`: Initiate a replica movement - `DELETE /replication/replicate`: Delete all replication operations - `POST /replication/replicate/force-delete`: Force delete replication operations - `GET /replication/replicate/{id}`: Retrieve a replication operation - `DELETE /replication/replicate/{id}`: Delete a replication operation - `GET /replication/replicate/list`: List replication operations - `POST /replication/replicate/{id}/cancel`: Cancel a replication operation - `GET /replication/sharding-state`: Get sharding state - `GET /replication/scale`: Get replication scale plan - `POST /replication/scale`: Apply replication scaling plan ### mcp Model Context Protocol (MCP) endpoint. Provides tool discovery and invocation for LLM agents via the MCP Streamable HTTP transport. Check out the [Weaviate MCP server documentation](https://docs.weaviate.io/weaviate/configuration/mcp-server) for more info. Full reference: - `POST /mcp`: mcp.post - `DELETE /mcp`: mcp.delete ### namespaces Operations for managing cluster-level namespaces. Namespaces group resources under a common administrative unit. Access is gated by the operator-tier `manage_namespaces` action and, on namespace-enabled clusters, a well-formed Weaviate license key on the serving node. Full reference: - `GET /namespaces`: List namespaces - `GET /namespaces/{namespace_id}`: Get a namespace - `PUT /namespaces/{namespace_id}`: Update a namespace - `POST /namespaces/{namespace_id}`: Create a new namespace - `DELETE /namespaces/{namespace_id}`: Delete a namespace - `POST /namespaces/{namespace_id}/suspend`: Suspend a namespace - `POST /namespaces/{namespace_id}/resume`: Resume a namespace ### experimental Full reference: - `POST /experimental/export-db-users`: Export all database-user credentials - `POST /experimental/import-db-users`: Import database-user credentials ### tokenize Full reference: - `POST /tokenize`: Tokenize text ### distributedTasks Full reference: - `GET /tasks`: Lists all distributed tasks in the cluster