vectorpanda-com Query API

openapi: 3.2.0
info:
  title: Vector Panda Query API
  version: 1.0.0
  description: 'Vector search as a service. Upload vector data files, query by similarity,

    and manage collections through a single API endpoint.


    All endpoints are served from the public gateway (vectorpanda.com).

    Internal services (coordinator, artifact server, workers) are not

    directly accessible.'
  contact:
    name: Vector Panda
    url: https://vectorpanda.com
servers:
- url: https://api.vectorpanda.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Query
paths:
  /api/v1/query:
    post:
      summary: Vector similarity search
      description: 'Search a collection by vector similarity. Returns the top-k most

        similar vectors, optionally with metadata.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryResponse'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: No workers available for collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Query
      operationId: postApiV1Query
      x-operation-id-source: derived
  /api/v1/query/batch:
    post:
      summary: Batch vector search
      description: 'Execute multiple similarity searches in a single request.

        Each query is independent and executed in parallel.

        Maximum 100 queries per batch.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - queries
              properties:
                queries:
                  type: array
                  maxItems: 100
                  items:
                    $ref: '#/components/schemas/QueryRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: integer
                        results:
                          type: array
                          items:
                            $ref: '#/components/schemas/QueryResult'
                        error:
                          type: string
      tags:
      - Query
      operationId: postApiV1QueryBatch
      x-operation-id-source: derived
components:
  schemas:
    WorkerStats:
      type: object
      properties:
        worker_id:
          type: string
        search_time_ms:
          type: integer
        vectors_scanned:
          type: integer
    QueryResult:
      type: object
      properties:
        key:
          type: string
          description: Vector key (u128 decimal string)
        score:
          type: number
          format: float
          description: Similarity score
        metadata:
          type: object
          additionalProperties: true
          description: Metadata fields (only present when include_metadata=true)
    Error:
      type: object
      properties:
        error:
          type: string
    QueryRequest:
      type: object
      required:
      - collection
      - vector
      properties:
        collection:
          type: string
          description: Collection name
          example: my_embeddings
        vector:
          type: array
          items:
            type: number
            format: float
          description: Query vector (must match collection dimension)
        top_k:
          type: integer
          default: 1000
          description: Maximum number of results to return
        similarity_threshold:
          type: number
          format: float
          default: 0.7
          description: Minimum similarity score to include in results
        distance_metric:
          type: string
          enum:
          - cosine
          - euclidean
          - dot_product
          default: cosine
        include_metadata:
          type: boolean
          default: false
          description: Include metadata fields in results
        use_index:
          type: string
          enum:
          - pca
          - none
          description: Index strategy override (default chosen automatically)
        filter:
          type: object
          additionalProperties: true
          description: 'MongoDB-style metadata filter. Only results whose metadata

            passes all conditions are returned. Operators: $eq, $ne,

            $gt, $gte, $lt, $lte, $in, $nin. Logical: $and, $or.

            Shorthand: {"field": "value"} means {"field": {"$eq": "value"}}.

            Multiple top-level keys are implicitly $and.

            '
          example:
            category:
              $eq: electronics
            price:
              $lte: 500
    QueryResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/QueryResult'
        worker_stats:
          type: array
          items:
            $ref: '#/components/schemas/WorkerStats'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key issued from the dashboard. Pass as `Authorization: Bearer <api_key>`.

        '