Weaviate REST API
The Weaviate REST API provides full programmatic access to vector database operations including object CRUD, schema management, GraphQL vector search, multi-tenancy, backups, authentication, authorization, and cluster management.
OpenAPI Specification
openapi: 3.0.3
info:
title: Weaviate REST API
description: '# Introduction<br/> Weaviate is an open source, AI-native vector database
that helps developers create intuitive and reliable AI-powered applications. <br/>
### Base Path <br/>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. <br/>
### Questions? <br/>If you have any comments or questions, please feel free to
reach out to us at the community forum [https://forum.weaviate.io/](https://forum.weaviate.io/).
<br/>### Issues? <br/>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).
<br/>### Need more documentation? <br/>For a quickstart, code examples, concepts
and more, please visit our [documentation page](https://docs.weaviate.io/weaviate).'
version: 1.38.0-dev
servers:
- url: http://localhost:8080
description: Local Weaviate instance
security:
- ApiKeyAuth: []
- BearerAuth: []
paths:
/:
get:
summary: Weaviate List Available Endpoints
description: Get links to other endpoints to help discover the REST API.
operationId: weaviate.root
responses:
'200':
description: Weaviate is alive and ready.
content:
application/json:
schema:
type: object
properties:
links:
type: array
items:
$ref: '#/components/schemas/Link'
x-microcks-operation:
delay: 100
/.well-known/live:
get:
summary: Weaviate Check Application Liveness
description: Indicates if the Weaviate instance is running and responsive to
basic HTTP requests. Primarily used for health checks, such as Kubernetes
liveness probes.
operationId: weaviate.wellknown.liveness
responses:
'200':
description: The application is alive and responding to HTTP requests.
x-microcks-operation:
delay: 100
/.well-known/ready:
get:
summary: Weaviate Check Application Readiness
description: Indicates if the Weaviate instance has completed its startup routines
and is prepared to accept user traffic (data import, queries, etc.). Used
for readiness checks, such as Kubernetes readiness probes.
operationId: weaviate.wellknown.readiness
responses:
'200':
description: The application is ready to serve traffic.
'503':
description: The application is not ready to serve traffic. Traffic should
be directed to other available replicas if applicable.
x-microcks-operation:
delay: 100
/.well-known/openid-configuration:
get:
summary: Weaviate Get OIDC Configuration
description: Provides OpenID Connect (OIDC) discovery information if OIDC authentication
is configured for Weaviate. Returns details like the token issuer URL, client
ID, and required scopes.
tags:
- well-known
- oidc
- discovery
responses:
'200':
description: OIDC configuration details returned successfully.
content:
application/json:
schema:
type: object
properties:
href:
type: string
description: The OIDC issuer URL to redirect to for authentication.
clientId:
type: string
description: The OAuth Client ID configured for Weaviate.
scopes:
type: array
description: The required OAuth scopes for authentication.
items:
type: string
'404':
description: OIDC provider is not configured for this Weaviate instance.
'500':
description: An internal server error occurred while retrieving OIDC configuration.
Check the ErrorResponse for details.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
/replication/replicate:
post:
summary: Weaviate Initiate A Replica Movement
description: Begins an asynchronous operation to move or copy a specific shard
replica from its current node to a designated target node. The operation involves
copying data, synchronizing, and potentially decommissioning the source replica.
tags:
- replication
operationId: replicate
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReplicationReplicateReplicaRequest'
responses:
'200':
description: Replication operation registered successfully. ID of the operation
is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/ReplicationReplicateReplicaResponse'
'400':
description: Malformed request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: The request syntax is correct, but the server couldn't process
it due to semantic issues. Please check the values in your request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An error has occurred while trying to fulfill the request.
Most likely the ErrorResponse will contain more information about the
error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'501':
description: Replica movement operations are disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
delete:
summary: Weaviate Delete All Replication Operations
description: Schedules all replication operations for deletion across all collections,
shards, and nodes.
tags:
- replication
operationId: deleteAllReplications
responses:
'204':
description: Replication operation registered successfully
'400':
description: Malformed request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: The request syntax is correct, but the server couldn't process
it due to semantic issues. Please check the values in your request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An error has occurred while trying to fulfill the request.
Most likely the ErrorResponse will contain more information about the
error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'501':
description: Replica movement operations are disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
/replication/replicate/force-delete:
post:
summary: Weaviate Force Delete Replication Operations
description: USE 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 corruption or loss. It is recommended to first scale the
number of replication engine workers to 0 before calling this endpoint to
ensure no operations are in-flight.
tags:
- replication
operationId: forceDeleteReplications
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReplicationReplicateForceDeleteRequest'
responses:
'200':
description: Replication operations force deleted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ReplicationReplicateForceDeleteResponse'
'400':
description: Malformed request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: The request syntax is correct, but the server couldn't process
it due to semantic issues. Please check the values in your request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An error has occurred while trying to fulfill the request.
Most likely the ErrorResponse will contain more information about the
error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
/replication/replicate/{id}:
get:
summary: Weaviate Retrieve A Replication Operation
description: Fetches the current status and detailed information for a specific
replication operation, identified by its unique ID. Optionally includes historical
data of the operation's progress if requested.
tags:
- replication
operationId: replicationDetails
parameters:
- name: id
in: path
required: true
description: The ID of the replication operation to get details for.
schema:
type: string
format: uuid
- name: includeHistory
in: query
required: false
description: Whether to include the history of the replication operation.
schema:
type: boolean
responses:
'200':
description: The details of the replication operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ReplicationReplicateDetailsReplicaResponse'
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Shard replica operation not found.
'422':
description: The request syntax is correct, but the server couldn't process
it due to semantic issues. Please check the values in your request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An error has occurred while trying to fulfill the request.
Most likely the ErrorResponse will contain more information about the
error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'501':
description: Replica movement operations are disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
delete:
summary: Weaviate Delete A Replication Operation
description: Removes a specific replication operation. If the operation is currently
active, it will be cancelled and its resources cleaned up before the operation
is deleted.
tags:
- replication
operationId: deleteReplication
parameters:
- name: id
in: path
required: true
description: The ID of the replication operation to delete.
schema:
type: string
format: uuid
responses:
'204':
description: Successfully deleted.
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Shard replica operation not found.
'409':
description: The operation is not in a deletable state, e.g. it is a MOVE
op in the DEHYDRATING state.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: The request syntax is correct, but the server couldn't process
it due to semantic issues. Please check the values in your request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An error has occurred while trying to fulfill the request.
Most likely the ErrorResponse will contain more information about the
error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'501':
description: Replica movement operations are disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
/replication/replicate/list:
get:
summary: Weaviate List Replication Operations
description: Retrieves a list of currently registered replication operations,
optionally filtered by collection, shard, or node ID.
tags:
- replication
operationId: listReplication
parameters:
- name: targetNode
in: query
required: false
description: The name of the target node to get details for.
schema:
type: string
- name: collection
in: query
required: false
description: The name of the collection to get details for.
schema:
type: string
- name: shard
in: query
required: false
description: The shard to get details for.
schema:
type: string
- name: includeHistory
in: query
required: false
description: Whether to include the history of the replication operation.
schema:
type: boolean
responses:
'200':
description: The details of the replication operations.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ReplicationReplicateDetailsReplicaResponse'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An error has occurred while trying to fulfill the request.
Most likely the ErrorResponse will contain more information about the
error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'501':
description: Replica movement operations are disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
/replication/replicate/{id}/cancel:
post:
summary: Weaviate Cancel A Replication Operation
description: Requests the cancellation of an active replication operation identified
by its ID. The operation will be stopped, but its record will remain in the
`CANCELLED` state (can't be resumed) and will not be automatically deleted.
tags:
- replication
operationId: cancelReplication
parameters:
- name: id
in: path
required: true
description: The ID of the replication operation to cancel.
schema:
type: string
format: uuid
responses:
'204':
description: Successfully cancelled.
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Shard replica operation not found.
'409':
description: The operation is not in a cancellable state, e.g. it is READY
or is a MOVE op in the DEHYDRATING state.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: The request syntax is correct, but the server couldn't process
it due to semantic issues. Please check the values in your request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An error has occurred while trying to fulfill the request.
Most likely the ErrorResponse will contain more information about the
error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'501':
description: Replica movement operations are disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
/replication/sharding-state:
get:
summary: Weaviate Get Sharding State
description: Fetches the current sharding state, including replica locations
and statuses, for all collections or a specified collection. If a shard name
is provided along with a collection, the state for that specific shard is
returned.
tags:
- replication
operationId: getCollectionShardingState
parameters:
- name: collection
in: query
required: false
description: The collection name to get the sharding state for.
schema:
type: string
- name: shard
in: query
required: false
description: The shard to get the sharding state for.
schema:
type: string
responses:
'200':
description: Successfully retrieved sharding state.
content:
application/json:
schema:
$ref: '#/components/schemas/ReplicationShardingStateResponse'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Collection or shard not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An error has occurred while trying to fulfill the request.
Most likely the ErrorResponse will contain more information about the
error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'501':
description: Replica movement operations are disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
/replication/scale:
get:
summary: Weaviate Get Replication Scale Plan
description: Computes 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 added and a list of nodes to be removed.
tags:
- replication
operationId: getReplicationScalePlan
parameters:
- name: collection
in: query
required: true
description: The collection name to get the scaling plan for.
schema:
type: string
- name: replicationFactor
in: query
required: true
description: The desired replication factor to scale to. Must be a positive
integer greater than zero.
schema:
type: integer
minimum: 1
responses:
'200':
description: Replication scale plan showing node additions and removals
per shard.
content:
application/json:
schema:
$ref: '#/components/schemas/ReplicationScalePlan'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Collection not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An error has occurred while trying to fulfill the request.
Most likely the ErrorResponse will contain more information about the
error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'501':
description: Replica movement operations are disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
post:
summary: Weaviate Apply Replication Scaling Plan
description: Apply a replication scaling plan that specifies nodes to add or
remove per shard for a given collection.
tags:
- replication
operationId: applyReplicationScalePlan
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReplicationScalePlan'
responses:
'200':
description: List of replication shard copy operation IDs initiated for
the scale operation
content:
application/json:
schema:
$ref: '#/components/schemas/ReplicationScaleApplyResponse'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Collection not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An error has occurred while trying to fulfill the request.
Most likely the ErrorResponse will contain more information about the
error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'501':
description: Replica movement operations are disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
/users/own-info:
get:
summary: Weaviate Get Current User Info
description: Get information about the currently authenticated user, including
username and assigned roles.
tags:
- users
operationId: getOwnInfo
responses:
'200':
description: Info about the user.
content:
application/json:
schema:
$ref: '#/components/schemas/UserOwnInfo'
'401':
description: Unauthorized or invalid credentials.
'500':
description: An error has occurred while trying to fulfill the request.
Most likely the ErrorResponse will contain more information about the
error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'501':
description: Replica movement operations are disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
/users/db:
get:
summary: Weaviate List All Users
description: Retrieves a list of all database (`db` user type) users with their
roles and status information.
tags:
- users
operationId: listAllUsers
parameters:
- name: includeLastUsedTime
in: query
required: false
description: Whether to include the last time the users were utilized.
schema:
type: boolean
default: false
responses:
'200':
description: Info about the users.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DBUserInfo'
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An error has occurred while trying to fulfill the request.
Most likely the ErrorResponse will contain more information about the
error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
/users/db/{user_id}:
get:
summary: Weaviate Get User Info
description: Retrieve detailed information about a specific database user (`db`
user type), including their roles, status, and type.
tags:
- users
operationId: getUserInfo
parameters:
- name: user_id
in: path
required: true
description: The name of the user.
schema:
type: string
- name: includeLastUsedTime
in: query
required: false
description: Whether to include the last used time of the given user
schema:
type: boolean
default: false
responses:
'200':
description: Info about the user.
content:
application/json:
schema:
$ref: '#/components/schemas/DBUserInfo'
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: User not found.
'422':
description: The request syntax is correct, but the server couldn't process
it due to semantic issues. Please check the values in your request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: An error has occurred while trying to fulfill the request.
Most likely the ErrorResponse will contain more information about the
error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-microcks-operation:
delay: 100
post:
summary: Weaviate Create A New User
description: Create a new database (`db` user type) user with the specified
name. Returns an API key for the newly created user.
tags:
- users
operationId: createUser
parameters:
- name: user_id
in: path
required: true
description: The name of the user.
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
import:
type: boolean
description: EXPERIMENTAL, DONT USE. THIS WILL BE REMOVED AGAIN.
- import api key from static user
default: false
createTime:
type: string
format: date-time
description: EXPERIMENTAL, DONT USE. THIS WILL BE REMOVED AGAIN.
- set the given time as creation time
namespace:
type: string
description: Namespace to bind the new user to. Required on namespace-enabled
clusters. Must be set by a global operator only.
responses:
'201':
description: User created successfully and API key returned.
content:
application/json:
schema:
$ref: '#/components/schemas/UserApiKey'
'400':
description: Malformed request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized or invalid credentials.
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: User not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: A user with the specified name already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: The request syntax is correct, but the server couldn't process
# --- truncated at 32 KB (305 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/weaviate/refs/heads/main/openapi/weaviate-openapi.yml