> ## Documentation Index
> Fetch the complete documentation index at: https://opendata.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upsert vectors

> Upsert one or more vectors into the collection. Each vector has a
user-provided string ID (up to 64 bytes), a dense embedding in the
`vector` attribute, and optional metadata attributes.

If a vector with the same ID already exists, it is replaced.

Supports both binary protobuf (`application/protobuf`) and ProtoJSON
(`application/protobuf+json`) request bodies.




## OpenAPI

````yaml /openapi/vector.yaml post /api/v1/vector/write
openapi: 3.1.0
info:
  title: OpenData Vector API
  version: 1.0.0
  description: >-
    HTTP API for the OpenData Vector service — a semantic search database on
    object storage.
servers:
  - url: http://localhost:8080
    description: Local development server
security: []
paths:
  /api/v1/vector/write:
    post:
      summary: Upsert vectors
      description: |
        Upsert one or more vectors into the collection. Each vector has a
        user-provided string ID (up to 64 bytes), a dense embedding in the
        `vector` attribute, and optional metadata attributes.

        If a vector with the same ID already exists, it is replaced.

        Supports both binary protobuf (`application/protobuf`) and ProtoJSON
        (`application/protobuf+json`) request bodies.
      operationId: write
      requestBody:
        required: true
        content:
          application/protobuf+json:
            schema:
              $ref: '#/components/schemas/WriteRequest'
            example:
              upsertVectors:
                - id: doc-1
                  attributes:
                    vector:
                      - 1
                      - 2
                      - 3
                    category: electronics
                    department: hw
                - id: doc-2
                  attributes:
                    vector:
                      - 4
                      - 5
                      - 6
                    category: books
          application/protobuf:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Vectors upserted successfully.
          content:
            application/protobuf+json:
              schema:
                $ref: '#/components/schemas/UpsertVectorsResponse'
              example:
                status: success
                vectorsUpserted: 2
        '400':
          description: >-
            Invalid input (malformed body, missing ID, missing vector, type
            mismatch).
          content:
            application/protobuf+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/protobuf+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    WriteRequest:
      type: object
      description: Request body for upserting vectors.
      properties:
        upsertVectors:
          type: array
          items:
            $ref: '#/components/schemas/Vector'
          description: One or more vectors to upsert.
      required:
        - upsertVectors
    UpsertVectorsResponse:
      type: object
      description: Response after successfully upserting vectors.
      properties:
        status:
          type: string
          example: success
        vectorsUpserted:
          type: integer
          format: int32
          description: Number of vectors upserted.
      required:
        - status
        - vectorsUpserted
    ErrorResponse:
      type: object
      description: Error response returned for all error cases.
      properties:
        status:
          type: string
          example: error
        message:
          type: string
          description: Human-readable error message.
      required:
        - status
        - message
    Vector:
      type: object
      description: A record with an ID and attributes, including the embedding vector.
      properties:
        id:
          type: string
          maxLength: 64
          description: User-provided unique identifier (up to 64 bytes).
        attributes:
          $ref: '#/components/schemas/Attributes'
      required:
        - id
        - attributes
    Attributes:
      type: object
      description: |
        A flat map of attribute names to values. Must include a `vector` key
        with an array of floats matching the collection's configured dimensions.
        Other keys are metadata attributes whose types must match the collection
        schema (if defined).
      additionalProperties:
        $ref: '#/components/schemas/AttributeValue'
      required:
        - vector
    AttributeValue:
      description: |
        A metadata attribute value. In JSON, values are represented as plain
        scalars or arrays — strings, integers, floats, booleans, or arrays of
        floats (for the vector field).
      oneOf:
        - type: string
          description: String attribute value.
        - type: integer
          format: int64
          description: 64-bit signed integer attribute value.
        - type: number
          format: double
          description: 64-bit floating point attribute value.
        - type: boolean
          description: Boolean attribute value.
        - type: array
          items:
            type: number
            format: float
          description: >-
            Vector attribute (array of f32 values). Used for the reserved
            `vector` field.

````