openapi.yaml

openapi: 3.1.0
info:
  title: VelesDB API
  description: High-performance vector database for AI applications. Supports semantic search, HNSW indexing, and multiple distance metrics. Authentication is optional — when API keys are configured via VELESDB_API_KEYS, all endpoints except /health and /ready require a valid Bearer token.
  contact:
    name: VelesDB Team
    url: https://github.com/cyberlife-coder/VelesDB
  license:
    name: VelesDB Core License 1.0
    url: https://github.com/cyberlife-coder/VelesDB/blob/main/LICENSE
  version: 6.0.0
servers:
- url: /
  description: Local server
paths:
  /aggregate:
    post:
      tags:
      - query
      summary: Execute an aggregation-only VelesQL query.
      description: This endpoint is explicit and stable for GROUP BY / HAVING / aggregate workloads.
      operationId: aggregate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
        required: true
      responses:
        '200':
          description: Aggregation results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregationResponse'
        '400':
          description: Query syntax error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VelesqlErrorResponse'
        '422':
          description: Aggregation validation/execution error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VelesqlErrorResponse'
  /collections:
    get:
      tags:
      - collections
      summary: List all collections.
      operationId: list_collections
      responses:
        '200':
          description: List of collections
          content:
            application/json:
              schema:
                type: object
    post:
      tags:
      - collections
      summary: Create a new collection.
      operationId: create_collection
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCollectionRequest'
        required: true
      responses:
        '201':
          description: Collection created
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
  /collections/{name}:
    get:
      tags:
      - collections
      summary: Get collection information.
      operationId: get_collection
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Collection details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - collections
      summary: Delete a collection.
      operationId: delete_collection
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Collection deleted
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/analyze:
    post:
      tags:
      - collections
      summary: Analyze a collection, computing and persisting statistics.
      operationId: analyze_collection
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Collection analyzed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionStatsResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Analysis failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/compact:
    post:
      tags:
      - collections
      summary: |-
        Compacts the vector storage of a collection, rewriting active vectors
        into a contiguous layout and reclaiming disk space from deleted entries.
      description: |-
        This is a blocking operation that may involve significant I/O for
        large, fragmented collections.
      operationId: compact_collection
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Storage compacted
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Compaction failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/config:
    get:
      tags:
      - collections
      summary: Get detailed collection configuration (HNSW params, storage mode, schema, etc.).
      operationId: get_collection_config
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Collection configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionConfigResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/diagnostics:
    get:
      tags:
      - collections
      summary: Get health diagnostics for a collection (index readiness, point count).
      operationId: collection_diagnostics
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Collection diagnostics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionDiagnosticsResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/empty:
    get:
      tags:
      - collections
      summary: Check if a collection is empty.
      operationId: is_empty
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Empty status
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/flush:
    post:
      tags:
      - collections
      summary: Flush pending changes to disk.
      operationId: flush_collection
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Flushed successfully
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Flush failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/graph/edges:
    get:
      tags:
      - graph
      summary: Get edges from a collection's graph filtered by label.
      operationId: get_edges
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      - name: label
        in: query
        description: Filter edges by label (e.g., "KNOWS", "FOLLOWS").
        required: false
        schema:
          type:
          - string
          - 'null'
        example: KNOWS
      responses:
        '200':
          description: Edges retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EdgesResponse'
        '400':
          description: Missing required 'label' query parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - graph
      summary: Add an edge to a collection's graph.
      operationId: add_edge
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddEdgeRequest'
        required: true
      responses:
        '201':
          description: Edge added successfully
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found, or source/target node has no stored payload (VELES-022 NodeNotFound)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/graph/edges/batch:
    post:
      tags:
      - graph
      summary: Add multiple edges to a collection's graph in one batched operation.
      operationId: add_edges_batch
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddEdgesBatchRequest'
        required: true
      responses:
        '201':
          description: Edges added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddEdgesBatchResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found, or a source/target node has no stored payload (VELES-022 NodeNotFound) — the whole batch is rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/graph/edges/count:
    get:
      tags:
      - graph
      summary: Get the total number of edges in the graph.
      operationId: get_edge_count
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Edge count retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EdgeCountResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/graph/edges/{edge_id}:
    delete:
      tags:
      - graph
      summary: Remove an edge by ID.
      operationId: remove_edge
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      - name: edge_id
        in: path
        description: Edge ID to remove (u64 as a string; precision-safe above 2^53-1)
        required: true
        schema:
          type: string
          pattern: ^[0-9]+$
      responses:
        '204':
          description: Edge removed successfully
        '404':
          description: Edge or collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/graph/nodes:
    get:
      tags:
      - graph
      summary: List all node IDs in the graph.
      operationId: list_nodes
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Node list retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeListResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/graph/nodes/{node_id}/degree:
    get:
      tags:
      - graph
      summary: Get the degree (in and out) of a specific node.
      operationId: get_node_degree
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      - name: node_id
        in: path
        description: Node ID (u64 as a string; precision-safe above 2^53-1)
        required: true
        schema:
          type: string
          pattern: ^[0-9]+$
      responses:
        '200':
          description: Degree retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DegreeResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/graph/nodes/{node_id}/edges:
    get:
      tags:
      - graph
      summary: Get edges for a specific node with direction filtering.
      operationId: get_node_edges
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      - name: node_id
        in: path
        description: Node ID (u64 as a string; precision-safe above 2^53-1)
        required: true
        schema:
          type: string
          pattern: ^[0-9]+$
      - name: direction
        in: query
        description: 'Filter by direction: "in", "out", or "both".'
        required: false
        schema:
          type: string
        example: out
      - name: label
        in: query
        description: Filter edges by label.
        required: false
        schema:
          type:
          - string
          - 'null'
        example: KNOWS
      responses:
        '200':
          description: Node edges retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EdgesResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/graph/nodes/{node_id}/payload:
    get:
      tags:
      - graph
      summary: Get the payload of a graph node.
      operationId: get_node_payload
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      - name: node_id
        in: path
        description: Node ID (u64 as a string; precision-safe above 2^53-1)
        required: true
        schema:
          type: string
          pattern: ^[0-9]+$
      responses:
        '200':
          description: Payload retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodePayloadResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
      - graph
      summary: Upsert a payload on a graph node.
      operationId: upsert_node_payload
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      - name: node_id
        in: path
        description: Node ID (u64 as a string; precision-safe above 2^53-1)
        required: true
        schema:
          type: string
          pattern: ^[0-9]+$
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertNodePayloadRequest'
        required: true
      responses:
        '204':
          description: Payload stored successfully
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/graph/search:
    post:
      tags:
      - graph
      summary: Search graph nodes by embedding similarity.
      operationId: graph_search
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphSearchRequest'
        required: true
      responses:
        '200':
          description: Graph search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphSearchResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/graph/traverse:
    post:
      tags:
      - graph
      summary: Traverse the graph using BFS or DFS from a source node.
      operationId: traverse_graph
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TraverseRequest'
        required: true
      responses:
        '200':
          description: Traversal completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraverseResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/graph/traverse/parallel:
    post:
      tags:
      - graph
      summary: Parallel multi-source BFS traversal.
      operationId: traverse_parallel
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParallelTraverseRequest'
        required: true
      responses:
        '200':
          description: Parallel traversal completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraverseResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
  /collections/{name}/graph/traverse/stream:
    get:
      tags:
      - graph
      summary: Stream graph traversal results via SSE.
      description: |-
        The traversal runs to completion first, then its events are sent:
        - `node`: each node reached
        - `stats`: `nodes_visited` and `elapsed_ms`, after every 100th `node` event
        - `done`: `total_nodes`, `max_depth_reached` and `elapsed_ms`, last
        - `error`: sent alone instead, when the traversal cannot run
      operationId: stream_traverse
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      - name: start_node
        in: query
        description: Source node ID to start traversal from.
        required: true
        schema:
          type: string
          pattern: ^[0-9]+$
        example: '123'
      - name: algorithm
        in: query
        description: 'Traversal algorithm: "bfs" or "dfs".'
        required: false
        schema:
          type: string
        example: bfs
      - name: max_depth
        in: query
        description: Maximum traversal depth.
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
        example: 5
      - name: limit
        in: query
        description: Maximum number of results to stream.
        required: false
        schema:
          type: integer
          minimum: 0
        example: 1000
      - name: relationship_types
        in: query
        description: Filter by relationship types (comma-separated).
        required: false
        schema:
          type:
          - string
          - 'null'
        example: KNOWS,FOLLOWS
      responses:
        '200':
          description: SSE stream of traversal events (node, stats, done, error)
  /collections/{name}/index/rebuild:
    post:
      tags:
      - collections
      summary: |-
        Rebuilds the HNSW index of a vector collection, reclaiming memory
        occupied by tombstoned entries and producing a fresh graph from
        the current vector storage.
      description: |-
        This is a blocking operation: for large collections it may take
        several seconds. The response includes the number of entries that
        were compacted during the rebuild.
      operationId: rebuild_index
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Index rebuilt
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Rebuild failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/indexes:
    get:
      tags:
      - indexes
      summary: List all indexes on a collection.
      operationId: list_indexes
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of indexes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListIndexesResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - indexes
      summary: Create a property index on a graph collection.
      operationId: create_index
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIndexRequest'
        required: true
      responses:
        '201':
          description: Index created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
  /collections/{name}/indexes/{label}/{property}:
    delete:
      tags:
      - indexes
      summary: Delete a property index.
      operationId: delete_index
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      - name: label
        in: path
        description: Node label
        required: true
        schema:
          type: string
      - name: property
        in: path
        description: Property name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Index deleted
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Index or collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/locality/reorder:
    post:
      tags:
      - collections
      summary: |-
        Reorders the HNSW adjacency lists and vector storage for cache
        locality so nodes traversed together during search sit close in
        memory (issue #377). No-op for collections with fewer than 1 000
        vectors. Recall is preserved — only the physical layout changes.
      description: |-
        This is a blocking operation that may involve significant I/O for
        large collections.
      operationId: reorder_for_locality
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Locality reordered
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Reorder failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/match:
    post:
      tags:
      - graph
      summary: Execute a MATCH query on a collection.
      description: |-
        # Endpoint

        `POST /collections/{name}/match`

        # Example Request

        ```json
        {
          "query": "MATCH (a:Person)-[:KNOWS]->(b) WHERE similarity(a.vec, $v) > 0.8 RETURN a.name",
          "params": {
            "v": [0.1, 0.2, 0.3]
          }
        }
        ```

        # Errors

        When the query fails with a core error, the JSON body carries its
        `VELES-XXX` code, and the status follows its variant:
        - `404 NOT_FOUND` (`VELES-002`) — collection not found
        - `400 BAD_REQUEST` (`VELES-010`) — parse error, not a MATCH query,
          invalid threshold, or an unbound query parameter
        - otherwise: `404 NOT_FOUND` for a missing point, edge or node;
          `409 CONFLICT` for a collection or edge that already exists;
          `400 BAD_REQUEST` for other invalid input; `503 SERVICE_UNAVAILABLE`
          for a locked database or a guard rail; `500 INTERNAL_SERVER_ERROR` for
          anything else
      operationId: match_query
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MatchQueryRequest'
        required: true
      responses:
        '200':
          description: Match query results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchQueryResponse'
        '400':
          description: Parse error or invalid query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: A guard rail stopped the query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/points:
    post:
      tags:
      - points
      summary: Upsert points to a collection.
      operationId: upsert_points
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertPointsRequest'
        required: true
      responses:
        '200':
          description: Points upserted
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid request or batch too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
  /collections/{name}/points/delete:
    post:
      tags:
      - points
      summary: Deletes multiple points by ID in a single request.
      description: |-
        Accepts a JSON body with a list of point IDs. All IDs are passed to
        the underlying `Collection::delete(&[u64])` in one call, which is
        more efficient than individual deletions.

        Returns the number of points that were requested for deletion.
        Points that do not exist are silently skipped (idempotent delete).

        # Empty payload semantics

        `{ "ids": [] }` is treated as a successful no-op: the response is
        `200 OK` with `deleted_count = 0`. This matches Kubernetes-style
        idempotent batch APIs and lets callers send empty batches without
        special-casing on the client side.

        # Limits

        Batches larger than `MAX_BULK_DELETE_SIZE` (10000) are rejected with
        `400 BAD_REQUEST`.
      operationId: bulk_delete_points
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDeleteRequest'
        required: true
      responses:
        '200':
          description: Points deleted
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Batch too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
        '500':
          description: Delete failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/points/raw:
    post:
      tags:
      - points
      summary: Bulk upsert points via the binary wire format.
      description: |-
        Accepts an `application/octet-stream` body in the VRB1 raw-bulk format
        (a 16-byte header — magic, count, dim, id_width — followed by tightly-packed
        `u64` ids and `f32` vectors). The vectors are forwarded to
        `Collection::upsert_bulk_from_raw` (zero per-point `Point` allocation).
        Payloads are not supported on this path.
      operationId: upsert_points_raw
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        description: 'VRB1 binary bulk format: header + packed u64 ids + packed f32 vectors'
        content:
          application/octet-stream:
            schema:
              type: string
        required: true
      responses:
        '200':
          description: Points upserted
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Malformed body or dimension mismatch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/points/scroll:
    post:
      tags:
      - points
      summary: Scroll through collection points with cursor-based pagination.
      operationId: scroll_points
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrollRequest'
        required: true
      responses:
        '200':
          description: Scroll batch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScrollResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
  /collections/{name}/points/stream:
    post:
      tags:
      - points
      summary: Stream upsert points using NDJSON.
      description: |-
        Accepts a `application/x-ndjson` body. Each line is one JSON-encoded point,
        whose `id` is an unsigned 64-bit integer: a line that is not blank and does
        not parse as one, a string `id` included, is counted in the response's
        `malformed` field.
        Points are accumulated into micro-batches and flushed via `upsert_bulk`.

        The response body includes a `network_errors` field: a non-zero value means
        the HTTP body stream was truncated (e.g., client disconnect or proxy error),
        and the server may have received fewer points than the client sent (M-7).
      operationId: stream_upsert_points
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        description: NDJSON stream with one point per line
        content:
          application/x-ndjson:
            schema:
              type: string
        required: true
      responses:
        '200':
          description: Stream processed
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/points/{id}:
    get:
      tags:
      - points
      summary: Get a point by ID.
      operationId: get_point
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Point ID (u64 as a string; precision-safe above 2^53-1)
        required: true
        schema:
          type: string
          pattern: ^[0-9]+$
      responses:
        '200':
          description: Point found
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Point or collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - points
      summary: Delete a point by ID.
      operationId: delete_point
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Point ID (u64 as a string; precision-safe above 2^53-1)
        required: true
        schema:
          type: string
          pattern: ^[0-9]+$
      responses:
        '200':
          description: Point deleted
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Point or collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/points/{id}/relations:
    get:
      tags:
      - graph
      summary: List outgoing relation edges for a point.
      operationId: get_point_relations
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Point ID (u64 as a string; precision-safe above 2^53-1)
        required: true
        schema:
          type: string
          pattern: ^[0-9]+$
      responses:
        '200':
          description: Outgoing relations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelationsResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/points/{id}/ttl:
    patch:
      tags:
      - points
      summary: Set (or refresh) the durable TTL of a point.
      description: |-
        Persists `_veles_expires_at` in the point's payload so the expiry
        survives a restart. A `ttl_seconds` of `0` expires the point immediately.
        Expired points are excluded from all read surfaces (search/get/scroll/query);
        refreshing an expired point returns 404; storage is reclaimed lazily.
      operationId: set_point_ttl
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Point ID (u64 as a string; precision-safe above 2^53-1)
        required: true
        schema:
          type: string
          pattern: ^[0-9]+$
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetTtlRequest'
        required: true
      responses:
        '204':
          description: TTL set successfully
        '400':
          description: Non-object payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection or point not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/relations:
    post:
      tags:
      - graph
      summary: Create a relation edge between two points in a collection.
      description: |-
        Works on vector, graph, and metadata collections alike.
        The edge ID is auto-assigned; the response body carries the allocated value.
      operationId: relate_points
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RelateRequest'
        required: true
      responses:
        '201':
          description: Relation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelateResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found, or source/target point has no stored payload (VELES-022 NodeNotFound)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/relations/{edge_id}:
    delete:
      tags:
      - graph
      summary: Remove a relation edge by ID.
      operationId: unrelate_points
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      - name: edge_id
        in: path
        description: Edge ID to remove (u64 as a string; precision-safe above 2^53-1)
        required: true
        schema:
          type: string
          pattern: ^[0-9]+$
      responses:
        '204':
          description: Relation removed
        '404':
          description: Collection or edge not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/sanity:
    get:
      tags:
      - collections
      summary: Run a quick sanity check for onboarding and troubleshooting.
      operationId: collection_sanity
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Collection sanity status
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/search:
    post:
      tags:
      - search
      summary: Search for similar vectors.
      description: |-
        Auto-detects search mode:
        - **Dense**: `vector` only (existing behavior)
        - **Sparse**: `sparse_vector` only
        - **Hybrid**: both `vector` and `sparse_vector` (fused via RRF/RSF)
      operationId: search
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
        required: true
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: A field of the wrong type, such as a negative or non-integer ef_search
          content:
            text/plain:
              schema:
                type: string
  /collections/{name}/search/batch:
    post:
      tags:
      - search
      summary: Batch search for multiple vectors.
      operationId: batch_search
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchSearchRequest'
        required: true
      responses:
        '200':
          description: Batch search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchSearchResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: A field of the wrong type in an entry, such as a negative ef_search
          content:
            text/plain:
              schema:
                type: string
  /collections/{name}/search/hybrid:
    post:
      tags:
      - search
      summary: Hybrid search combining vector similarity and BM25 text search.
      operationId: hybrid_search
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HybridSearchRequest'
        required: true
      responses:
        '200':
          description: Hybrid search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
  /collections/{name}/search/ids:
    post:
      tags:
      - search
      summary: Lightweight search returning only IDs and scores (no payload hydration).
      description: |-
        Accepts the same request body as the standard `/search` endpoint, for a
        dense, sparse or hybrid search. `mode` is checked on every shape but
        applied only to a dense search with neither a `filter` nor `ef_search`:
        `ef_search` wins over it, and a filtered search applies neither (#457).
      operationId: search_ids
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
        required: true
      responses:
        '200':
          description: IDs-only search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchIdsResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: A field of the wrong type, such as a negative or non-integer ef_search
          content:
            text/plain:
              schema:
                type: string
  /collections/{name}/search/multi:
    post:
      tags:
      - search
      summary: Multi-query search with fusion strategies.
      operationId: multi_query_search
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultiQuerySearchRequest'
        required: true
      responses:
        '200':
          description: Multi-query search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/search/multi/ids:
    post:
      tags:
      - search
      summary: Multi-query fusion search returning only ids and scores (no payloads).
      description: |-
        Faster than `/search/multi` when payloads are not needed: the core
        `multi_query_search_ids` kernel skips payload hydration. Metadata filters
        are not supported here — use `/search/multi` for filtered fusion.
      operationId: multi_query_search_ids
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MultiQuerySearchRequest'
        required: true
      responses:
        '200':
          description: Multi-query ids-only results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchIdsResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
  /collections/{name}/search/text:
    post:
      tags:
      - search
      summary: Search using BM25 full-text search.
      operationId: text_search
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TextSearchRequest'
        required: true
      responses:
        '200':
          description: Text search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
  /collections/{name}/stats:
    get:
      tags:
      - collections
      summary: Get cached collection statistics (returns 404 if never analyzed).
      operationId: get_collection_stats
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Collection statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionStatsResponse'
        '404':
          description: No statistics available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Failed to read stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/stream/enable:
    post:
      tags:
      - points
      summary: Enable streaming ingestion on a collection.
      description: |-
        Spawns the background drain task so subsequent calls to
        `/collections/{name}/stream/insert` accept points instead of returning a
        `409 Conflict` "streaming not configured" error. Omitted body fields fall
        back to the engine defaults. Calling this again replaces the existing
        ingester (the old drain task is aborted).

        Returns `200 OK` on success and `404 Not Found` when the collection does
        not exist.
      operationId: enable_streaming
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnableStreamingRequest'
        required: true
      responses:
        '200':
          description: Streaming enabled
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
  /collections/{name}/stream/insert:
    post:
      tags:
      - points
      summary: Stream-insert a single point via the bounded ingestion channel.
      description: |-
        Returns 202 Accepted on success, 429 Too Many Requests when the buffer is
        full (with `Retry-After: 1` header per RFC 7231), 503 Service Unavailable
        when the drain task has exited, and 404 when the collection is not found.

        This handler is `async` to satisfy Axum's handler contract; it does not
        perform any async I/O internally (the channel send is non-blocking).
      operationId: stream_insert
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StreamInsertRequest'
        required: true
      responses:
        '202':
          description: Point accepted into streaming buffer
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Streaming not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
        '429':
          description: Streaming buffer full — retry after 1 second
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Streaming drain task has exited — collection must be reconfigured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /collections/{name}/vacuum:
    post:
      tags:
      - collections
      summary: |-
        Vacuums the HNSW index of a vector collection, removing tombstoned
        entries and rebuilding the graph from current vectors.
      description: |-
        Semantically equivalent to `POST /collections/{name}/index/rebuild`
        but exposed under a more intuitive maintenance-oriented name.

        This is a blocking operation: for large collections it may take
        several seconds.
      operationId: vacuum_collection
      parameters:
      - name: name
        in: path
        description: Collection name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Index vacuumed
          content:
            application/json:
              schema:
                type: object
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Vacuum failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /guardrails:
    get:
      tags:
      - guardrails
      summary: Get current guard-rails configuration.
      operationId: get_guardrails
      responses:
        '200':
          description: Current guard-rails config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuardRailsConfigResponse'
    put:
      tags:
      - guardrails
      summary: Update guard-rails configuration (partial update).
      operationId: update_guardrails
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuardRailsConfigRequest'
        required: true
      responses:
        '200':
          description: Updated guard-rails config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuardRailsConfigResponse'
        '422':
          $ref: '#/components/responses/MalformedBody'
  /health:
    get:
      tags:
      - health
      summary: Liveness probe — always returns 200 OK.
      operationId: health_check
      responses:
        '200':
          description: Server is alive
          content:
            application/json:
              schema:
                type: object
  /metrics:
    get:
      tags:
      - metrics
      summary: Prometheus text format metrics response.
      description: Returns metrics in Prometheus exposition format, including plan cache stats.
      operationId: prometheus_metrics
      responses:
        '200':
          description: Prometheus metrics
          content:
            text/plain: {}
        '500':
          description: Internal server error
  /query:
    post:
      tags:
      - query
      summary: Execute a VelesQL query.
      description: |-
        BUG-1 FIX: Automatically detects aggregation queries (GROUP BY, COUNT, SUM, etc.)
        and routes them to execute_aggregate for proper handling.

        DDL statements (CREATE/DROP COLLECTION) are intercepted before collection
        resolution and dispatched directly through `Database::execute_query`.
      operationId: query
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
        required: true
      responses:
        '200':
          description: Query results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        '400':
          description: Query syntax error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VelesqlErrorResponse'
        '422':
          description: Query validation/execution error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VelesqlErrorResponse'
  /query/explain:
    post:
      tags:
      - query
      summary: Explain a VelesQL query, optionally executing it with instrumentation.
      description: |-
        When `analyze` is false (default), returns the estimated plan only.
        When `analyze` is true, executes the query and returns actual statistics.
      operationId: explain
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExplainRequest'
        required: true
      responses:
        '200':
          description: Query plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExplainResponse'
        '400':
          description: Query syntax error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryErrorResponse'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VelesqlErrorResponse'
        '422':
          description: Query validation/execution error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VelesqlErrorResponse'
  /ready:
    get:
      tags:
      - health
      summary: Readiness probe — returns 200 when the database is fully loaded, 503 otherwise.
      operationId: readiness_check
      responses:
        '200':
          description: Server is ready to accept requests
          content:
            application/json:
              schema:
                type: object
        '503':
          description: Server is not yet ready
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    ActualStatsResponse:
      type: object
      description: |-
        Actual execution statistics for EXPLAIN ANALYZE responses.

        `actual_rows`, `actual_time_ms`, and `loops` are measured. The graph
        traversal counters `nodes_visited` / `edges_traversed` are **strategy-
        dependent approximations** (a lower bound, not an exact figure):
        `VectorFirst` undercounts via its `limit(1)` existence-BFS frontier and
        `Parallel` double-counts a node touched by both legs. The
        `traversal_counters_approximate` flag exposes this honesty contract in a
        machine-readable form (backlog #26), mirroring the `estimated` flag of
        `NodeStatsResponse`.
      required:
      - actual_rows
      - actual_time_ms
      - loops
      - nodes_visited
      - edges_traversed
      - traversal_counters_approximate
      properties:
        actual_rows:
          type: integer
          format: int64
          description: Actual number of rows returned.
          minimum: 0
        actual_time_ms:
          type: number
          format: double
          description: Actual execution time in milliseconds.
        edges_traversed:
          type: integer
          format: int64
          description: |-
            Approximate number of edges traversed during MATCH graph traversal.
            See `traversal_counters_approximate`; 0 for non-graph queries.
          minimum: 0
        executed_filter_strategy:
          type:
          - string
          - 'null'
          description: |-
            Filter strategy the executor actually ran, recorded at the dispatch
            site (see `FilterStrategy::as_str`). Present for single SELECTs that
            went through the filtered vector-search dispatch; absent for MATCH,
            compound queries, and arms where pre/post-filter does not apply.
        loops:
          type: integer
          format: int64
          description: Number of loop iterations.
          minimum: 0
        nodes_visited:
          type: integer
          format: int64
          description: |-
            Approximate number of nodes visited during MATCH graph traversal.
            See `traversal_counters_approximate`; 0 for non-graph queries.
          minimum: 0
        traversal_counters_approximate:
          type: boolean
          description: |-
            When `true`, `nodes_visited` and `edges_traversed` are strategy-dependent
            approximations (a lower bound), not exact measured counts. Always `false`
            for non-graph queries, where both counters are 0.
    AddEdgeRequest:
      type: object
      description: Request to add an edge to the graph.
      required:
      - id
      - source
      - target
      - label
      properties:
        id:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
          description: Point ID. Accepts a JSON integer (native form) or a string; use a string for u64 values above 2^53-1 to avoid JavaScript precision loss.
        label:
          type: string
          description: Edge label (relationship type).
        properties:
          description: Edge properties.
        source:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
          description: Point ID. Accepts a JSON integer (native form) or a string; use a string for u64 values above 2^53-1 to avoid JavaScript precision loss.
        target:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
          description: Point ID. Accepts a JSON integer (native form) or a string; use a string for u64 values above 2^53-1 to avoid JavaScript precision loss.
    AddEdgesBatchRequest:
      type: object
      description: Request to add multiple edges in one batched operation.
      required:
      - edges
      properties:
        edges:
          type: array
          items:
            $ref: '#/components/schemas/AddEdgeRequest'
          description: Edges to insert.
    AddEdgesBatchResponse:
      type: object
      description: Response for a batched edge insertion.
      required:
      - added
      properties:
        added:
          type: integer
          description: |-
            Number of edges actually inserted. May be less than the number submitted:
            edges whose ID already exists (in the request or the graph) are silently
            skipped. Compare against the request length to detect skipped duplicates.
          minimum: 0
    AggregationResponse:
      type: object
      description: Response from `VelesQL` aggregation query execution.
      required:
      - result
      - timing_ms
      - meta
      properties:
        meta:
          $ref: '#/components/schemas/QueryResponseMeta'
          description: Query response metadata.
        result:
          description: Aggregation results.
        timing_ms:
          type: number
          format: double
          description: Query execution time in milliseconds.
    BatchSearchRequest:
      type: object
      description: Request for batch vector search.
      required:
      - searches
      properties:
        searches:
          type: array
          items:
            $ref: '#/components/schemas/SearchRequest'
          description: List of search requests.
    BatchSearchResponse:
      type: object
      description: Response from batch search.
      required:
      - results
      - timing_ms
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchResponse'
          description: Results for each search query.
        timing_ms:
          type: number
          format: double
          description: Total time in milliseconds.
    BulkDeleteRequest:
      type: object
      description: Request body for bulk point deletion.
      required:
      - ids
      properties:
        ids:
          type: array
          items:
            oneOf:
            - type: integer
              format: int64
              minimum: 0
            - type: string
              pattern: ^[0-9]+$
          description: Point IDs. Each accepts a JSON integer (native form) or a string; use a string for u64 values above 2^53-1 to avoid JavaScript precision loss.
    CollectionConfigResponse:
      type: object
      description: Response with detailed collection configuration.
      required:
      - name
      - dimension
      - metric
      - storage_mode
      - point_count
      - metadata_only
      properties:
        async_index_builder:
          description: |-
            Async index builder configuration (Issue `#488`) — `None` when
            the feature is disabled for this collection.
        deferred_indexing:
          description: |-
            Deferred indexing configuration (`US-366`) — `None` when the
            feature is disabled for this collection.
        dimension:
          type: integer
          description: Vector dimension (0 for metadata-only collections).
          minimum: 0
        embedding_dimension:
          type:
          - integer
          - 'null'
          description: Embedding dimension for graph node vectors.
          minimum: 0
        graph_schema:
          description: Graph schema (if this is a graph collection).
        hnsw_params:
          description: |-
            Persisted HNSW parameters (M, `ef_construction`, etc.) when
            customised at create time. `None` means the defaults inferred
            from the collection dimension are in use.
        metadata_only:
          type: boolean
          description: Whether this is a metadata-only collection.
        metric:
          type: string
          description: Distance metric.
        name:
          type: string
          description: Collection name.
        point_count:
          type: integer
          description: Number of points in the collection.
          minimum: 0
        pq_rescore_oversampling:
          type:
          - integer
          - 'null'
          format: int32
          description: |-
            PQ rescore oversampling factor. See `CollectionConfig` for
            the semantics of `None`, `Some(0)`, and `Some(n > 0)`.
          minimum: 0
        schema_version:
          type: integer
          format: int32
          description: |-
            On-disk schema version. Increments when the persisted
            `config.json` format changes in a way older `VelesDB` versions
            cannot safely read.
          minimum: 0
        storage_mode:
          type: string
          description: Storage mode (full, sq8, binary, pq).
    CollectionDiagnosticsResponse:
      type: object
      description: Response with a collection's health diagnostics.
      required:
      - has_vectors
      - search_ready
      - dimension_configured
      - point_count
      - index_health
      properties:
        dimension_configured:
          type: boolean
          description: Whether a valid dimension is configured (> 0 for vector collections).
        has_vectors:
          type: boolean
          description: Whether the collection contains at least one vector/point.
        index_health:
          type: string
          description: 'Primary search-index health: `healthy`, `empty`, or `needs_rebuild`.'
        index_health_detail:
          type:
          - string
          - 'null'
          description: Detail message when `index_health` is `needs_rebuild`.
        point_count:
          type: integer
          description: Total number of points in the collection.
          minimum: 0
        search_ready:
          type: boolean
          description: Whether the collection is ready to serve search queries.
    CollectionResponse:
      type: object
      description: Response with collection information.
      required:
      - name
      - dimension
      - metric
      - point_count
      - storage_mode
      properties:
        dimension:
          type: integer
          description: Vector dimension.
          minimum: 0
        metric:
          type: string
          description: Distance metric.
        name:
          type: string
          description: Collection name.
        point_count:
          type: integer
          description: Number of points in the collection.
          minimum: 0
        storage_mode:
          type: string
          description: Storage mode (full, sq8, binary).
    CollectionStatsResponse:
      type: object
      description: Response with collection statistics from ANALYZE.
      required:
      - total_points
      - total_size_bytes
      - row_count
      - deleted_count
      - avg_row_size_bytes
      - payload_size_bytes
      - column_stats
      - index_stats
      properties:
        avg_row_size_bytes:
          type: integer
          format: int64
          description: Average row size in bytes.
          example: 2048
          minimum: 0
        column_stats:
          type: object
          description: Per-column statistics.
        deleted_count:
          type: integer
          format: int64
          description: Number of deleted/tombstoned rows.
          example: 500
          minimum: 0
        index_stats:
          type: object
          description: Per-index statistics.
        last_analyzed_epoch_ms:
          type:
          - integer
          - 'null'
          format: int64
          description: Timestamp of last ANALYZE (epoch milliseconds), or null if never analyzed.
          minimum: 0
        payload_size_bytes:
          type: integer
          format: int64
          description: Total payload storage footprint in bytes.
          example: 5120000
          minimum: 0
        row_count:
          type: integer
          format: int64
          description: Number of active rows.
          example: 49500
          minimum: 0
        total_points:
          type: integer
          format: int64
          description: Total number of points in the collection.
          example: 50000
          minimum: 0
        total_size_bytes:
          type: integer
          format: int64
          description: Total collection size in bytes.
          example: 102400000
          minimum: 0
    ColumnStatsResponse:
      type: object
      description: Per-column statistics in a collection stats response.
      required:
      - name
      - null_count
      - distinct_count
      - avg_size_bytes
      properties:
        avg_size_bytes:
          type: integer
          format: int64
          description: Average value size in bytes.
          minimum: 0
        distinct_count:
          type: integer
          format: int64
          description: Number of distinct values (cardinality).
          minimum: 0
        histogram_buckets:
          type:
          - integer
          - 'null'
          description: Number of histogram buckets, or null if no histogram.
          minimum: 0
        histogram_stale:
          type:
          - boolean
          - 'null'
          description: Whether the histogram is stale, or null if no histogram.
        max_value:
          type:
          - string
          - 'null'
          description: Maximum value (serialized string), if available.
        min_value:
          type:
          - string
          - 'null'
          description: Minimum value (serialized string), if available.
        name:
          type: string
          description: Column name.
        null_count:
          type: integer
          format: int64
          description: Number of null values.
          minimum: 0
    CreateCollectionRequest:
      type: object
      description: Request to create a new collection.
      required:
      - name
      properties:
        async_index_builder:
          description: |-
            Async index builder configuration (Issue `#488` — Bulk Insert V2).

            When present, enables the `AsyncIndexBuilder` for deferred HNSW
            insertion during bulk import. Accepted as a free-form JSON object
            matching
            `velesdb_core::collection::streaming::AsyncIndexBuilderConfig`.
        collection_type:
          type: string
          description: 'Collection type: "vector" (default) or "`metadata_only`".'
          example: vector
        deferred_indexing:
          description: |-
            Deferred indexing configuration (`US-366`).

            When present, inserts are buffered in memory and batch-merged
            into the HNSW index when the buffer reaches `merge_threshold`.
            Accepted as a free-form JSON object matching
            `velesdb_core::collection::streaming::DeferredIndexerConfig`.
        dimension:
          type:
          - integer
          - 'null'
          description: Vector dimension (required for vector collections, ignored for `metadata_only`).
          example: 768
          minimum: 0
        graph_schema:
          description: |-
            Graph schema (only for `collection_type = "graph"`).

            Accepted as a free-form JSON object matching
            `velesdb_core::GraphSchema`. `GraphSchema::schemaless()` is
            used when the field is absent.
        hnsw_alpha:
          type:
          - number
          - 'null'
          format: float
          description: |-
            VAMANA alpha for neighbor diversification (default derived from dimension).

            Values > 1.0 bias `select_neighbors` toward diversity over proximity,
            producing a more navigable graph with better recall. The engine
            default is 1.2 (VAMANA paper recommendation). Set to 1.0 for strict
            nearest-neighbor selection.
          example: 1.2
        hnsw_ef_construction:
          type:
          - integer
          - 'null'
          description: HNSW `ef_construction` parameter (candidate list size during build).
          example: 400
          minimum: 0
        hnsw_m:
          type:
          - integer
          - 'null'
          description: HNSW M parameter (number of bi-directional links per node).
          example: 32
          minimum: 0
        hnsw_max_elements:
          type:
          - integer
          - 'null'
          description: |-
            Initial HNSW capacity (grows automatically if exceeded).

            Pre-sizing matters for bulk imports: the engine avoids repeated
            realloc-and-copy cycles when the final population is known upfront.
            Use this when migrating a large existing corpus into a fresh
            collection.
          example: 1000000
          minimum: 0
        metric:
          type: string
          description: Distance metric (cosine, euclidean, dot, hamming, jaccard).
          example: cosine
        name:
          type: string
          description: Collection name.
          example: documents
        pq_rescore_oversampling:
          type:
          - integer
          - 'null'
          format: int32
          description: |-
            PQ rescore oversampling factor (default 4).

            The search pipeline fetches `max(k * factor, k + 32)` candidates
            from HNSW and rescores them with full-precision ADC. Only
            meaningful for quantised storage modes (SQ8, PQ). `Some(0)` is
            treated as "disabled".
          example: 4
          minimum: 0
        storage_mode:
          type: string
          description: Storage mode (full, sq8, binary). Defaults to full.
          example: full
    CreateIndexRequest:
      type: object
      description: Request to create a property index.
      required:
      - label
      - property
      properties:
        index_type:
          type: string
          description: 'Index type: "hash" (equality O(1)) or "range" (range queries O(log n)).'
          example: hash
        label:
          type: string
          description: Node label to index.
          example: Person
        property:
          type: string
          description: Property name to index.
          example: email
    DegreeResponse:
      type: object
      description: Response for node degree query.
      required:
      - in_degree
      - out_degree
      properties:
        in_degree:
          type: integer
          description: Number of incoming edges.
          minimum: 0
        out_degree:
          type: integer
          description: Number of outgoing edges.
          minimum: 0
    EdgeCountResponse:
      type: object
      description: Response for edge count query.
      required:
      - count
      properties:
        count:
          type: integer
          description: Total number of edges in the graph.
          minimum: 0
    EdgeResponse:
      type: object
      description: A single edge in the response.
      required:
      - id
      - source
      - target
      - label
      - properties
      properties:
        id:
          type: string
          description: Edge ID.
        label:
          type: string
          description: Edge label (relationship type).
        properties:
          description: Edge properties.
        source:
          type: string
          description: Source node ID.
        target:
          type: string
          description: Target node ID.
    EdgesResponse:
      type: object
      description: Response containing edges.
      required:
      - edges
      - count
      properties:
        count:
          type: integer
          description: Total count of edges returned.
          minimum: 0
        edges:
          type: array
          items:
            $ref: '#/components/schemas/EdgeResponse'
          description: List of edges.
    EnableStreamingRequest:
      type: object
      description: |-
        Request body for the enable-streaming endpoint.

        All fields are optional; omitted fields fall back to the engine defaults
        (`buffer_size = 10000`, `batch_size = 128`, `flush_interval_ms = 50`).
      properties:
        batch_size:
          type:
          - integer
          - 'null'
          description: Number of points that trigger an immediate micro-batch flush.
          minimum: 0
        buffer_size:
          type:
          - integer
          - 'null'
          description: Capacity of the bounded ingestion channel (backpressure threshold).
          minimum: 0
        flush_interval_ms:
          type:
          - integer
          - 'null'
          format: int64
          description: Maximum time (ms) before a partial batch is flushed.
          minimum: 0
    ErrorResponse:
      type: object
      description: Error response.
      required:
      - error
      properties:
        code:
          type:
          - string
          - 'null'
          description: Structured error code (e.g., `"VELES-004"` for dimension mismatch).
        error:
          type: string
          description: Error message.
    ExplainCost:
      type: object
      description: Estimated cost metrics for the query.
      required:
      - uses_index
      - selectivity
      - complexity
      properties:
        complexity:
          type: string
          description: Estimated complexity class.
        index_name:
          type:
          - string
          - 'null'
          description: Index name if used.
        selectivity:
          type: number
          format: double
          description: Estimated selectivity (0.0 - 1.0).
        uses_index:
          type: boolean
          description: Whether an index can be used.
    ExplainFeatures:
      type: object
      description: Features detected in the query.
      required:
      - has_vector_search
      - has_filter
      - has_order_by
      - has_group_by
      - has_aggregation
      - has_join
      - has_fusion
      properties:
        has_aggregation:
          type: boolean
          description: Has aggregation functions.
        has_filter:
          type: boolean
          description: Has metadata filter.
        has_fusion:
          type: boolean
          description: Has FUSION clause.
        has_group_by:
          type: boolean
          description: Has GROUP BY clause.
        has_join:
          type: boolean
          description: Has JOIN clause.
        has_order_by:
          type: boolean
          description: Has ORDER BY clause.
        has_vector_search:
          type: boolean
          description: Has vector search (NEAR clause).
        limit:
          type:
          - integer
          - 'null'
          format: int64
          description: LIMIT value if present.
          minimum: 0
        offset:
          type:
          - integer
          - 'null'
          format: int64
          description: OFFSET value if present.
          minimum: 0
    ExplainRequest:
      type: object
      description: Request for query EXPLAIN.
      required:
      - query
      properties:
        analyze:
          type: boolean
          description: When true, execute the query and return actual statistics alongside the plan.
        params:
          type: object
          description: Named parameters for the query.
          additionalProperties: {}
          propertyNames:
            type: string
        query:
          type: string
          description: The `VelesQL` query string to explain.
          example: SELECT * FROM docs WHERE category = 'tech' AND vector NEAR $v LIMIT 10
    ExplainResponse:
      type: object
      description: Response from query EXPLAIN.
      required:
      - query
      - query_type
      - collection
      - plan
      - estimated_cost
      - features
      properties:
        actual_stats:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ActualStatsResponse'
            description: 'Actual execution statistics (only when `analyze: true`).'
        actual_time_ms:
          type:
          - number
          - 'null'
          format: double
          description: 'Actual execution time in milliseconds (only when `analyze: true`).'
        cache_hit:
          type:
          - boolean
          - 'null'
          description: Whether this plan was served from the compiled plan cache.
        collection:
          type: string
          description: Target collection name.
        estimated_cost:
          $ref: '#/components/schemas/ExplainCost'
          description: Estimated cost metrics.
        estimated_cost_ms:
          type:
          - number
          - 'null'
          format: double
          description: Estimated cost in milliseconds (for side-by-side comparison with actual).
        features:
          $ref: '#/components/schemas/ExplainFeatures'
          description: Query features detected.
        node_stats:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/NodeStatsResponse'
          description: 'Per-node execution statistics (only when `analyze: true`).'
        plan:
          type: array
          items:
            $ref: '#/components/schemas/ExplainStep'
          description: Query plan steps.
        plan_reuse_count:
          type:
          - integer
          - 'null'
          format: int64
          description: How many times this cached plan has been reused.
          minimum: 0
        query:
          type: string
          description: The original query.
        query_type:
          type: string
          description: Query type (SELECT, MATCH, etc.).
    ExplainStep:
      type: object
      description: A step in the query execution plan.
      required:
      - step
      - operation
      - description
      properties:
        description:
          type: string
          description: Description of what this step does.
        estimated_rows:
          type:
          - integer
          - 'null'
          description: Estimated rows processed/produced.
          minimum: 0
        estimation_method:
          type:
          - string
          - 'null'
          description: How the row estimate was produced (e.g. "histogram", "cardinality", "heuristic").
        operation:
          type: string
          description: Operation type.
        step:
          type: integer
          description: Step number (1-indexed).
          minimum: 0
    FusionRequest:
      type: object
      description: Fusion configuration for hybrid dense+sparse search.
      required:
      - strategy
      properties:
        avg_w:
          type:
          - number
          - 'null'
          format: float
          description: |-
            Weighted fusion: weight applied to the average score component
            (only for strategy = "weighted", default 0.5).
        dense_w:
          type:
          - number
          - 'null'
          format: float
          description: Dense weight (only for strategy = "rsf", default 0.5).
        hit_w:
          type:
          - number
          - 'null'
          format: float
          description: |-
            Weighted fusion: weight applied to the hit-ratio component
            (only for strategy = "weighted", default 0.2).
        k:
          type:
          - integer
          - 'null'
          format: int32
          description: RRF k parameter (only for strategy = "rrf", default 60).
          minimum: 0
        max_w:
          type:
          - number
          - 'null'
          format: float
          description: |-
            Weighted fusion: weight applied to the maximum score component
            (only for strategy = "weighted", default 0.3).
        sparse_w:
          type:
          - number
          - 'null'
          format: float
          description: Sparse weight (only for strategy = "rsf", default 0.5).
        strategy:
          type: string
          description: |-
            Fusion strategy: "rrf", "rsf" (alias "`relative_score`"),
            "average" (alias "avg"), "maximum" (alias "max"), or "weighted".
          example: rrf
    GraphSearchRequest:
      type: object
      description: Request for graph embedding search.
      required:
      - vector
      properties:
        top_k:
          type: integer
          description: Number of results to return.
          minimum: 0
        vector:
          type: array
          items:
            type: number
            format: float
          description: Query vector for similarity search.
    GraphSearchResponse:
      type: object
      description: Response for graph embedding search.
      required:
      - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/GraphSearchResultItem'
          description: Search results with node ID and similarity score.
    GraphSearchResultItem:
      type: object
      description: A single graph search result.
      required:
      - id
      - score
      properties:
        id:
          type: string
          description: Node ID.
        payload:
          description: Node payload (if any).
        score:
          type: number
          format: float
          description: Similarity score.
    GuardRailsConfigRequest:
      type: object
      description: Request to configure query guard-rails.
      properties:
        circuit_failure_threshold:
          type:
          - integer
          - 'null'
          format: int32
          description: 'Circuit breaker: failure threshold before tripping.'
          example: 5
          minimum: 0
        circuit_recovery_seconds:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Circuit breaker: recovery time in seconds.'
          example: 30
          minimum: 0
        max_cardinality:
          type:
          - integer
          - 'null'
          description: Maximum intermediate cardinality.
          example: 100000
          minimum: 0
        max_depth:
          type:
          - integer
          - 'null'
          format: int32
          description: Maximum graph traversal depth.
          example: 10
          minimum: 0
        memory_limit_bytes:
          type:
          - integer
          - 'null'
          description: Memory limit per query in bytes.
          example: 104857600
          minimum: 0
        rate_limit_qps:
          type:
          - integer
          - 'null'
          format: int32
          description: 'Rate limit: max queries per second per client.'
          example: 100
          minimum: 0
        timeout_ms:
          type:
          - integer
          - 'null'
          format: int64
          description: Query timeout in milliseconds (0 = no timeout).
          example: 30000
          minimum: 0
    GuardRailsConfigResponse:
      type: object
      description: Response with current guard-rails configuration.
      required:
      - max_depth
      - max_cardinality
      - memory_limit_bytes
      - timeout_ms
      - rate_limit_qps
      - circuit_failure_threshold
      - circuit_recovery_seconds
      properties:
        circuit_failure_threshold:
          type: integer
          format: int32
          description: 'Circuit breaker: failure threshold.'
          minimum: 0
        circuit_recovery_seconds:
          type: integer
          format: int64
          description: 'Circuit breaker: recovery time in seconds.'
          minimum: 0
        max_cardinality:
          type: integer
          description: Maximum intermediate cardinality.
          minimum: 0
        max_depth:
          type: integer
          format: int32
          description: Maximum graph traversal depth.
          minimum: 0
        memory_limit_bytes:
          type: integer
          description: Memory limit per query in bytes.
          minimum: 0
        rate_limit_qps:
          type: integer
          format: int32
          description: 'Rate limit: max queries per second per client.'
          minimum: 0
        timeout_ms:
          type: integer
          format: int64
          description: Query timeout in milliseconds.
          minimum: 0
    HybridSearchRequest:
      type: object
      description: Request for hybrid search (vector + text).
      required:
      - vector
      - query
      properties:
        filter:
          type: object
          description: Optional metadata filter.
          example:
            condition:
              field: category
              type: eq
              value: tech
        query:
          type: string
          description: Text query for BM25 search.
          example: rust programming
        top_k:
          type: integer
          description: Number of results to return.
          example: 10
          minimum: 0
        vector:
          type: array
          items:
            type: number
            format: float
          description: Query vector for similarity search.
        vector_weight:
          type: number
          format: float
          description: Weight for vector similarity (0.0-1.0). Text weight = 1 - `vector_weight`.
          example: 0.5
    IdScoreResult:
      type: object
      description: A single ID+score result from IDs-only search.
      required:
      - id
      - score
      properties:
        id:
          type: string
          description: Point ID.
        score:
          type: number
          format: float
          description: Similarity score.
    IndexResponse:
      type: object
      description: Response with index information.
      required:
      - label
      - property
      - index_type
      - cardinality
      - memory_bytes
      properties:
        cardinality:
          type: integer
          description: Number of unique values indexed.
          minimum: 0
        index_type:
          type: string
          description: Index type (hash or range).
        label:
          type: string
          description: Node label.
        memory_bytes:
          type: integer
          description: Memory usage in bytes.
          minimum: 0
        property:
          type: string
          description: Property name.
    IndexStatsResponse:
      type: object
      description: Per-index statistics in a collection stats response.
      required:
      - name
      - index_type
      - entry_count
      - depth
      - size_bytes
      properties:
        depth:
          type: integer
          format: int32
          description: Index depth (for tree-based indexes).
          minimum: 0
        entry_count:
          type: integer
          format: int64
          description: Number of entries in the index.
          minimum: 0
        index_type:
          type: string
          description: Index type (e.g., "HNSW", "`PropertyIndex`").
        name:
          type: string
          description: Index name.
        size_bytes:
          type: integer
          format: int64
          description: Index size in bytes.
          minimum: 0
    ListIndexesResponse:
      type: object
      description: Response listing all indexes.
      required:
      - indexes
      - total
      properties:
        indexes:
          type: array
          items:
            $ref: '#/components/schemas/IndexResponse'
          description: List of indexes.
        total:
          type: integer
          description: Total number of indexes.
          minimum: 0
    MatchQueryMeta:
      type: object
      description: Metadata section for MATCH query responses.
      required:
      - velesql_contract_version
      properties:
        velesql_contract_version:
          type: string
          description: VelesQL contract version used by this response.
    MatchQueryRequest:
      type: object
      description: Request body for MATCH query execution.
      required:
      - query
      properties:
        params:
          type: object
          description: Query parameters (e.g., vectors, values).
          additionalProperties: {}
          propertyNames:
            type: string
        query:
          type: string
          description: VelesQL MATCH query string.
        threshold:
          type:
          - number
          - 'null'
          format: float
          description: Similarity threshold (0.0 to 1.0, default 0.0).
        vector:
          type:
          - array
          - 'null'
          items:
            type: number
            format: float
          description: Query vector for similarity scoring (EPIC-058 US-007).
    MatchQueryResponse:
      type: object
      description: Response for MATCH query execution.
      required:
      - results
      - took_ms
      - count
      - meta
      properties:
        count:
          type: integer
          description: Number of results.
          minimum: 0
        meta:
          $ref: '#/components/schemas/MatchQueryMeta'
          description: Response metadata.
        results:
          type: array
          items:
            $ref: '#/components/schemas/MatchQueryResultItem'
          description: Query results.
        took_ms:
          type: integer
          format: int64
          description: Execution time in milliseconds.
          minimum: 0
    MatchQueryResultItem:
      type: object
      description: Single result from MATCH query.
      required:
      - bindings
      - depth
      properties:
        bindings:
          type: object
          additionalProperties:
            oneOf:
            - type: integer
              format: int64
              minimum: 0
            - type: string
              pattern: ^[0-9]+$
        depth:
          type: integer
          format: int32
          description: Traversal depth.
          minimum: 0
        projected:
          type: object
          description: Projected properties from RETURN clause (EPIC-058 US-007).
          additionalProperties: {}
          propertyNames:
            type: string
        score:
          type:
          - number
          - 'null'
          format: float
          description: Similarity score (if similarity() was used).
    MultiQuerySearchRequest:
      type: object
      description: Request for multi-query vector search with fusion.
      required:
      - vectors
      properties:
        avg_weight:
          type: number
          format: float
          description: 'Weighted fusion: weight for average score component.'
          example: 0.5
        dense_weight:
          type: number
          format: float
          description: 'Relative score fusion: weight for the dense (vector) branch.'
          example: 0.5
        filter:
          type: object
          description: Optional metadata filter.
          example:
            condition:
              field: category
              type: eq
              value: tech
        hit_weight:
          type: number
          format: float
          description: 'Weighted fusion: weight for hit count component.'
          example: 0.2
        max_weight:
          type: number
          format: float
          description: 'Weighted fusion: weight for max score component.'
          example: 0.3
        rrf_k:
          type: integer
          format: int32
          description: RRF k parameter (only used when strategy = "rrf").
          example: 60
          minimum: 0
        sparse_weight:
          type: number
          format: float
          description: 'Relative score fusion: weight for the sparse branch.'
          example: 0.5
        strategy:
          type: string
          description: 'Fusion strategy: "average", "maximum", "rrf", "weighted", "`relative_score`".'
          example: rrf
        top_k:
          type: integer
          description: Number of results to return.
          example: 10
          minimum: 0
        vectors:
          type: array
          items:
            type: array
            items:
              type: number
              format: float
          description: List of query vectors.
    NodeListResponse:
      type: object
      description: Response containing all node IDs in the graph.
      required:
      - node_ids
      - count
      properties:
        count:
          type: integer
          description: Total count of nodes.
          minimum: 0
        node_ids:
          type: array
          items:
            oneOf:
            - type: integer
              format: int64
              minimum: 0
            - type: string
              pattern: ^[0-9]+$
          description: Point IDs. Each accepts a JSON integer (native form) or a string; use a string for u64 values above 2^53-1 to avoid JavaScript precision loss.
    NodePayloadResponse:
      type: object
      description: Response for a node payload retrieval.
      required:
      - node_id
      properties:
        node_id:
          type: string
          description: Node ID.
        payload:
          description: Stored payload (null if none).
    NodeStatsResponse:
      type: object
      description: |-
        Per-plan-node **estimated** execution statistics for EXPLAIN ANALYZE responses.

        All values are synthetic heuristics derived from the plan-global
        `actual_time_ms` — they are **not** individually measured per node.
        Field names keep the `actual_` prefix for API stability; check the
        `estimated` flag to distinguish heuristic values from future
        instrumented measurements (#467).
      required:
      - node_label
      - actual_time_ms
      - actual_rows_in
      - actual_rows_out
      - loops
      - estimated
      properties:
        actual_rows_in:
          type: integer
          format: int64
          description: Estimated rows entering this node (heuristic approximation).
          minimum: 0
        actual_rows_out:
          type: integer
          format: int64
          description: Estimated rows leaving this node (heuristic approximation).
          minimum: 0
        actual_time_ms:
          type: number
          format: double
          description: |-
            Estimated wall-clock time for this node in milliseconds.
            Derived from total execution time using normalized weight fractions,
            not real per-node instrumentation. Will be replaced by measured
            timing (#467).
        estimated:
          type: boolean
          description: |-
            When `true`, time and row counts are heuristic estimates, not real
            per-node measurements. Will become `false` once instrumented timing
            lands (#467).
        loops:
          type: integer
          format: int64
          description: Number of loop iterations (1 for non-looping nodes).
          minimum: 0
        node_label:
          type: string
          description: Node label (e.g. `VectorSearch`, `Filter`, `Limit`).
    ParallelTraverseRequest:
      type: object
      description: Request for parallel multi-source BFS traversal.
      required:
      - sources
      properties:
        limit:
          type: integer
          description: Maximum number of results per source.
          minimum: 0
        max_depth:
          type: integer
          format: int32
          description: Maximum traversal depth.
          minimum: 0
        rel_types:
          type: array
          items:
            type: string
          description: Filter by relationship types (empty = all types).
        sources:
          type: array
          items:
            oneOf:
            - type: integer
              format: int64
              minimum: 0
            - type: string
              pattern: ^[0-9]+$
          description: Point IDs. Each accepts a JSON integer (native form) or a string; use a string for u64 values above 2^53-1 to avoid JavaScript precision loss.
    PointRequest:
      type: object
      description: A point in an upsert request.
      required:
      - id
      - vector
      properties:
        id:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
          description: Point ID. Accepts a JSON integer (native form) or a string; use a string for u64 values above 2^53-1 to avoid JavaScript precision loss.
        payload:
          description: Optional payload.
        sparse_vector:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/SparseVectorInput'
            description: Single sparse vector (convenience, stored under default name `""`).
        sparse_vectors:
          type:
          - object
          - 'null'
          description: Named sparse vectors map.
          additionalProperties:
            $ref: '#/components/schemas/SparseVectorInput'
          propertyNames:
            type: string
        vector:
          type: array
          items:
            type: number
            format: float
          description: Vector data.
    QueryErrorDetail:
      type: object
      description: '`VelesQL` query error detail.'
      required:
      - type
      - message
      - position
      - query
      properties:
        message:
          type: string
          description: Error message.
        position:
          type: integer
          description: Position in query where error occurred.
          minimum: 0
        query:
          type: string
          description: Fragment of query around error.
        type:
          type: string
          description: Error type.
    QueryErrorResponse:
      type: object
      description: '`VelesQL` query error response.'
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/QueryErrorDetail'
          description: Error details.
    QueryRequest:
      type: object
      description: Request for `VelesQL` query execution.
      required:
      - query
      properties:
        collection:
          type:
          - string
          - 'null'
          description: Optional collection name (required for top-level MATCH queries via `/query`).
        params:
          type: object
          description: Named parameters for the query.
          additionalProperties: {}
          propertyNames:
            type: string
        query:
          type: string
          description: The `VelesQL` query string.
    QueryResponse:
      type: object
      description: |-
        Response from `VelesQL` query execution.

        Results are projected rows: the shape depends on the SELECT clause.
        - `SELECT *` → `{id, field1, field2, ...}` (no vector)
        - `SELECT col1, col2` → `{col1, col2}`
        - `SELECT similarity() AS score, title` → `{score, title}`

        ## MATCH-query extra fields

        When the query contains a `MATCH` clause, each row may carry additional
        graph-specific fields:
        - `_edge_bindings` — map of alias → edge (id, source, target, label, properties)
          for every named relationship in the pattern.
        - `_edge_paths` — array of edge-ID arrays, one per matched path variable.
          Only present when the `MATCH` clause binds a path variable (`p = (…)-[…]->(…)`).
      required:
      - results
      - timing_ms
      - took_ms
      - rows_returned
      - meta
      properties:
        meta:
          $ref: '#/components/schemas/QueryResponseMeta'
          description: Query response metadata.
        results:
          type: array
          items: {}
          description: |-
            Projected result rows. Shape depends on SELECT clause.

            MATCH queries may include `_edge_bindings` and `_edge_paths` fields
            in each row — see the struct documentation for details.
        rows_returned:
          type: integer
          description: Number of rows returned.
          minimum: 0
        timing_ms:
          type: number
          format: double
          description: Query execution time in milliseconds.
        took_ms:
          type: integer
          format: int64
          description: Query execution time in whole milliseconds (compat helper).
          minimum: 0
    QueryResponseMeta:
      type: object
      description: Metadata section for `VelesQL` query responses.
      required:
      - velesql_contract_version
      - count
      properties:
        count:
          type: integer
          description: Number of rows in `results`.
          minimum: 0
        velesql_contract_version:
          type: string
          description: '`VelesQL` contract version used by this response.'
    RelateRequest:
      type: object
      description: Request body for `POST /collections/{name}/relations`.
      required:
      - source
      - target
      - rel_type
      properties:
        properties:
          description: Optional edge properties.
        rel_type:
          type: string
          description: Relationship type label (e.g. `"KNOWS"`, `"RELATED_TO"`).
        source:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
          description: Point ID. Accepts a JSON integer (native form) or a string; use a string for u64 values above 2^53-1 to avoid JavaScript precision loss.
        target:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
          description: Point ID. Accepts a JSON integer (native form) or a string; use a string for u64 values above 2^53-1 to avoid JavaScript precision loss.
    RelateResponse:
      type: object
      description: Response body for `POST /collections/{name}/relations`.
      required:
      - edge_id
      properties:
        edge_id:
          type: string
          description: Allocated edge ID.
    RelationEdge:
      type: object
      description: A single relation edge in a response.
      required:
      - id
      - source
      - target
      - rel_type
      - properties
      properties:
        id:
          type: string
          description: Edge ID.
        properties:
          description: Edge properties (null when empty).
        rel_type:
          type: string
          description: Relationship type label.
        source:
          type: string
          description: Source point ID.
        target:
          type: string
          description: Target point ID.
    RelationsResponse:
      type: object
      description: Response body for `GET /collections/{name}/points/{id}/relations`.
      required:
      - edges
      - count
      properties:
        count:
          type: integer
          description: Total count.
          minimum: 0
        edges:
          type: array
          items:
            $ref: '#/components/schemas/RelationEdge'
          description: Outgoing relation edges.
    ScrollPoint:
      type: object
      description: A single point in a scroll response.
      required:
      - id
      - vector
      properties:
        id:
          type: string
          description: Point ID.
        payload:
          description: Optional payload.
        vector:
          type: array
          items:
            type: number
            format: float
          description: Vector data.
    ScrollRequest:
      type: object
      description: Request body for the scroll endpoint.
      properties:
        batch_size:
          type: integer
          format: int32
          description: Maximum points per batch (1–10 000, default 100).
          minimum: 0
        cursor:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
          - type: 'null'
          description: Resume after this point ID (exclusive). Omit or send null to start from the beginning. Accepts a JSON integer or a precision-safe string.
        filter:
          description: Optional filter expression.
    ScrollResponse:
      type: object
      description: Response from the scroll endpoint.
      required:
      - points
      properties:
        next_cursor:
          type:
          - string
          - 'null'
          description: Cursor for the next batch. Null when iteration is complete.
        points:
          type: array
          items:
            $ref: '#/components/schemas/ScrollPoint'
          description: Points in this batch (ascending ID order).
    SearchIdsResponse:
      type: object
      description: Response from IDs-only search (no payload hydration).
      required:
      - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/IdScoreResult'
          description: Search results with IDs and scores only.
    SearchRequest:
      type: object
      description: Request for vector search (dense, sparse, or hybrid).
      properties:
        ef_search:
          type:
          - integer
          - 'null'
          description: |-
            HNSW `ef_search` parameter, in `[16, 4096]`: an integer outside the
            range is refused with a `400` naming it (#2274), and a value that is
            not a non-negative integer fails the body's JSON parsing with a `422`,
            as any mistyped field does. It wins over `mode` for a dense search with
            no `filter`; a filtered search applies neither, and a batch entry's is
            checked but not applied.
          example: 128
          maximum: 4096
          minimum: 16
        filter:
          type: object
          description: Optional metadata filter.
          example:
            condition:
              field: category
              type: eq
              value: tech
        fusion:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/FusionRequest'
            description: Fusion configuration for hybrid search.
        mode:
          type:
          - string
          - 'null'
          description: |-
            Search quality preset, in any letter case: `fast`, `balanced`,
            `accurate`, `perfect`, `autotune` (aliases `auto_tune` and `auto`),
            `custom:<ef>` or `adaptive:<min_ef>:<max_ef>` (`min_ef` at most
            `max_ef`). Any other value is refused with a `400` naming these forms
            (#2267). It applies only to a dense search with neither a `filter` nor
            `ef_search`, and a batch entry's is checked but not applied.
          example: balanced
        sparse_index:
          type:
          - string
          - 'null'
          description: Which named sparse index to search.
        sparse_vector:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/SparseVectorInput'
            description: Single sparse query vector.
        sparse_vectors:
          type:
          - object
          - 'null'
          description: Named sparse query vectors map.
          additionalProperties:
            $ref: '#/components/schemas/SparseVectorInput'
          propertyNames:
            type: string
        timeout_ms:
          type:
          - integer
          - 'null'
          format: int64
          description: Query timeout in milliseconds.
          example: 30000
          minimum: 0
        top_k:
          type: integer
          description: Number of results to return.
          minimum: 0
        vector:
          type: array
          items:
            type: number
            format: float
          description: Query vector for dense search.
    SearchResponse:
      type: object
      description: Response from vector search.
      required:
      - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchResultResponse'
          description: Search results.
    SearchResultResponse:
      type: object
      description: A single search result.
      required:
      - id
      - score
      properties:
        id:
          type: string
          description: Point ID.
        payload:
          description: Point payload.
        score:
          type: number
          format: float
          description: Similarity score.
    SetTtlRequest:
      type: object
      description: Request body for `PATCH /collections/{name}/points/{id}/ttl`.
      required:
      - ttl_seconds
      properties:
        ttl_seconds:
          type: integer
          format: int64
          description: |-
            Number of seconds from now until this point expires.
            A value of `0` expires the point immediately.
          minimum: 0
    SparseVectorInput:
      oneOf:
      - type: object
        description: Canonical parallel-array format with explicit indices and values.
        required:
        - indices
        - values
        properties:
          indices:
            type: array
            items:
              type: integer
              format: int32
              minimum: 0
            description: Term/dimension indices (u32).
          values:
            type: array
            items:
              type: number
              format: float
            description: Corresponding weights.
      - type: object
        description: Dictionary format mapping string term IDs to weights.
        additionalProperties:
          type: number
          format: float
        propertyNames:
          type: string
      description: |-
        Input format for sparse vectors, supporting two JSON representations:

        - **Parallel arrays**: `{"indices": [42, 1337], "values": [0.5, 1.2]}`
        - **Dict format** (Qdrant-compatible): `{"42": 0.5, "1337": 1.2}`
    StreamDoneEvent:
      type: object
      description: 'SSE event: Traversal completed.'
      required:
      - total_nodes
      - max_depth_reached
      - elapsed_ms
      properties:
        elapsed_ms:
          type: integer
          format: int64
          description: Total elapsed time in milliseconds.
          minimum: 0
        max_depth_reached:
          type: integer
          format: int32
          description: Maximum depth reached.
          minimum: 0
        total_nodes:
          type: integer
          description: Total nodes returned.
          minimum: 0
    StreamInsertRequest:
      type: object
      description: Request body for the streaming insert endpoint (single point).
      required:
      - id
      - vector
      properties:
        id:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
          description: Point ID. Accepts a JSON integer (native form) or a string; use a string for u64 values above 2^53-1 to avoid JavaScript precision loss.
        payload:
          description: Optional JSON payload (metadata).
        vector:
          type: array
          items:
            type: number
            format: float
          description: Dense vector data.
    StreamNodeEvent:
      type: object
      description: 'SSE event: A node reached during traversal.'
      required:
      - id
      - depth
      - path
      properties:
        depth:
          type: integer
          format: int32
          description: Depth from source.
          minimum: 0
        id:
          type: string
          description: Target node ID.
        path:
          type: array
          items:
            oneOf:
            - type: integer
              format: int64
              minimum: 0
            - type: string
              pattern: ^[0-9]+$
          description: Point IDs. Each accepts a JSON integer (native form) or a string; use a string for u64 values above 2^53-1 to avoid JavaScript precision loss.
    StreamStatsEvent:
      type: object
      description: 'SSE event: Periodic statistics update.'
      required:
      - nodes_visited
      - elapsed_ms
      properties:
        elapsed_ms:
          type: integer
          format: int64
          description: Elapsed time in milliseconds.
          minimum: 0
        nodes_visited:
          type: integer
          description: Number of nodes visited so far.
          minimum: 0
    TextSearchRequest:
      type: object
      description: Request for BM25 text search.
      required:
      - query
      properties:
        filter:
          type: object
          description: Optional metadata filter.
          example:
            condition:
              field: category
              type: eq
              value: tech
        query:
          type: string
          description: Text query for full-text search.
          example: rust programming
        top_k:
          type: integer
          description: Number of results to return.
          example: 10
          minimum: 0
    TraversalResultItem:
      type: object
      description: A single traversal result item.
      required:
      - target_id
      - depth
      - path
      properties:
        depth:
          type: integer
          format: int32
          description: Depth of traversal (number of hops from source).
          minimum: 0
        path:
          type: array
          items:
            oneOf:
            - type: integer
              format: int64
              minimum: 0
            - type: string
              pattern: ^[0-9]+$
          description: Point IDs. Each accepts a JSON integer (native form) or a string; use a string for u64 values above 2^53-1 to avoid JavaScript precision loss.
        target_id:
          type: string
          description: Target node ID reached.
    TraversalStats:
      type: object
      description: Statistics from traversal operation.
      required:
      - visited
      - depth_reached
      properties:
        depth_reached:
          type: integer
          format: int32
          description: Maximum depth reached.
          minimum: 0
        visited:
          type: integer
          description: Number of nodes visited.
          minimum: 0
    TraverseRequest:
      type: object
      description: Request for graph traversal.
      required:
      - source
      properties:
        limit:
          type: integer
          description: Maximum number of results to return.
          minimum: 0
        max_depth:
          type: integer
          format: int32
          description: Maximum traversal depth.
          minimum: 0
        rel_types:
          type: array
          items:
            type: string
          description: Filter by relationship types (empty = all types).
        source:
          oneOf:
          - type: integer
            format: int64
            minimum: 0
          - type: string
            pattern: ^[0-9]+$
          description: Point ID. Accepts a JSON integer (native form) or a string; use a string for u64 values above 2^53-1 to avoid JavaScript precision loss.
        strategy:
          type: string
          description: 'Traversal strategy: "bfs" or "dfs".'
    TraverseResponse:
      type: object
      description: Response from graph traversal.
      required:
      - results
      - has_more
      - stats
      properties:
        has_more:
          type: boolean
          description: Whether more results are available.
        results:
          type: array
          items:
            $ref: '#/components/schemas/TraversalResultItem'
          description: List of traversal results.
        stats:
          $ref: '#/components/schemas/TraversalStats'
          description: Traversal statistics.
    UpsertNodePayloadRequest:
      type: object
      description: Request to upsert a node payload.
      required:
      - payload
      properties:
        payload:
          description: JSON payload to store on the node.
    UpsertPointsRequest:
      type: object
      description: Request to upsert points.
      required:
      - points
      properties:
        points:
          type: array
          items:
            $ref: '#/components/schemas/PointRequest'
          description: Points to upsert.
    VelesqlErrorDetail:
      type: object
      description: Standardized `VelesQL` semantic/runtime error detail.
      required:
      - code
      - message
      - hint
      properties:
        code:
          type: string
          description: Stable machine-readable error code.
        details:
          description: Optional additional details.
        hint:
          type: string
          description: Actionable hint for developers.
        message:
          type: string
          description: Human-readable error message.
    VelesqlErrorResponse:
      type: object
      description: Standardized `VelesQL` semantic/runtime error response.
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/VelesqlErrorDetail'
          description: Error details.
  responses:
    MalformedBody:
      description: 'A body the server cannot deserialise: a field of the wrong type, or JSON that does not match the request schema.'
      content:
        text/plain:
          schema:
            type: string
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
security:
- bearer_auth: []
tags:
- name: health
  description: Health check endpoints
- name: collections
  description: Collection management
- name: points
  description: Vector point operations
- name: search
  description: Vector similarity search
- name: query
  description: VelesQL query execution
- name: indexes
  description: Property index management (EPIC-009)
- name: graph
  description: Graph traversal and edge operations
- name: guardrails
  description: Query guard-rails configuration (EPIC-048)
- name: metrics
  description: Prometheus operational metrics