Weaviate REST API
Introduction Weaviate is an open source, AI-native vector database that helps developers create intuitive and reliable AI-powered applications. ### Base Path…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
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 https://forum.weaviate.io/. ### Issues? If you find a bug or want to file a feature request, please open an issue on our GitHub repository for Weaviate. ### Need more documentation? For a quickstart, code examples, concepts and more, please visit our documentation page.
Endpoints 131
objects
- GETList objects
/objects?after=string&offset=0&limit=0&include=string&sort=string&order=string&class=string&tenant=stringRetrieves a list of data objects. By default, objects are returned in reverse order of creation. Requires a collection name (class) parameter to specify which… - POSTCreate an object
/objects?consistency_level=stringCreates a new data object. The object's metadata and schema values are validated before creation.<br/><br/>Note (batch import):<br/>If you plan on importing a… - GETGet an object
/objects/:id?include=stringDeprecated. Get a specific object based on its UUID. Also available as Websocket bus. <br/><br/>Note: This endpoint is deprecated and will be removed in a… - PUTUpdate an object
/objects/:id?consistency_level=stringDeprecated. Updates an object based on its UUID. Given meta-data and schema values are validated. lastUpdateTimeUnix is set to the time this function is… - DELETEDelete an object
/objects/:id?consistency_level=string&tenant=stringDeprecated. Deletes an object from the database based on its UUID. <br/><br/>Note: This endpoint is deprecated and will be removed in a future version. Use… - HEADCheck if an object exists
/objects/:idDeprecated. Checks if an object exists in the system based on its UUID. <br/><br/>Note: This endpoint is deprecated and will be removed in a future version.… - PATCHPatch an object
/objects/:id?consistency_level=stringDeprecated. Update an object based on its UUID (using patch semantics). This method supports json-merge style patch semantics (RFC 7396). Provided meta-data… - GETGet an object
/objects/:className/:id?include=string&consistency_level=string&node_name=string&tenant=stringGet a data object based on its collection name (className) and UUID (id). - PUTReplace an object
/objects/:className/:id?consistency_level=stringReplaces properties of an existing data object. The object is identified by its collection name (className) and UUID (id). The request body must contain the… - DELETEDelete an object
/objects/:className/:id?consistency_level=string&tenant=stringRemoves a data object from a specific collection, identified by its collection name (className) and UUID (id).<br/><br/>Note on deleting references (legacy… - HEADCheck if an object exists
/objects/:className/:id?consistency_level=string&tenant=stringVerifies the existence of a specific data object within a collection (class), identified by its collection name (className) and UUID (id), without returning… - PATCHPatch an object
/objects/:className/:id?consistency_level=stringUpdates specific properties of an existing data object using JSON merge patch semantics (RFC 7396). The object is identified by its collection name… - PUTReplace object references
/objects/:id/references/:propertyName?tenant=stringDeprecated. Replace all references in cross-reference property of an object. <br/><br/>Note: This endpoint is deprecated and will be removed in a future… - POSTAdd an object reference
/objects/:id/references/:propertyName?tenant=stringDeprecated. Add a reference to a specific property of a data object. <br/><br/>Note: This endpoint is deprecated and will be removed in a future version. Use… - DELETEDelete an object reference
/objects/:id/references/:propertyName?tenant=stringDeprecated. Delete the single reference that is given in the body from the list of references that this property has. <br/><br/>Note: This endpoint is… - PUTReplace object references
/objects/:className/:id/references/:propertyName?consistency_level=string&tenant=stringReplaces all existing references for a specific reference property (propertyName) on a source data object. The source object is identified by its collection… - POSTAdd an object reference
/objects/:className/:id/references/:propertyName?consistency_level=string&tenant=stringAdds a new reference to a reference property (propertyName) on a source data object. The source object is identified by its collection name (className) and… - DELETEDelete an object reference
/objects/:className/:id/references/:propertyName?consistency_level=string&tenant=stringRemoves a specific reference from a reference property (propertyName) of a source data object. The source object is identified by its collection name… - POSTValidate an object
/objects/validateChecks if a data object's structure conforms to the specified collection schema and metadata rules without actually storing the object.<br/><br/>A successful…
batch
- POSTCreate objects in batch
/batch/objects?consistency_level=stringRegisters multiple data objects in a single request for efficiency. Metadata and schema values for each object are validated.<br/><br/>Note… - DELETEDelete objects in batch
/batch/objects?consistency_level=string&tenant=stringRemoves multiple data objects based on a filter specified in the request body.<br/><br/>Deletion occurs based on the filter criteria provided in the where… - POSTCreate cross-references in bulk
/batch/references?consistency_level=stringBatch create cross-references between collection items in bulk.
graphql
- POSTPerform a GraphQL query
/graphqlExecutes a single GraphQL query provided in the request body. Use this endpoint for all Weaviate data queries and exploration. - POSTPerform batched GraphQL queries
/graphql/batchExecutes multiple GraphQL queries provided in the request body as an array. Allows performing several queries in a single network request for efficiency.
search
- POSTSearch a collection with bm25
/search/:collection/bm25Performs a keyword (BM25F) search over the objects of a collection. Objects are scored against the query with the BM25F ranking function over the searchable… - POSTSearch a collection with hybrid
/search/:collection/hybridPerforms a hybrid search over the objects of a collection: the query is scored with the BM25F ranking function over the searchable text properties (all of… - POSTSearch a collection with near-object
/search/:collection/near-objectPerforms a similarity search over the objects of a collection, anchored at an existing object: the stored vector of the source object (referenced by id) is… - POSTSearch a collection with near-text
/search/:collection/near-textPerforms a semantic (near-text) search over the objects of a collection. The query text is vectorized server-side by the collection's vectorizer module and… - POSTSearch a collection with near-vector
/search/:collection/near-vectorPerforms a similarity search over the objects of a collection, anchored at a vector supplied by the caller: the query vector is searched against the vector…
aggregate
- POSTAggregate over a collection
/aggregate/:collectionAggregates over the objects of a collection. Phase 1 supports counts: the number of matching objects, either in total (flat count response) or per group of a…
meta
- GETGet instance metadata
/metaProvides meta-information about the running Weaviate instance, including its version, loaded modules, and network hostname. This information can be useful for…
schema
- GETGet all collection definitions
/schemaRetrieves the definitions of all collections (classes) currently in the database schema. - POSTCreate a new collection
/schemaDefines and creates a new collection (class).<br/><br/>If AutoSchema is enabled (not recommended for production), Weaviate might attempt to infer schema from… - GETGet a single collection
/schema/:classNameRetrieve the definition of a specific collection (className), including its properties, configuration, and vectorizer settings. - PUTUpdate collection definition
/schema/:classNameUpdates the configuration settings of an existing collection (className) based on the provided definition. Note: This operation modifies mutable settings… - DELETEDelete a collection (and all associated data)
/schema/:classNameRemoves a collection definition from the schema. WARNING: This action permanently deletes all data objects stored within the collection. - POSTAdd a property to a collection
/schema/:className/propertiesAdds a new property definition to an existing collection (className) definition. - GETGet index status for all properties of a collection
/schema/:className/indexesReturns per-property index state including active reindex progress. This powers the UI to show live migration status. The response reflects the state of the… - PUTDeclaratively create or migrate a property's inverted index
/schema/:className/properties/:propertyName/index/:indexName?tenants=stringUpserts the inverted index of a property, identified by indexName. The body describes the desired index configuration; the server diffs it against the current… - DELETEDelete a property's inverted index
/schema/:className/properties/:propertyName/index/:indexNameDeletes an inverted index of a specific property within a collection (className). The index to delete is identified by indexName and must be one of… - POSTRebuild a property's inverted index with unchanged configuration
/schema/:className/properties/:propertyName/index/:indexName/rebuild?tenants=stringRebuilds the inverted index from the stored objects with its current configuration (repair / format refresh). No request body. Index-mutating work is… - POSTCancel the in-flight reindex task on a property's inverted index
/schema/:className/properties/:propertyName/index/:indexName/cancelCancels the in-flight reindex task targeting this property's index. No request body. Idempotent: succeeds whether or not a task was in flight (a 202 with… - POSTTokenize text using a property's configuration
/schema/:className/properties/:propertyName/tokenizeTokenizes the provided text using the tokenization method configured for the specified property. This endpoint automatically applies the property's… - DELETEDelete a collection's vector index.
/schema/:className/vectors/:vectorIndexName/indexDeletes a specific vector index within a collection (className). The vector index to delete is identified by vectorIndexName. - GETGet the shards status of a collection
/schema/:className/shards?tenant=stringRetrieves the status of all shards associated with the specified collection (className). For multi-tenant collections, use the tenant query parameter to… - PUTUpdate a shard status
/schema/:className/shards/:shardNameUpdates the status of a specific shard within a collection (e.g., sets it to READY or READONLY). This is typically used after resolving an underlying issue… - GETGet the list of tenants
/schema/:className/tenantsRetrieves a list of all tenants currently associated with the specified collection. - PUTUpdate a tenant
/schema/:className/tenantsUpdates the activity status (e.g., ACTIVE, INACTIVE, etc.) of one or more specified tenants within a collection (className). - POSTCreate a new tenant
/schema/:className/tenantsCreates one or more new tenants for a specified collection (className). Multi-tenancy must be enabled for the collection via its definition. - DELETEDelete tenants
/schema/:className/tenantsDeletes one or more specified tenants from a collection (className). WARNING: This action permanently deletes all data associated with the specified tenants. - GETGet a specific tenant
/schema/:className/tenants/:tenantNameRetrieves details about a specific tenant within the given collection (className), such as its current activity status. - HEADCheck if a tenant exists
/schema/:className/tenants/:tenantNameChecks for the existence of a specific tenant within the given collection (className). - GETList aliases
/aliases?class=stringRetrieve a list of all aliases in the system. Results can be filtered by specifying a collection (class) name to get aliases for a specific collection only. - POSTCreate a new alias
/aliasesCreate a new alias mapping between an alias name and a collection (class). The alias acts as an alternative name for accessing the collection. - GETGet an alias
/aliases/:aliasNameRetrieve details about a specific alias by its name, including which collection (class) it points to. - PUTUpdate an alias
/aliases/:aliasNameUpdate an existing alias to point to a different collection (class). This allows you to redirect an alias from one collection to another without changing the… - DELETEDelete an alias
/aliases/:aliasNameRemove an existing alias from the system. This will delete the alias mapping but will not affect the underlying collection (class).
backups
- GETList all created backups
/backups/:backend?order=descList all created backups IDs, Status - POSTCreate a backup
/backups/:backendInitiates the creation of a backup for specified collections on a designated backend storage.<br/><br/>Notes:<br/>- Backups are compressed using gzip by… - GETGet backup creation status
/backups/:backend/:id?bucket=string&path=stringChecks the status of a specific backup creation process identified by its ID on the specified backend.<br/><br/>Client libraries often provide a 'wait for… - DELETECancel a backup
/backups/:backend/:id?bucket=string&path=stringCancels an ongoing backup operation identified by its ID. - GETGet backup restoration status
/backups/:backend/:id/restore?bucket=string&path=stringChecks the status of a specific backup restoration process identified by the backup ID on the specified backend.<br/><br/>Client libraries often provide a… - POSTRestore from a backup
/backups/:backend/:id/restoreInitiates the restoration of collections from a specified backup located on a designated backend.<br/><br/>Requirements:<br/>- Target cluster must have the… - DELETECancel a backup restoration
/backups/:backend/:id/restore?bucket=string&path=stringCancels an ongoing backup restoration process identified by its ID on the specified backend storage.
users
- GETGet current user info
/users/own-infoGet information about the currently authenticated user, including username and assigned roles. - GETList all users
/users/db?includeLastUsedTime=falseRetrieves a list of all database (db user type) users with their roles and status information. - GETGet user info
/users/db/:user_id?includeLastUsedTime=falseRetrieve detailed information about a specific database user (db user type), including their roles, status, and type. - POSTCreate a new user
/users/db/:user_idCreate a new database (db user type) user with the specified name. Returns an API key for the newly created user. - DELETEDelete a user
/users/db/:user_idDelete a database user. You can't delete your current user. - POSTRotate API key of a user
/users/db/:user_id/rotate-keyRevoke the current API key for the specified database user (db user type) and generate a new one. - POSTActivate a user
/users/db/:user_id/activateActivate a deactivated database user (db user type). - POSTDeactivate a user
/users/db/:user_id/deactivateDeactivate a database user (db user type). - PUTSet a user's expiration
/users/db/:user_id/expirationSet or clear the time at which a database user's (db user type) API key stops authenticating. The body sets exactly one of expiresAt, which must be in the…
authz
- GETGet all roles
/authz/rolesGet all roles and their assigned permissions. - POSTCreate new role
/authz/rolesCreate a new role with the specified permissions. - POSTAdd permissions to a role
/authz/roles/:id/add-permissionsAdd new permissions to an existing role without affecting current permissions. - POSTRemove permissions from a role
/authz/roles/:id/remove-permissionsPermissions can be revoked from a specified role. Removing all permissions from a role will delete the role itself. - GETGet a role
/authz/roles/:idFetch a role by its name. - DELETEDelete a role
/authz/roles/:idDeleting a role will remove it from the system, and revoke the associated permissions from all users who had this role. - POSTCheck whether a role possesses a permission
/authz/roles/:id/has-permissionCheck whether a role has the specified permissions. - GETGet users assigned to a role
/authz/roles/:id/usersDeprecated. Get all the users (db + oidc) who have been assigned a specific role. Deprecated, will be removed when v1.29 is not supported anymore. - GETGet users assigned to a role
/authz/roles/:id/user-assignmentsFetch a list of users which have the specified role. - GETGet groups that have a specific role assigned
/authz/roles/:id/group-assignmentsRetrieves a list of all groups that have been assigned a specific role, identified by its name. - GETGet roles assigned to a user
/authz/users/:id/rolesDeprecated. Retrieve the roles assigned to a specific user (db + oidc). Deprecated, will be removed when 1.29 is not supported anymore - GETGet roles assigned to a user
/authz/users/:id/roles/:userType?includeFullRoles=falseGet all the roles for a specific user (db or oidc). - POSTAssign a role to a user
/authz/users/:id/assignAssign one or more roles to a user. Users can have multiple roles. - POSTRevoke a role from a user
/authz/users/:id/revokeRemove one or more roles from a user. - POSTAssign a role to a group
/authz/groups/:id/assignAssign roles to the specified group. - POSTRevoke a role from a group
/authz/groups/:id/revokeRevoke roles from the specified group. - GETGet roles assigned to a specific group
/authz/groups/:id/roles/:groupType?includeFullRoles=falseRetrieves a list of all roles assigned to a specific group. The group must be identified by both its name (id) and its type (db or oidc). - GETList all groups of a specific type
/authz/groups/:groupTypeRetrieves a list of all available group names for a specified group type (oidc or db).
replication
- POSTInitiate a replica movement
/replication/replicateBegins an asynchronous operation to move or copy a specific shard replica from its current node to a designated target node. The operation involves copying… - DELETEDelete all replication operations
/replication/replicateSchedules all replication operations for deletion across all collections, shards, and nodes. - POSTForce delete replication operations
/replication/replicate/force-deleteUSE AT OWN RISK! Synchronously force delete operations from the FSM. This will not perform any checks on which state the operation is in so may lead to data… - GETRetrieve a replication operation
/replication/replicate/:id?includeHistory=trueFetches the current status and detailed information for a specific replication operation, identified by its unique ID. Optionally includes historical data of… - DELETEDelete a replication operation
/replication/replicate/:idRemoves a specific replication operation. If the operation is currently active, it will be cancelled and its resources cleaned up before the operation is… - GETList replication operations
/replication/replicate/list?targetNode=string&collection=string&shard=string&includeHistory=trueRetrieves a list of currently registered replication operations, optionally filtered by collection, shard, or node ID. - POSTCancel a replication operation
/replication/replicate/:id/cancelRequests the cancellation of an active replication operation identified by its ID. The operation will be stopped, but its record will remain in the CANCELLED… - GETGet sharding state
/replication/sharding-state?collection=string&shard=stringFetches the current sharding state, including replica locations and statuses, for all collections or a specified collection. If a shard name is provided along… - GETGet replication scale plan
/replication/scale?collection=string&replicationFactor=1Computes and returns a replication scale plan for a given collection and desired replication factor. The plan includes, for each shard, a list of nodes to be… - POSTApply replication scaling plan
/replication/scaleApply a replication scaling plan that specifies nodes to add or remove per shard for a given collection. - GETGet the rebalance plan
/replication/rebalanceReturns the cluster's rebalance plan, including the node measurements and baseline balance taken by its planning run. - POSTCreate a rebalance plan
/replication/rebalanceCreates the cluster's rebalance plan in the PLANNING state and starts an asynchronous planning run. The run measures the listed source and target nodes and… - DELETEDelete the rebalance plan
/replication/rebalanceRemoves the cluster's rebalance plan. Only a PROPOSED plan or a plan in an end state can be deleted; stop a PLANNING plan first. Succeeds when no plan exists. - POSTStop the rebalance plan
/replication/rebalance/stopStops the cluster's rebalance plan while it is PLANNING. The plan ends STOPPED and the result of its planning run is discarded. - POSTApprove the rebalance plan
/replication/rebalance/approveApproves a PROPOSED rebalance plan for execution. Approval is not implemented yet and always answers 501.
mcp
- POSTmcp.post
/mcpMCP Streamable HTTP endpoint. Handles JSON-RPC requests for tool discovery and invocation. Every request is authenticated on its own; no Mcp-Session-Id is… - DELETEmcp.delete
/mcpAccepted so clients that end their session explicitly keep working. The server keeps no session state, so there is nothing to terminate.
namespaces
- GETList namespaces
/namespacesRetrieve the list of all namespaces the caller has permission to see. Callers without any applicable manage_namespaces permission receive an empty list rather… - GETGet a namespace
/namespaces/:namespace_idRetrieve details about a specific namespace by its name. - PUTUpdate a namespace
/namespaces/:namespace_idUpdate a namespace's home_nodes. The new list replaces the namespace's list and applies to future placement decisions only (new collection create, new tenant… - POSTCreate a new namespace
/namespaces/:namespace_idCreate a new cluster-level namespace with the given name. Names must contain only lowercase letters, digits, and hyphens, must start and end with a letter or… - DELETEDelete a namespace
/namespaces/:namespace_idMark a namespace for deletion. The endpoint is asynchronous: the namespace is flipped to the "deleting" state, which stops its dynamic users from… - POSTSuspend a namespace
/namespaces/:namespace_id/suspendMove a namespace to the "suspended" state. Suspending stops the namespace's users from authenticating and blocks the creation of new classes, aliases, users,… - POSTResume a namespace
/namespaces/:namespace_id/resumeReturn a suspended namespace to the "active" state, so its dynamic users authenticate again and its resources accept writes. Repeated calls against an…
well-known
- GETGet OIDC configuration
/.well-known/openid-configurationProvides OpenID Connect (OIDC) discovery information if OIDC authentication is configured for Weaviate. Returns details like the token issuer URL, client ID,…
experimental
- POSTExport all database-user credentials
/experimental/export-db-usersExperimental: this endpoint may change or be removed without notice. Export every database (db user type) user's API-key credential for migration to another… - POSTImport database-user credentials
/experimental/import-db-usersExperimental: this endpoint may change or be removed without notice. Recreate exported database (db user type) user credentials on this cluster under a target…
tokenize
- POSTTokenize text
/tokenizeTokenizes the provided text using the specified tokenization method. This is a stateless utility endpoint useful for debugging and understanding how text will…
export
- POSTStart a new export
/export/:backendInitiates an export operation on the specified backend storage (S3, GCS, Azure, or filesystem). The output format is controlled by the required 'file_format'… - GETGet export status
/export/:backend/:idRetrieves the current status of an export operation, including progress for each collection being exported. - DELETECancel an export
/export/:backend/:idCancels an ongoing export operation identified by its ID.
cluster
- GETGet cluster statistics
/cluster/statisticsProvides statistics about the internal Raft consensus protocol state for the Weaviate cluster.
nodes
- GETGet node status
/nodes?output=minimalRetrieves status information about all nodes in the cluster. Use the output query parameter to control the level of detail. - GETGet node status by collection
/nodes/:className?shardName=string&output=minimalRetrieves status information only for the nodes that host shards for the specified collection (className). Use the output query parameter to control the level…
distributedTasks
- GETLists all distributed tasks in the cluster
/tasks
classifications
- POSTStart a classification
/classifications/Initiates a background classification task based on the provided parameters. Use the GET /classifications/{id} endpoint to monitor the status and retrieve… - GETGet classification status
/classifications/:idRetrieves the status, metadata, and results (if completed) of a classification task identified by its unique ID.
- GETList available endpoints
/Get links to other endpoints to help discover the REST API. - GETCheck application liveness
/.well-known/liveIndicates if the Weaviate instance is running and responsive to basic HTTP requests. Primarily used for health checks, such as Kubernetes liveness probes. - GETCheck application readiness
/.well-known/readyIndicates if the Weaviate instance has completed its startup routines and is prepared to accept user traffic (data import, queries, etc.). Used for readiness…
API details
- Authentication
- OAuth 2.0 (implicit flow)
- Operations
- 131 operations on 88 pathsPOST 51GET 44DELETE 20PUT 11HEAD 3PATCH 2
10 marked deprecated - Main resources
- schema 26objects 21authz 18replication 15users 9backups 7namespaces 7search 5batch 3export 3
- Response formats
application/json- Description format
- Swagger 2.0, API version
1.41.0-rc.0 - Links
- Documentation · OpenAPI document · Support
- Listed from
- Weaviate's published OpenAPI description (weaviate/weaviate) (BSD-3-Clause)
How to test the Weaviate REST API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Weaviate REST API collection, without the publisher's secrets.
- Add your credentialsThis API uses OAuth 2.0 (implicit flow). Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “List objects” (GET /objects?after=string&offset=0&limit=0&include=string&sort=string&order=string&class=string&tenant=string), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Weaviate REST API?
Introduction Weaviate is an open source, AI-native vector database that helps developers create intuitive and reliable AI-powered applications. ### Base Path… It is listed under AI & machine learning and has 131 endpoints.
Who publishes the Weaviate REST API?
It is listed from Weaviate's public API description (an OpenAPI document), not published by Weaviate on Swastik Codes. Anyone who controls weaviate.io can claim the profile by adding a DNS TXT record.
How do I authenticate with the Weaviate REST API?
With OAuth 2.0 (implicit flow).
How many endpoints does the Weaviate REST API have?
131 operations on 88 paths (51 POST, 44 GET, 20 DELETE, 11 PUT, 3 HEAD, 2 PATCH). The largest groups are schema, objects, authz, replication.
Is forking the Weaviate REST API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.