ydb-qdrant-tech Collections API

openapi: 3.2.0
info:
  title: YDB-Qdrant REST Collections 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: Collections
  description: Qdrant-compatible collection metadata operations
paths:
  /collections/{collection}:
    parameters:
    - $ref: '#/components/parameters/Collection'
    - $ref: '#/components/parameters/TenantId'
    - $ref: '#/components/parameters/ApiVersion'
    put:
      operationId: createCollection
      tags:
      - Collections
      summary: Create or confirm a collection
      description: Creates collection metadata for the api-key namespace. Repeating the same vector configuration is idempotent; sending a different vector configuration for an existing collection returns an error.
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCollectionRequest'
            examples:
              cosine384:
                value:
                  vectors:
                    size: 384
                    distance: Cosine
                    data_type: float
      responses:
        '200':
          description: Collection exists with the requested configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanEnvelope'
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    get:
      operationId: getCollection
      tags:
      - Collections
      summary: Get collection metadata
      description: Returns collection status, point count, and vector configuration in the api-key namespace.
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Collection metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionInfoEnvelope'
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      operationId: deleteCollection
      tags:
      - Collections
      summary: Delete a collection
      description: Deletes collection metadata and associated points for the api-key namespace when the collection exists. Missing collections are treated as no-op success by the backend.
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Collection delete accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BooleanEnvelope'
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /collections/{collection}/index:
    parameters:
    - $ref: '#/components/parameters/Collection'
    - $ref: '#/components/parameters/TenantId'
    - $ref: '#/components/parameters/ApiVersion'
    put:
      operationId: putCollectionIndex
      tags:
      - Collections
      summary: Accept a Qdrant payload-index compatibility call
      description: Compatibility endpoint for clients that call PUT /collections/{collection}/index. YDB-Qdrant does not build a separate vector or payload index; search uses the global YDB-backed points table and exact top-k execution.
      security:
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      responses:
        '200':
          description: Index request acknowledged
          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:
    VectorParams:
      type: object
      required:
      - size
      - distance
      properties:
        size:
          type: integer
          minimum: 1
        distance:
          $ref: '#/components/schemas/Distance'
        data_type:
          type: string
          enum:
          - float
          default: float
      additionalProperties: false
    Distance:
      type: string
      enum:
      - Cosine
      - Euclid
      - Dot
      - Manhattan
    CollectionInfo:
      type: object
      required:
      - status
      - points_count
      - name
      - vectors
      - config
      properties:
        status:
          type: string
          examples:
          - green
        points_count:
          type: integer
          minimum: 0
        name:
          type: string
        vectors:
          $ref: '#/components/schemas/VectorParams'
        config:
          type: object
          required:
          - params
          properties:
            params:
              type: object
              required:
              - vectors
              properties:
                vectors:
                  $ref: '#/components/schemas/VectorParams'
    BooleanEnvelope:
      allOf:
      - $ref: '#/components/schemas/QdrantEnvelope'
      - type: object
        properties:
          result:
            type: boolean
    CreateCollectionRequest:
      type: object
      required:
      - vectors
      properties:
        vectors:
          $ref: '#/components/schemas/VectorParams'
      additionalProperties: false
    CollectionInfoEnvelope:
      allOf:
      - $ref: '#/components/schemas/QdrantEnvelope'
      - type: object
        properties:
          result:
            $ref: '#/components/schemas/CollectionInfo'
    UpdateResult:
      type: object
      required:
      - operation_id
      - status
      properties:
        operation_id:
          type: integer
          const: 0
        status:
          type: string
          const: completed
    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
    QdrantEnvelope:
      type: object
      required:
      - status
      - result
      - time
      - usage
      properties:
        status:
          type: string
          const: ok
        result: true
        time:
          type: number
          minimum: 0
        usage:
          type: 'null'
    UpdateResultEnvelope:
      allOf:
      - $ref: '#/components/schemas/QdrantEnvelope'
      - type: object
        properties:
          result:
            $ref: '#/components/schemas/UpdateResult'
  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
  parameters:
    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'
    Collection:
      name: collection
      in: path
      required: true
      description: Collection name. The backend normalizes names for storage.
      schema:
        type: string
        minLength: 1
        examples:
        - documents
    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
    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
  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