ydb-qdrant-tech Points API

openapi: 3.2.0
info:
  title: YDB-Qdrant REST Points API
  summary: Qdrant-compatible vector search API backed by YDB.
  description: YDB-Qdrant exposes a Qdrant-compatible REST subset for collection lifecycle, point upsert, point retrieval, search/query, and point deletion. API keys are used as stable namespace keys. Optional X-Tenant-Id values split one api-key into additional tenant namespaces. The hosted Code Indexer MCP endpoint uses separate bearer tokens created in the dashboard and scoped by GitHub App repository access.
  version: 0.1.0
  license:
    name: MIT
    url: https://github.com/astandrik/ydb-qdrant/blob/main/LICENSE
servers:
- url: https://ydb-qdrant.tech
  description: Public HTTPS API proxy for health, collection, and point routes. The root path serves the static documentation site.
- url: http://ydb-qdrant.tech:8080
  description: HTTP-only public demo Qdrant-compatible base URL; use only with non-sensitive demo credentials.
- url: http://localhost:8080
  description: Self-hosted local server
tags:
- name: Points
  description: Qdrant-compatible point retrieval, upsert, search, query, and delete operations
paths:
  /collections/{collection}/points:
    parameters:
    - $ref: '#/components/parameters/Collection'
    - $ref: '#/components/parameters/TenantId'
    - $ref: '#/components/parameters/ApiVersion'
    post:
      operationId: retrievePoints
      tags:
      - Points
      summary: Retrieve points by id
      description: Retrieves up to 1000 point ids from a collection. with_vector is accepted for Qdrant request compatibility, but the current REST server returns vector as null.
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrievePointsRequest'
      responses:
        '200':
          description: Retrieved points
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievedPointsEnvelope'
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    put:
      operationId: upsertPoints
      tags:
      - Points
      summary: Upsert points
      description: Qdrant-compatible upsert alias. Each point must use the collection vector dimension.
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertPointsRequest'
      responses:
        '200':
          description: Points upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateResultEnvelope'
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /collections/{collection}/points/upsert:
    parameters:
    - $ref: '#/components/parameters/Collection'
    - $ref: '#/components/parameters/TenantId'
    - $ref: '#/components/parameters/ApiVersion'
    post:
      operationId: upsertPointsPost
      tags:
      - Points
      summary: Upsert points with POST
      description: POST alias for upserting points into a collection.
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertPointsRequest'
      responses:
        '200':
          description: Points upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateResultEnvelope'
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /collections/{collection}/points/search:
    parameters:
    - $ref: '#/components/parameters/Collection'
    - $ref: '#/components/parameters/TenantId'
    - $ref: '#/components/parameters/ApiVersion'
    post:
      operationId: searchPoints
      tags:
      - Points
      summary: Search points
      description: Runs exact top-k vector search. For Cosine and Dot, score_threshold is a minimum similarity threshold. For Euclid and Manhattan, score_threshold is a maximum distance threshold.
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchPointsRequest'
            examples:
              search:
                value:
                  vector:
                  - 0.1
                  - 0.2
                  - 0.3
                  top: 10
                  with_payload: true
                  score_threshold: 0.4
      responses:
        '200':
          description: Scored points
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchPointsEnvelope'
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /collections/{collection}/points/query:
    parameters:
    - $ref: '#/components/parameters/Collection'
    - $ref: '#/components/parameters/TenantId'
    - $ref: '#/components/parameters/ApiVersion'
    post:
      operationId: queryPoints
      tags:
      - Points
      summary: Query points
      description: Compatibility endpoint for Qdrant query-style requests. The vector can be supplied as vector, embedding, query.vector, query.nearest.vector, nearest.vector, or the first nested numeric array within the request body.
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryPointsRequest'
      responses:
        '200':
          description: Query response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryPointsEnvelope'
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /collections/{collection}/points/delete:
    parameters:
    - $ref: '#/components/parameters/Collection'
    - $ref: '#/components/parameters/TenantId'
    - $ref: '#/components/parameters/ApiVersion'
    post:
      operationId: deletePoints
      tags:
      - Points
      summary: Delete points
      description: Deletes points by ids, clears all points with an empty filter, or deletes by supported pathSegments.N match filters. Other Qdrant filters are intentionally not supported in this subset.
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeletePointsRequest'
      responses:
        '200':
          description: Delete request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateResultEnvelope'
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
components:
  schemas:
    RetrievePointsRequest:
      type: object
      required:
      - ids
      properties:
        ids:
          type: array
          items:
            $ref: '#/components/schemas/PointId'
          minItems: 1
          maxItems: 1000
        with_payload:
          type: boolean
          default: true
        with_vector:
          type: boolean
          description: Accepted for Qdrant request compatibility. The current REST server returns vector as null in retrieve responses.
          default: false
      additionalProperties: false
    QdrantEnvelope:
      type: object
      required:
      - status
      - result
      - time
      - usage
      properties:
        status:
          type: string
          const: ok
        result: true
        time:
          type: number
          minimum: 0
        usage:
          type: 'null'
    RetrievedPointsEnvelope:
      allOf:
      - $ref: '#/components/schemas/QdrantEnvelope'
      - type: object
        properties:
          result:
            type: array
            items:
              $ref: '#/components/schemas/RetrievedPoint'
    PointStruct:
      type: object
      required:
      - id
      - vector
      properties:
        id:
          $ref: '#/components/schemas/PointId'
        vector:
          type: array
          items:
            type: number
          minItems: 1
        payload:
          $ref: '#/components/schemas/Payload'
      additionalProperties: true
    UpdateResultEnvelope:
      allOf:
      - $ref: '#/components/schemas/QdrantEnvelope'
      - type: object
        properties:
          result:
            $ref: '#/components/schemas/UpdateResult'
    SearchPointsEnvelope:
      allOf:
      - $ref: '#/components/schemas/QdrantEnvelope'
      - type: object
        properties:
          result:
            type: array
            items:
              $ref: '#/components/schemas/ScoredPoint'
    QueryPointsRequest:
      type: object
      description: Loose query compatibility body. A numeric vector may be supplied directly or nested under query/nearest fields.
      properties:
        vector:
          type: array
          items:
            type: number
        embedding:
          type: array
          items:
            type: number
        query: true
        nearest: true
        top:
          type: integer
          minimum: 1
          maximum: 1000
        limit:
          type: integer
          minimum: 1
          maximum: 1000
        with_payload:
          oneOf:
          - type: boolean
          - type: array
          - type: object
        score_threshold:
          type:
          - number
          - 'null'
        filter:
          $ref: '#/components/schemas/PathSegmentsFilter'
      additionalProperties: true
    ErrorResponse:
      type: object
      required:
      - status
      - error
      - code
      - message
      - resolution
      - request_id
      properties:
        status:
          type: string
          const: error
        error:
          type: string
          description: Backward-compatible Qdrant-style error string.
        code:
          type: string
          description: Stable machine-readable error code for agent recovery.
          enum:
          - AUTHENTICATION_REQUIRED
          - BAD_REQUEST
          - COLLECTION_NOT_FOUND
          - HEALTH_CHECK_FAILED
          - INTERNAL_ERROR
          - NOT_FOUND
          - PAYLOAD_TOO_LARGE
          - REQUEST_ABORTED
          - REQUEST_TIMEOUT
          - VALIDATION_ERROR
          - VECTOR_DIMENSION_MISMATCH
        message:
          type: string
          description: Human-readable error message, usually matching error.
        resolution:
          type: string
          description: Actionable hint for clients and AI agents.
        request_id:
          type: string
          description: Request correlation id returned in the X-Request-Id header.
        details:
          type: object
          additionalProperties: true
          description: Optional structured validation or domain-specific details for agent recovery. Shape depends on the error code.
      examples:
      - status: error
        error: collection not found
        code: COLLECTION_NOT_FOUND
        message: collection not found
        resolution: Create the collection first, or check the collection name, api-key, and X-Tenant-Id namespace.
        request_id: req-123
        details:
          collection: documents
    SearchPointsRequest:
      type: object
      required:
      - vector
      properties:
        vector:
          type: array
          items:
            type: number
          minItems: 1
        top:
          type: integer
          minimum: 1
          maximum: 1000
        limit:
          type: integer
          minimum: 1
          maximum: 1000
        with_payload:
          oneOf:
          - type: boolean
          - type: array
          - type: object
        score_threshold:
          type:
          - number
          - 'null'
        filter:
          $ref: '#/components/schemas/PathSegmentsFilter'
      additionalProperties: true
    PathSegmentsCondition:
      type: object
      required:
      - key
      - match
      properties:
        key:
          type: string
          pattern: ^pathSegments\.\d+$
        match:
          type: object
          required:
          - value
          properties:
            value:
              type: string
          additionalProperties: false
      additionalProperties: false
    QueryPointsEnvelope:
      allOf:
      - $ref: '#/components/schemas/QdrantEnvelope'
      - type: object
        properties:
          result:
            type: object
            required:
            - points
            properties:
              points:
                type: array
                items:
                  $ref: '#/components/schemas/ScoredPoint'
    RetrievedPoint:
      type: object
      required:
      - id
      - version
      - payload
      - vector
      - shard_key
      - order_value
      properties:
        id:
          type: string
          description: Stored point id. Numeric request ids are normalized to strings before storage and retrieve responses.
        version:
          type: integer
        payload: true
        vector:
          type: 'null'
          description: Always null in the current retrieve response, even when with_vector is true.
        shard_key:
          type: 'null'
        order_value:
          type: 'null'
    UpdateResult:
      type: object
      required:
      - operation_id
      - status
      properties:
        operation_id:
          type: integer
          const: 0
        status:
          type: string
          const: completed
    PointId:
      description: Point ids accepted by write and lookup requests. Numeric ids are normalized to strings in storage and response objects.
      oneOf:
      - type: string
      - type: number
    ScoredPoint:
      type: object
      required:
      - id
      - version
      - score
      - payload
      - vector
      - shard_key
      - order_value
      properties:
        id:
          type: string
          description: Stored point id. Numeric request ids are normalized to strings before storage and search results.
        version:
          type: integer
        score:
          type: number
        payload:
          oneOf:
          - $ref: '#/components/schemas/Payload'
          - type: 'null'
        vector:
          type: 'null'
          description: Vectors are not returned by the current search/query response projection.
        shard_key:
          type: 'null'
        order_value:
          type: 'null'
    UpsertPointsRequest:
      type: object
      required:
      - points
      properties:
        points:
          type: array
          items:
            $ref: '#/components/schemas/PointStruct'
          minItems: 1
      additionalProperties: false
    DeletePointsRequest:
      oneOf:
      - type: object
        required:
        - points
        properties:
          points:
            type: array
            items:
              $ref: '#/components/schemas/PointId'
            minItems: 1
        additionalProperties: false
      - type: object
        required:
        - filter
        properties:
          filter:
            oneOf:
            - type: object
              maxProperties: 0
              description: Empty filter that clears all points in the collection.
            - $ref: '#/components/schemas/PathSegmentsFilter'
        additionalProperties: false
    PathSegmentsFilter:
      oneOf:
      - type: object
        required:
        - must
        properties:
          must:
            type: array
            items:
              $ref: '#/components/schemas/PathSegmentsCondition'
        additionalProperties: false
      - type: object
        required:
        - should
        properties:
          should:
            type: array
            items:
              type: object
              required:
              - must
              properties:
                must:
                  type: array
                  items:
                    $ref: '#/components/schemas/PathSegmentsCondition'
                  minItems: 1
              additionalProperties: false
            minItems: 1
        additionalProperties: false
    Payload:
      type: object
      additionalProperties: true
  parameters:
    TenantId:
      name: X-Tenant-Id
      in: header
      required: false
      description: Optional tenant suffix within one api-key namespace. Non-alphanumeric characters are normalized to underscores.
      schema:
        type: string
        default: default
        examples:
        - agent-a
        - workspace_42
    Collection:
      name: collection
      in: path
      required: true
      description: Collection name. The backend normalizes names for storage.
      schema:
        type: string
        minLength: 1
        examples:
        - documents
    ApiVersion:
      name: YDB-Qdrant-API-Version
      in: header
      required: false
      description: Optional API contract version pin. Current documented version is 2026-05-28. Omit the header to use the current public contract.
      schema:
        type: string
        enum:
        - '2026-05-28'
        examples:
        - '2026-05-28'
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: Client-supplied stable key for safely retrying mutation requests. Reuse the same value for the same intended create, delete, index, upsert, or point-delete operation.
      schema:
        type: string
        minLength: 1
        maxLength: 255
        examples:
        - upsert-doc-1-20260527
  responses:
    Error:
      description: Structured JSON error response. The error field remains a string for Qdrant-compatible clients; code, message, resolution, request_id, and optional details are included for agent workflows.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            collectionNotFound:
              summary: Collection not found
              value:
                status: error
                error: collection not found
                code: COLLECTION_NOT_FOUND
                message: collection not found
                resolution: Create the collection first, or check the collection name, api-key, and X-Tenant-Id namespace.
                request_id: req-123
            validationError:
              summary: Validation error
              value:
                status: error
                error: validation failed
                code: VALIDATION_ERROR
                message: validation failed
                resolution: Check the request JSON against the OpenAPI schema and required fields.
                request_id: req-124
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: Stable namespace key for YDB-Qdrant REST operations. The backend derives an isolated user namespace from this key. Optional X-Tenant-Id further scopes the namespace. This is not an OAuth role system.
    CodeIndexerBearer:
      type: http
      scheme: bearer
      bearerFormat: opaque MCP token
      description: Dashboard-created token for hosted Code Indexer MCP. Tokens are read-only, stored as hashes, revocable, and scoped by the GitHub App repositories available to the linked user.
externalDocs:
  description: Developer resources and agent-readable docs
  url: https://ydb-qdrant.tech/developers/
x-api-lifecycle:
  current_version: '2026-05-28'
  versioning: Header-based API versioning. Clients may send YDB-Qdrant-API-Version with the documented date value to pin the current REST contract. URL path versioning such as /v1 is not published today.
  deprecation_policy: Backward-incompatible REST API changes will be documented in the OpenAPI description and public docs with at least 90 days of notice when the public hosted API is affected. Deprecated fields or endpoints will remain documented during the notice window with migration guidance.
x-agent-resources:
  llms: https://ydb-qdrant.tech/llms.txt
  llms_full: https://ydb-qdrant.tech/llms-full.txt
  auth_docs: https://ydb-qdrant.tech/docs/auth/
  mcp_server_card: https://ydb-qdrant.tech/.well-known/mcp/server-card.json
  code_indexer_mcp_endpoint: https://code-indexer.ydb-qdrant.tech/mcp