Weaviate objects API

openapi: 3.0.3
info:
  title: Weaviate REST authz objects 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: objects
paths:
  /objects:
    get:
      summary: Weaviate List Objects
      description: Retrieves a list of data objects. By default, objects are returned in reverse order of creation. Requires a collection name (`class`) parameter to specify which collection's objects to list, otherwise, returns an empty list.
      tags:
      - objects
      operationId: objects.list
      parameters:
      - name: after
        in: query
        required: false
        description: A threshold UUID of the objects to retrieve after, using an UUID-based ordering. This object is not part of the set. <br/><br/>Must be used with collection name (`class`), typically in conjunction with `limit`. <br/><br/>Note `after` cannot be used with `offset` or `sort`. <br/><br/>For a null value similar to offset=0, set an empty string in the request, i.e. `after=` or `after`.
        schema:
          type: string
      - name: offset
        in: query
        required: false
        description: The starting index of the result window. Note `offset` will retrieve `offset+limit` results and return `limit` results from the object with index `offset` onwards. Limited by the value of `QUERY_MAXIMUM_RESULTS`. <br/><br/>Should be used in conjunction with `limit`. <br/><br/>Cannot be used with `after`.
        schema:
          type: integer
          format: int64
          default: 0
      - name: limit
        in: query
        required: false
        description: The maximum number of items to be returned per page. The default is 25 unless set otherwise as an environment variable.
        schema:
          type: integer
          format: int64
      - name: include
        in: query
        required: false
        description: 'Include additional information, such as classification information. Allowed values include: `classification`, `vector` and `interpretation`.'
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: Name(s) of the property to sort by - e.g. `city`, or `country,city`.
        schema:
          type: string
      - name: order
        in: query
        required: false
        description: 'Order parameter to tell how to order (asc or desc) data within given field. Should be used in conjunction with `sort` parameter. If providing multiple `sort` values, provide multiple `order` values in corresponding order, e.g.: `sort=author_name,title&order=desc,asc`.'
        schema:
          type: string
      - name: class
        in: query
        required: false
        description: The collection from which to query objects.  <br/><br/>Note that if the collection name (`class`) is not provided, the response will not include any objects.
        schema:
          type: string
      - name: tenant
        in: query
        required: false
        description: Specifies the tenant in a request targeting a multi-tenant collection (class).
        schema:
          type: string
      responses:
        '200':
          description: Successful response containing the list of objects. If the collection name (`class`) is not provided, the response will not include any objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectsListResponse'
        '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: Successful query result but no matching objects were 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. Ensure the specified collection exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error occurred while trying to fulfill the request. Check the ErrorResponse for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
    post:
      summary: Weaviate Create An Object
      description: Creates 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 large number of objects, using the `/batch/objects` endpoint is significantly more efficient than sending multiple single requests.<br/><br/>**Note (idempotence)**:<br/>This operation (POST) fails if an object with the provided ID already exists. To update an existing object, use the PUT or PATCH methods.
      tags:
      - objects
      operationId: objects.create
      parameters:
      - name: consistency_level
        in: query
        required: false
        description: Determines how many replicas must acknowledge a request before it is considered successful.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Object'
      responses:
        '200':
          description: Object created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '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. Ensure the collection exists and the object properties are valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error occurred while trying to fulfill the request. Check the ErrorResponse for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
  /objects/{id}:
    delete:
      summary: Weaviate Delete An Object
      description: '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 the `/objects/{className}/{id}` endpoint instead.'
      tags:
      - objects
      operationId: objects.delete
      parameters:
      - name: id
        in: path
        required: true
        description: Unique UUID of the object to be deleted.
        schema:
          type: string
          format: uuid
      - name: consistency_level
        in: query
        required: false
        description: Determines how many replicas must acknowledge a request before it is considered successful.
        schema:
          type: string
      - name: tenant
        in: query
        required: false
        description: Specifies the tenant in a request targeting a multi-tenant collection (class).
        schema:
          type: string
      responses:
        '204':
          description: Object deleted successfully.
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Object not found.
        '500':
          description: An error occurred while trying to fulfill the request. Check the ErrorResponse for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
    get:
      summary: Weaviate Get An Object
      description: '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 future version. Use the `/objects/{className}/{id}` endpoint instead.'
      tags:
      - objects
      operationId: objects.get
      parameters:
      - name: id
        in: path
        required: true
        description: Unique UUID of the object to be retrieved.
        schema:
          type: string
          format: uuid
      - name: include
        in: query
        required: false
        description: 'Include additional information, such as classification information. Allowed values include: `classification`, `vector` and `interpretation`.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response containing the object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '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: Object not found.
        '500':
          description: An error occurred while trying to fulfill the request. Check the ErrorResponse for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
    patch:
      summary: Weaviate Patch An Object
      description: 'Update an object based on its UUID (using patch semantics). This method supports json-merge style patch semantics (RFC 7396). Provided meta-data and schema values are validated. `lastUpdateTimeUnix` is set to the time this function is called. <br/><br/>**Note**: This endpoint is deprecated and will be removed in a future version. Use the `/objects/{className}/{id}` endpoint instead.'
      tags:
      - objects
      operationId: objects.patch
      parameters:
      - name: id
        in: path
        required: true
        description: Unique UUID of the object to be patched.
        schema:
          type: string
          format: uuid
      - name: consistency_level
        in: query
        required: false
        description: Determines how many replicas must acknowledge a request before it is considered successful.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Object'
      responses:
        '204':
          description: Object patched successfully.
        '400':
          description: Malformed patch request body.
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Object not found.
        '422':
          description: The patch object is valid JSON but is unprocessable for other reasons (e.g., invalid schema).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error occurred while trying to fulfill the request. Check the ErrorResponse for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
    put:
      summary: Weaviate Update An Object
      description: 'Updates an object based on its UUID. Given meta-data and schema values are validated. `lastUpdateTimeUnix` is set to the time this function is called. <br/><br/>**Note**: This endpoint is deprecated and will be removed in a future version. Use the `/objects/{className}/{id}` endpoint instead.'
      tags:
      - objects
      operationId: objects.update
      parameters:
      - name: id
        in: path
        required: true
        description: Unique UUID of the object to be replaced.
        schema:
          type: string
          format: uuid
      - name: consistency_level
        in: query
        required: false
        description: Determines how many replicas must acknowledge a request before it is considered successful.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Object'
      responses:
        '200':
          description: Object replaced successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Object 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. Ensure the collection exists and the object properties are valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error occurred while trying to fulfill the request. Check the ErrorResponse for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
    head:
      summary: Weaviate Check If An Object Exists
      description: '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. Use the `/objects/{className}/{id}` endpoint instead.'
      tags:
      - objects
      operationId: objects.head
      parameters:
      - name: id
        in: path
        required: true
        description: Unique UUID of the object to check.
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Object exists.
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Object does not exist.
        '500':
          description: An error occurred while trying to fulfill the request. Check the ErrorResponse for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
  /objects/{className}/{id}:
    get:
      summary: Weaviate Get An Object
      description: Get a data object based on its collection name (`className`) and UUID (`id`).
      tags:
      - objects
      operationId: objects.class.get
      parameters:
      - name: className
        in: path
        required: true
        description: Name of the collection (class) the object belongs to.
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Unique UUID of the object to be retrieved.
        schema:
          type: string
          format: uuid
      - name: include
        in: query
        required: false
        description: 'Include additional information, such as classification information. Allowed values include: `classification`, `vector` and `interpretation`.'
        schema:
          type: string
      - name: consistency_level
        in: query
        required: false
        description: Determines how many replicas must acknowledge a request before it is considered successful.
        schema:
          type: string
      - name: node_name
        in: query
        required: false
        description: The target node which should fulfill the request.
        schema:
          type: string
      - name: tenant
        in: query
        required: false
        description: Specifies the tenant in a request targeting a multi-tenant collection (class).
        schema:
          type: string
      responses:
        '200':
          description: Successful response containing the object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '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: Object 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 occurred while trying to fulfill the request. Check the ErrorResponse for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
    delete:
      summary: Weaviate Delete An Object
      description: Removes a data object from a specific collection, identified by its collection name (`className`) and UUID (`id`).<br/><br/>**Note on deleting references (legacy format):**<br/>For backward compatibility with older beacon formats (lacking a collection name), deleting a reference requires the beacon in the request to exactly match the stored format. Beacons always use `localhost` as the host, indicating the target is within the same Weaviate instance.
      tags:
      - objects
      operationId: objects.class.delete
      parameters:
      - name: className
        in: path
        required: true
        description: Name of the collection (class) the object belongs to.
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Unique UUID of the object to be deleted.
        schema:
          type: string
          format: uuid
      - name: consistency_level
        in: query
        required: false
        description: Determines how many replicas must acknowledge a request before it is considered successful.
        schema:
          type: string
      - name: tenant
        in: query
        required: false
        description: Specifies the tenant in a request targeting a multi-tenant collection (class).
        schema:
          type: string
      responses:
        '204':
          description: Object deleted 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'
        '404':
          description: Object 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 occurred while trying to fulfill the request. Check the ErrorResponse for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
    put:
      summary: Weaviate Replace An Object
      description: Replaces properties of an existing data object. The object is identified by its collection name (`className`) and UUID (`id`). The request body must contain the complete object definition with the new property values.
      tags:
      - objects
      operationId: objects.class.put
      parameters:
      - name: className
        in: path
        required: true
        description: Name of the collection (class) the object belongs to.
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Unique UUID of the object to be replaced.
        schema:
          type: string
          format: uuid
      - name: consistency_level
        in: query
        required: false
        description: Determines how many replicas must acknowledge a request before it is considered successful.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Object'
      responses:
        '200':
          description: Object replaced successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Object 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. Ensure the collection exists and the object properties are valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error occurred while trying to fulfill the request. Check the ErrorResponse for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
    patch:
      summary: Weaviate Patch An Object
      description: Updates specific properties of an existing data object using JSON merge patch semantics (RFC 7396). The object is identified by its collection name (`className`) and UUID (`id`). Only the fields provided in the request body are modified. Metadata and schema values are validated, and the object's `lastUpdateTimeUnix` is updated.
      tags:
      - objects
      operationId: objects.class.patch
      parameters:
      - name: className
        in: path
        required: true
        description: Name of the collection (class) the object belongs to.
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Unique UUID of the object to be patched.
        schema:
          type: string
          format: uuid
      - name: consistency_level
        in: query
        required: false
        description: Determines how many replicas must acknowledge a request before it is considered successful.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Object'
      responses:
        '204':
          description: Object patched successfully.
        '400':
          description: Malformed patch request body.
          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: Object not found.
        '422':
          description: The patch object is valid JSON but is unprocessable for other reasons (e.g., invalid schema).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error occurred while trying to fulfill the request. Check the ErrorResponse for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
    head:
      summary: Weaviate Check If An Object Exists
      description: Verifies the existence of a specific data object within a collection (class), identified by its collection name (`className`) and UUID (`id`), without returning the object itself.<br/><br/>This is faster than a GET request as it avoids retrieving and processing object data. Existence is confirmed by a 204 No Content status code, while non-existence results in a 404 Not Found.
      tags:
      - objects
      operationId: objects.class.head
      parameters:
      - name: className
        in: path
        required: true
        description: Name of the collection (class) the object belongs to.
        schema:
          type: string
      - name: id
        in: path
        required: true
        description: Unique UUID of the object to check.
        schema:
          type: string
          format: uuid
      - name: consistency_level
        in: query
        required: false
        description: Determines how many replicas must acknowledge a request before it is considered successful.
        schema:
          type: string
      - name: tenant
        in: query
        required: false
        description: Specifies the tenant in a request targeting a multi-tenant collection (class).
        schema:
          type: string
      responses:
        '204':
          description: Object exists.
        '401':
          description: Unauthorized or invalid credentials.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Object does not exist.
        '422':
          description: Invalid data provided. Please check the values in your request (e.g., invalid UUID format).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error occurred while trying to fulfill the request. Check the ErrorResponse for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
  /objects/{id}/references/{propertyName}:
    post:
      summary: Weaviate Add An Object Reference
      description: '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 the `/objects/{className}/{id}/references/{propertyName}` endpoint instead.'
      tags:
      - objects
      operationId: objects.references.create
      parameters:
      - name: id
        in: path
        required: true
        description: Unique UUID of the source object.
        schema:
          type: string
          format: uuid
      - name: propertyName
        in: path
        required: true
        description: Unique name of the reference property of the source object.
        schema:
          type: string
      - name: tenant
        in: query
        required: false
        description: Specifies the tenant in a request targeting a multi-tenant collection (class).
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SingleRef'
      responses:
        '200':
          description: Reference added successfully.
        '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. Ensure the property exists and is a reference type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: An error occurred while trying to fulfill the request. Check the ErrorResponse for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 100
    put:
      summary: Weaviate Replace Object References
      description: 'Replace all references in cross-reference property of an object. <br/><br/>**Note**: This endpoint is deprecated and will be removed in a future version. Use the `/objects/{className}/{id}/references/{propertyName}` endpoint instead.'
      tags:
      - objects
      operationId: objects.references.update
      parameters:
      - name: id
        in: path
        required: true
        description: Unique UUID of the source object.
        schema:
          type: string
          format: uuid
      - name: propertyName
        in: path
        required: true
        description: Unique name of the reference property of the source object.
        schema:
          type: string
      - name: tenant
        in: query
        required: false
        description: Specifies the tenant in a request targeting a multi-tenant collection (class).
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultipleRef'
      responses:
        '200':
          description: References replaced successfully.
        '401':
          d

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