Weaviate replication API

openapi: 3.0.3
info:
  title: Weaviate REST authz replication 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: []
tags:
- name: replication
paths:
  /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
components:
  schemas:
    ReplicationReplicateForceDeleteResponse:
      type: object
      description: Provides the UUIDs that were successfully force deleted as part of the replication operation. If dryRun is true, this will return the expected outcome without actually deleting anything.
      properties:
        deleted:
          type: array
          description: The unique identifiers (IDs) of the replication operations that were forcefully deleted.
          items:
            type: string
            format: uuid
        dryRun:
          type: boolean
          description: Indicates whether the operation was a dry run (true) or an actual deletion (false).
    ReplicationShardingState:
      type: object
      description: Details the sharding layout for a specific collection, mapping each shard to its set of replicas across the cluster.
      properties:
        collection:
          type: string
          description: The name of the collection.
        shards:
          type: array
          description: An array detailing each shard within the collection and the nodes hosting its replicas.
          items:
            $ref: '#/components/schemas/ReplicationShardReplicas'
    ReplicationReplicateReplicaResponse:
      type: object
      description: Contains the unique identifier for a successfully initiated asynchronous replica movement operation. This ID can be used to track the progress of the operation.
      required:
      - id
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier (ID) assigned to the registered replication operation.
    ReplicationShardingStateResponse:
      type: object
      description: Provides the detailed sharding state for one or more collections, including the distribution of shards and their replicas across the cluster nodes.
      properties:
        shardingState:
          $ref: '#/components/schemas/ReplicationShardingState'
    ReplicationReplicateForceDeleteRequest:
      type: object
      description: Specifies the parameters available when force deleting replication operations.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier (ID) of the replication operation to be forcefully deleted.
        collection:
          type: string
          description: The name of the collection to which the shard being replicated belongs.
        shard:
          type: string
          description: The identifier of the shard involved in the replication operations.
        node:
          type: string
          description: The name of the target node where the replication operations are registered.
        dryRun:
          type: boolean
          description: If true, the operation will not actually delete anything but will return the expected outcome of the deletion.
          default: false
    ReplicationReplicateReplicaRequest:
      type: object
      description: Specifies the parameters required to initiate a shard replica movement operation between two nodes for a given collection and shard. This request defines the source and target node, the collection and type of transfer.
      required:
      - sourceNode
      - targetNode
      - collection
      - shard
      properties:
        sourceNode:
          type: string
          description: The name of the Weaviate node currently hosting the shard replica that needs to be moved or copied.
        targetNode:
          type: string
          description: The name of the Weaviate node where the new shard replica will be created as part of the movement or copy operation.
        collection:
          type: string
          description: The name of the collection to which the target shard belongs.
        shard:
          type: string
          description: The name of the shard whose replica is to be moved or copied.
        type:
          type: string
          description: Specifies the type of replication operation to perform. `COPY` creates a new replica on the target node while keeping the source replica. `MOVE` creates a new replica on the target node and then removes the source replica upon successful completion. Defaults to `COPY` if omitted.
          enum:
          - COPY
          - MOVE
          default: COPY
    ErrorResponse:
      type: object
      description: An error response returned by Weaviate endpoints.
      properties:
        error:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
    ReplicationReplicateDetailsReplicaStatusError:
      type: object
      description: Represents an error encountered during a replication operation, including its timestamp and a human-readable message.
      properties:
        whenErroredUnixMs:
          type: integer
          format: int64
          description: The unix timestamp in ms when the error occurred. This is an approximate time and so should not be used for precise timing.
        message:
          type: string
          description: A human-readable message describing the error.
    ReplicationReplicateDetailsReplicaStatus:
      type: object
      description: Represents the current or historical status of a shard replica involved in a replication operation, including its operational state and any associated errors.
      properties:
        state:
          type: string
          description: The current operational state of the replica during the replication process.
          enum:
          - REGISTERED
          - HYDRATING
          - FINALIZING
          - DEHYDRATING
          - READY
          - CANCELLED
        whenStartedUnixMs:
          type: integer
          format: int64
          description: The UNIX timestamp in ms when this state was first entered. This is an approximate time and so should not be used for precise timing.
        errors:
          type: array
          description: A list of error messages encountered by this replica during the replication operation, if any.
          items:
            $ref: '#/components/schemas/ReplicationReplicateDetailsReplicaStatusError'
    ReplicationReplicateDetailsReplicaResponse:
      description: Provides a comprehensive overview of a specific replication operation, detailing its unique ID, the involved collection, shard, source and target nodes, transfer type, current status, and optionally, its status history.
      required:
      - id
      - shard
      - sourceNode
      - targetNode
      - collection
      - status
      - type
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier (ID) of this specific replication operation.
        shard:
          type: string
          description: The name of the shard involved in this replication operation.
        collection:
          type: string
          description: The name of the collection to which the shard being replicated belongs.
        sourceNode:
          type: string
          description: The identifier of the node from which the replica is being moved or copied (the source node).
        targetNode:
          type: string
          description: The identifier of the node to which the replica is being moved or copied (the target node).
        type:
          type: string
          description: Indicates whether the operation is a `COPY` (source replica remains) or a `MOVE` (source replica is removed after successful transfer).
          enum:
          - COPY
          - MOVE
        uncancelable:
          type: boolean
          description: Whether the replica operation can't be cancelled.
        scheduledForCancel:
          type: boolean
          description: Whether the replica operation is scheduled for cancellation.
        scheduledForDelete:
          type: boolean
          description: Whether the replica operation is scheduled for deletion.
        status:
          $ref: '#/components/schemas/ReplicationReplicateDetailsReplicaStatus'
        statusHistory:
          type: array
          description: An array detailing the historical sequence of statuses the replication operation has transitioned through, if requested and available.
          items:
            $ref: '#/components/schemas/ReplicationReplicateDetailsReplicaStatus'
        whenStartedUnixMs:
          type: integer
          format: int64
          description: The UNIX timestamp in ms when the replication operation was initiated. This is an approximate time and so should not be used for precise timing.
    ReplicationScalePlan:
      type: object
      description: Defines a complete plan for scaling replication within a collection. Each shard entry specifies nodes to remove and nodes to add. Added nodes may either be initialized empty (null) or created by replicating data from a source node specified as a string. If a source node is also marked for removal in the same shard, it represents a move operation and can only be used once as a source for that shard. If a source node is not marked for removal, it represents a copy operation and can be used as the source for multiple additions in that shard. Nodes listed in 'removeNodes' cannot also appear as targets in 'addNodes' for the same shard, and the same node cannot be specified for both addition and removal in a single shard.
      required:
      - planId
      - collection
      - shardScaleActions
      properties:
        planId:
          type: string
          format: uuid
          description: A unique identifier for this replication scaling plan, useful for tracking and auditing purposes.
        collection:
          type: string
          description: The name of the collection to which this replication scaling plan applies.
        shardScaleActions:
          type: object
          description: A mapping of shard names to their corresponding scaling actions. Each key corresponds to a shard name, and its value defines which nodes should be removed and which should be added for that shard. If a source node listed for an addition is also in 'removeNodes' for the same shard, that addition is treated as a move operation. Such a node can appear only once as a source in that shard. Otherwise, if the source node is not being removed, it represents a copy operation and can be referenced multiple times as a source for additions.
          additionalProperties:
            type: object
            des

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/weaviate/refs/heads/main/openapi/weaviate-replication-api-openapi.yml