ydb-qdrant-tech Service API

openapi: 3.2.0
info:
  title: YDB-Qdrant REST Service 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: Service
  description: Root and health endpoints
paths:
  /:
    parameters:
    - $ref: '#/components/parameters/ApiVersion'
    get:
      operationId: getServiceRoot
      tags:
      - Service
      summary: Get service identity
      description: Returns the ydb-qdrant service title and runtime version on self-hosted servers. The public https://ydb-qdrant.tech/ root serves the static website; use GET /health for public smoke tests.
      servers:
      - url: http://localhost:8080
        description: Self-hosted local server root
      - url: http://ydb-qdrant.tech:8080
        description: HTTP-only public demo Qdrant-compatible server root; use only with non-sensitive demo credentials.
      responses:
        '200':
          description: Service identity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceRoot'
        default:
          $ref: '#/components/responses/Error'
  /health:
    parameters:
    - $ref: '#/components/parameters/ApiVersion'
    get:
      operationId: getHealth
      tags:
      - Service
      summary: Check service health
      description: Returns ok when the HTTP server and YDB health probe are available.
      responses:
        '200':
          description: Service is ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthOk'
              examples:
                ok:
                  value:
                    status: ok
        '503':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
components:
  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
  schemas:
    ServiceRoot:
      type: object
      required:
      - title
      - version
      properties:
        title:
          type: string
          const: ydb-qdrant
        version:
          type: string
    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
    HealthOk:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          const: ok
  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'
  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