openapi: 3.1.0
info:
  title: Loam native REST API
  version: pre-alpha
  description: '**Status: Available** for everything except the operations and import endpoints, which
    are marked **In progress**: they are built and landing, and not in a released build.


    The native API addresses namespaces, streams, links and collections by name. Bodies are JSON; record
    keys, values and header values are base64. Request bodies are limited to 16 MiB.


    **Consistency tokens.** Every write returns a token, as the `Operon-Consistency-Token` header and
    in the body. Send it back on a read, as the header or in the `consistency` field, and the read sees
    that write. The string form is `v1:` followed by comma-joined `s<stream>/p<partition>@<offset>` items,
    for example `v1:s3/p0@42,s3/p1@7`.


    **Errors** are JSON: `{"error": <code>, "message": <text>, ...}`. `resource_exhausted` (429) and `unavailable`
    (503) carry a `Retry-After` header.


    **Auth.** The engine has no authentication yet and binds to loopback by default. Put it behind your
    own proxy if you expose it. The engine binary is still named `operon`, so headers use the `Operon-`
    prefix until the rename.

    '
servers:
- url: http://127.0.0.1:8080
  description: Local engine (`operon dev`)
tags:
- name: Health
  description: Liveness and readiness.
- name: Namespaces
  description: The unit of isolation.
- name: Streams
  description: Partitioned, offset-addressed logs. Every write lands in a stream first.
- name: Links
  description: Declared materializations from a stream into a collection.
- name: Collections
  description: Document sets with vectors, full text and filters, stored as Lance plus Tantivy.
- name: Documents
  description: Write, read, page, count and filter-update documents.
- name: Search
  description: Hybrid search and read-only SQL.
- name: Operations
  description: Long-running work run as durable workflows. In progress.
x-tagGroups:
- name: Engine
  tags:
  - Health
  - Namespaces
  - Streams
  - Links
  - Collections
  - Documents
  - Search
- name: Durable operations
  tags:
  - Operations
paths:
  /health:
    get:
      tags:
      - Health
      summary: Liveness
      operationId: health
      x-badges:
      - name: Available
        color: '#5f8f3a'
      responses:
        '200':
          description: The process is up.
  /ready:
    get:
      tags:
      - Health
      summary: Readiness
      description: 200 once the metastore is reachable, 503 before.
      operationId: ready
      x-badges:
      - name: Available
        color: '#5f8f3a'
      responses:
        '200':
          description: Ready.
        '503':
          $ref: '#/components/responses/Error'
  /v1/namespaces:
    post:
      tags:
      - Namespaces
      summary: Create a namespace
      operationId: createNamespace
      x-badges:
      - name: Available
        color: '#5f8f3a'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
      responses:
        '201':
          $ref: '#/components/responses/Created'
        '409':
          $ref: '#/components/responses/Error'
  /v1/namespaces/{ns}/streams:
    parameters:
    - $ref: '#/components/parameters/ns'
    post:
      tags:
      - Streams
      summary: Create a stream
      operationId: createStream
      x-badges:
      - name: Available
        color: '#5f8f3a'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - partitions
              properties:
                name:
                  type: string
                partitions:
                  type: integer
                  minimum: 1
                retention:
                  type: object
                  properties:
                    max_age_ms:
                      type: integer
                    max_bytes:
                      type: integer
      responses:
        '201':
          $ref: '#/components/responses/Created'
        '409':
          $ref: '#/components/responses/Error'
  /v1/namespaces/{ns}/streams/{stream}:
    parameters:
    - $ref: '#/components/parameters/ns'
    - name: stream
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Streams
      summary: Describe a stream
      operationId: describeStream
      x-badges:
      - name: Available
        color: '#5f8f3a'
      responses:
        '200':
          description: The stream, with the offsets of each partition.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  partitions:
                    type: array
                    items:
                      type: object
                      properties:
                        partition:
                          type: integer
                        log_start_offset:
                          type: integer
                        high_watermark:
                          type: integer
                  retention:
                    type: object
                    properties:
                      max_age_ms:
                        type:
                        - integer
                        - 'null'
                      max_bytes:
                        type:
                        - integer
                        - 'null'
        '404':
          $ref: '#/components/responses/Error'
  /v1/namespaces/{ns}/streams/{stream}/partitions/{partition}/records:
    parameters:
    - $ref: '#/components/parameters/ns'
    - name: stream
      in: path
      required: true
      schema:
        type: string
    - name: partition
      in: path
      required: true
      schema:
        type: integer
    post:
      tags:
      - Streams
      summary: Produce records
      description: Appends records to one partition. The write is durable in object storage before it
        returns.
      operationId: produce
      x-badges:
      - name: Available
        color: '#5f8f3a'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - records
              properties:
                records:
                  type: array
                  items:
                    $ref: '#/components/schemas/RecordIn'
      responses:
        '200':
          description: Offsets assigned to the batch.
          headers:
            Operon-Consistency-Token:
              $ref: '#/components/headers/Token'
          content:
            application/json:
              schema:
                type: object
                properties:
                  base_offset:
                    type: integer
                  last_offset:
                    type: integer
                  token:
                    type: array
                    description: The token as structured offsets (the header carries the string form).
                    items:
                      type: object
                      properties:
                        stream:
                          type: integer
                        partition:
                          type: integer
                        offset:
                          type: integer
        '429':
          $ref: '#/components/responses/Error'
    get:
      tags:
      - Streams
      summary: Fetch records
      operationId: fetch
      x-badges:
      - name: Available
        color: '#5f8f3a'
      parameters:
      - name: offset
        in: query
        required: true
        schema:
          type: integer
      - name: max_bytes
        in: query
        schema:
          type: integer
          default: 1048576
          maximum: 16777216
      - name: max_wait_ms
        in: query
        description: Long-poll for up to this long when no records are available (max 60 s).
        schema:
          type: integer
          maximum: 60000
      responses:
        '200':
          description: Records from the offset onward.
          content:
            application/json:
              schema:
                type: object
                properties:
                  records:
                    type: array
                    items:
                      $ref: '#/components/schemas/Record'
                  next_offset:
                    type: integer
                  high_watermark:
                    type: integer
                  log_start_offset:
                    type: integer
        '416':
          $ref: '#/components/responses/Error'
  /v1/namespaces/{ns}/links:
    parameters:
    - $ref: '#/components/parameters/ns'
    post:
      tags:
      - Links
      summary: Create a link
      operationId: createLink
      x-badges:
      - name: Available
        color: '#5f8f3a'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - source
              properties:
                name:
                  type: string
                source:
                  type: string
                  description: Source stream name.
                target:
                  type: object
                  properties:
                    kind:
                      type: string
                      examples:
                      - collection
                    name:
                      type: string
                options:
                  type: object
                  additionalProperties:
                    type: string
      responses:
        '201':
          $ref: '#/components/responses/Created'
  /v1/namespaces/{ns}/links/{link}:
    parameters:
    - $ref: '#/components/parameters/ns'
    - name: link
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Links
      summary: Describe a link
      description: Includes the applied offset of each source partition.
      operationId: describeLink
      x-badges:
      - name: Available
        color: '#5f8f3a'
      responses:
        '200':
          description: The link.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  source:
                    type: string
                  target:
                    type: object
                  options:
                    type: object
                  version:
                    type: integer
                  applied:
                    type: array
                    items:
                      type: object
                      properties:
                        partition:
                          type: integer
                        offset:
                          type: integer
  /v1/namespaces/{ns}/collections:
    parameters:
    - $ref: '#/components/parameters/ns'
    post:
      tags:
      - Collections
      summary: Create a collection
      operationId: createCollection
      x-badges:
      - name: Available
        color: '#5f8f3a'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - schema
              properties:
                name:
                  type: string
                schema:
                  $ref: '#/components/schemas/CollectionSchema'
                partitions:
                  type: integer
      responses:
        '201':
          description: The new collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionInfo'
    get:
      tags:
      - Collections
      summary: List collections
      operationId: listCollections
      x-badges:
      - name: Available
        color: '#5f8f3a'
      responses:
        '200':
          description: Collections in the namespace.
          content:
            application/json:
              schema:
                type: object
                properties:
                  collections:
                    type: array
                    items:
                      $ref: '#/components/schemas/CollectionInfo'
  /v1/namespaces/{ns}/collections/{c}:
    parameters:
    - $ref: '#/components/parameters/ns'
    - $ref: '#/components/parameters/c'
    get:
      tags:
      - Collections
      summary: Describe a collection
      description: Accepts a collection name or an alias.
      operationId: describeCollection
      x-badges:
      - name: Available
        color: '#5f8f3a'
      responses:
        '200':
          description: The collection and its hot-tier state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionInfo'
        '404':
          $ref: '#/components/responses/Error'
    delete:
      tags:
      - Collections
      summary: Drop a collection
      operationId: dropCollection
      x-badges:
      - name: Available
        color: '#5f8f3a'
      responses:
        '200':
          description: Dropped.
          content:
            application/json:
              schema:
                type: object
                properties:
                  dropped:
                    type: boolean
  /v1/namespaces/{ns}/collections/{c}/fields:
    parameters:
    - $ref: '#/components/parameters/ns'
    - $ref: '#/components/parameters/c'
    post:
      tags:
      - Collections
      summary: Add fields
      operationId: addFields
      x-badges:
      - name: Available
        color: '#5f8f3a'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fields:
                  type: array
                  items:
                    type: object
                vectors:
                  type: array
                  items:
                    type: object
                annotations:
                  type: object
      responses:
        '200':
          description: The updated schema.
          content:
            application/json:
              schema:
                type: object
                properties:
                  schema:
                    $ref: '#/components/schemas/CollectionSchema'
  /v1/namespaces/{ns}/collections/{c}/versions:
    parameters:
    - $ref: '#/components/parameters/ns'
    - $ref: '#/components/parameters/c'
    get:
      tags:
      - Collections
      summary: List schema versions
      operationId: schemaVersions
      x-badges:
      - name: Available
        color: '#5f8f3a'
      responses:
        '200':
          description: Schema versions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  versions:
                    type: array
                    items:
                      type: object
  /v1/namespaces/{ns}/collections/{c}/scan:
    parameters:
    - $ref: '#/components/parameters/ns'
    - $ref: '#/components/parameters/c'
    post:
      tags:
      - Collections
      summary: Plan an external scan
      description: Resolves the collection into what an external reader (DuckDB, pylance, Ray) needs,
        at the current manifest or a given point. The body may be empty.
      operationId: scanPlan
      x-badges:
      - name: Available
        color: '#5f8f3a'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                at:
                  description: A manifest version, a consistency token or a dataset tag.
      responses:
        '200':
          description: The scan plan.
          headers:
            Operon-Consistency-Token:
              $ref: '#/components/headers/Token'
          content:
            application/json:
              schema:
                type: object
  /v1/namespaces/{ns}/aliases:
    parameters:
    - $ref: '#/components/parameters/ns'
    post:
      tags:
      - Collections
      summary: Create or delete aliases
      operationId: aliasActions
      x-badges:
      - name: Available
        color: '#5f8f3a'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - actions
              properties:
                actions:
                  type: array
                  items:
                    type: object
                    description: '`{"create": {"alias", "collection"}}` or `{"delete": {"alias"}}`.'
      responses:
        '200':
          description: Applied.
  /v1/namespaces/{ns}/collections/{c}/hot:
    parameters:
    - $ref: '#/components/parameters/ns'
    - $ref: '#/components/parameters/c'
    put:
      tags:
      - Collections
      summary: Pin to the hot tier
      operationId: pinHot
      x-badges:
      - name: Available
        color: '#5f8f3a'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vectors:
                  type: boolean
                text:
                  type: boolean
                fragments:
                  type: boolean
      responses:
        '200':
          description: The hot-tier settings.
  /v1/namespaces/{ns}/collections/{c}/warm:
    parameters:
    - $ref: '#/components/parameters/ns'
    - $ref: '#/components/parameters/c'
    post:
      tags:
      - Collections
      summary: Warm the hot tier
      operationId: warm
      x-badges:
      - name: Available
        color: '#5f8f3a'
      responses:
        '202':
          description: Warming started.
  /v1/namespaces/{ns}/collections/{c}/documents:
    parameters:
    - $ref: '#/components/parameters/ns'
    - $ref: '#/components/parameters/c'
    post:
      tags:
      - Documents
      summary: Write documents
      description: Upserts, deletes and patches in one batch. Returns a consistency token.
      operationId: writeDocuments
      x-badges:
      - name: Available
        color: '#5f8f3a'
      parameters:
      - name: Operon-Backpressure
        in: header
        description: '`off` skips write backpressure.'
        schema:
          type: string
          enum:
          - 'off'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - ops
              properties:
                ops:
                  type: array
                  items:
                    $ref: '#/components/schemas/WriteOp'
                report_existence:
                  type: boolean
            example:
              ops:
              - upsert:
                  id: doc-1
                  source:
                    title: Soil horizons
                  vectors:
                    embedding:
                    - 0.1
                    - 0.2
              - delete:
                  id: doc-0
      responses:
        '200':
          description: Per-op results.
          headers:
            Operon-Consistency-Token:
              $ref: '#/components/headers/Token'
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    examples:
                    - v1:s3/p0@42
                  results:
                    type: array
                    items:
                      type: object
                  positions:
                    type: array
                    items:
                      type: object
        '429':
          $ref: '#/components/responses/Error'
  /v1/namespaces/{ns}/collections/{c}/documents/get:
    parameters:
    - $ref: '#/components/parameters/ns'
    - $ref: '#/components/parameters/c'
    post:
      tags:
      - Documents
      summary: Get documents by id
      operationId: getDocuments
      x-badges:
      - name: Available
        color: '#5f8f3a'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - ids
              properties:
                ids:
                  type: array
                  items:
                    type: string
                select:
                  type: object
                consistency:
                  $ref: '#/components/schemas/Consistency'
      responses:
        '200':
          description: One entry per id, null when missing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  documents:
                    type: array
                    items:
                      oneOf:
                      - $ref: '#/components/schemas/Document'
                      - type: 'null'
                  read_token:
                    type: string
  /v1/namespaces/{ns}/collections/{c}/documents/scroll:
    parameters:
    - $ref: '#/components/parameters/ns'
    - $ref: '#/components/parameters/c'
    post:
      tags:
      - Documents
      summary: Page through documents
      description: Pages by primary key.
      operationId: scrollDocuments
      x-badges:
      - name: Available
        color: '#5f8f3a'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  $ref: '#/components/schemas/Filter'
                after:
                  type: string
                limit:
                  type: integer
                  default: 100
                select:
                  type: object
                consistency:
                  $ref: '#/components/schemas/Consistency'
      responses:
        '200':
          description: A page of documents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  documents:
                    type: array
                    items:
                      $ref: '#/components/schemas/Document'
                  next:
                    type:
                    - string
                    - 'null'
                  read_token:
                    type: string
  /v1/namespaces/{ns}/collections/{c}/documents/count:
    parameters:
    - $ref: '#/components/parameters/ns'
    - $ref: '#/components/parameters/c'
    post:
      tags:
      - Documents
      summary: Count documents
      operationId: countDocuments
      x-badges:
      - name: Available
        color: '#5f8f3a'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  $ref: '#/components/schemas/Filter'
                consistency:
                  $ref: '#/components/schemas/Consistency'
      responses:
        '200':
          description: The count.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  read_token:
                    type: string
  /v1/namespaces/{ns}/collections/{c}/documents/delete_by_filter:
    parameters:
    - $ref: '#/components/parameters/ns'
    - $ref: '#/components/parameters/c'
    post:
      tags:
      - Documents
      summary: Delete by filter
      operationId: deleteByFilter
      x-badges:
      - name: Available
        color: '#5f8f3a'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - filter
              properties:
                filter:
                  $ref: '#/components/schemas/Filter'
                max_rows:
                  type: integer
                allow_partial:
                  type: boolean
                cursor:
                  type: string
      responses:
        '200':
          $ref: '#/components/responses/FilterWrite'
  /v1/namespaces/{ns}/collections/{c}/documents/patch_by_filter:
    parameters:
    - $ref: '#/components/parameters/ns'
    - $ref: '#/components/parameters/c'
    post:
      tags:
      - Documents
      summary: Patch by filter
      operationId: patchByFilter
      x-badges:
      - name: Available
        color: '#5f8f3a'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - filter
              - patch
              properties:
                filter:
                  $ref: '#/components/schemas/Filter'
                patch:
                  type: object
                max_rows:
                  type: integer
                allow_partial:
                  type: boolean
                cursor:
                  type: string
      responses:
        '200':
          $ref: '#/components/responses/FilterWrite'
  /v1/namespaces/{ns}/query:
    parameters:
    - $ref: '#/components/parameters/ns'
    post:
      tags:
      - Search
      summary: Search
      description: 'Hybrid retrieval in one planned query: vector, BM25 text and sparse retrievers, fused
        inside the engine (reciprocal rank fusion, weighted scores or DBSF), with filters, sorting, aggregations,
        highlighting and grouping.


        Two request forms are accepted. The full form has `collection` and `retrievers`. The short hybrid
        form has `from` and `retrieve`, and is used when the body has either key. Graph `expand` and `rerank`
        stages are refused until they are built.

        '
      operationId: query
      x-badges:
      - name: Available
        color: '#5f8f3a'
      parameters:
      - name: Operon-Hot
        in: header
        description: Use (`on`) or bypass (`off`) the hot tier. Results are identical either way.
        schema:
          type: string
          enum:
          - 'on'
          - 'off'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/SearchRequest'
              - $ref: '#/components/schemas/HybridRequest'
            example:
              from: docs
              retrieve:
              - vector:
                  field: embedding
                  query:
                  - 0.1
                  - 0.2
                  k: 50
              - text:
                  field: body
                  query: soil horizons
                  k: 50
              fuse: rrf
              limit: 10
      responses:
        '200':
          description: Ranked hits.
          headers:
            Operon-Hot-Used:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  hits:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        score:
                          type: number
                        sort_values:
                          type: array
                          items: {}
                        source:
                          type: object
                        vectors:
                          type: object
                        highlight:
                          type: object
                  total:
                    type: object
                  aggregations:
                    type: object
                  groups:
                    type: array
                    items:
                      type: object
                  read_token:
                    type: string
  /v1/namespaces/{ns}/sql:
    parameters:
    - $ref: '#/components/parameters/ns'
    post:
      tags:
      - Search
      summary: Run read-only SQL
      description: DataFusion SQL over collections, including the search table functions.
      operationId: sql
      x-badges:
      - name: Available
        color: '#5f8f3a'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                  examples:
                  - SELECT id, title FROM docs LIMIT 5
                consistency:
                  $ref: '#/components/schemas/Consistency'
      responses:
        '200':
          description: Columns and rows.
          content:
            application/json:
              schema:
                type: object
                properties:
                  columns:
                    type: array
                    items:
                      type: object
                  rows:
                    type: array
                    items:
                      type: array
                      items: {}
                  truncated:
                    type: boolean
  /v1/operations/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Operations
      summary: Get an operation
      operationId: getOperation
      x-badges:
      - name: In progress
        color: '#c0842f'
      responses:
        '200':
          description: The operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        '404':
          $ref: '#/components/responses/Error'
  /v1/namespaces/{ns}/operations:
    parameters:
    - $ref: '#/components/parameters/ns'
    get:
      tags:
      - Operations
      summary: List operations
      operationId: listOperations
      x-badges:
      - name: In progress
        color: '#c0842f'
      parameters:
      - name: state
        in: query
        schema:
          type: string
          enum:
          - queued
          - running
          - succeeded
          - failed
          - canceled
      - name: cursor
        in: query
        schema:
          type: string
      responses:
        '200':
          description: A page of operations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  operations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
                  next:
                    type:
                    - string
                    - 'null'
  /v1/operations/{id}/cancel:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      tags:
      - Operations
      summary: Cancel an operation
      operationId: cancelOperation
      x-badges:
      - name: In progress
        color: '#c0842f'
      responses:
        '202':
          description: Cancellation requested.
        '409':
          $ref: '#/components/responses/Error'
  /v1/namespaces/{ns}/collections/{c}/import:
    parameters:
    - $ref: '#/components/parameters/ns'
    - $ref: '#/components/parameters/c'
    post:
      tags:
      - Operations
      summary: Bulk import from object storage
      description: Starts a durable import of Parquet or NDJSON files. Repeat the request with the same
        `Idempotency-Key` to get the same operation back.
      operationId: importDocuments
      x-badges:
      - name: In progress
        color: '#c0842f'
      parameters:
      - name: Idempotency-Key
        in: header
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - source
              - format
              properties:
                source:
                  type: string
                  examples:
                  - s3://bucket/exports/
                format:
                  type: string
                  enum:
                  - parquet
                  - ndjson
                pattern:
                  type: string
                mapping:
                  type: object
                  properties:
                    columns:
                      type: object
                      additionalProperties:
                        type: string
                    id_type:
                      type: string
                      enum:
                      - str
                      - u64
                      - uuid
                    id_column:
                      type: string
                on_error:
                  type: string
                  enum:
                  - fail
                  - skip_file
                max_parallel_files:
                  type: integer
                  maximum: 64
      responses:
        '202':
          description: Started. `Location` points at the operation.
          headers:
            Location:
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  location:
                    type: string
        '409':
          $ref: '#/components/responses/Error'
components:
  parameters:
    ns:
      name: ns
      in: path
      required: true
      description: Namespace name.
      schema:
        type: string
    c:
      name: c
      in: path
      required: true
      description: Collection name or alias.
      schema:
        type: string
  headers:
    Token:
      description: Consistency token covering this write or read.
      schema:
        type: string
        examples:
        - v1:s3/p0@42
  responses:
    Created:
      description: Created.
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                type: integer
    Error:
      description: An error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    FilterWrite:
      description: How many rows matched and changed, and a cursor to continue when partial.
      headers:
        Operon-Consistency-Token:
          $ref: '#/components/headers/Token'
      content:
        application/json:
          schema:
            type: object
  schemas:
    Error:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          enum:
          - invalid_argument
          - not_found
          - already_exists
          - conflict
          - offset_out_of_range
          - resource_exhausted
          - unavailable
          - internal
        message:
          type: string
        retry_after_ms:
          type: integer
    RecordIn:
      type: object
      properties:
        key:
          type: string
          contentEncoding: base64
        value:
          type: string
          contentEncoding: base64
        headers:
          type: array
          items:
            type: object
            required:
            - key
            properties:
              key:
                type: string
              value:
                type: string
                contentEncoding: base64
        timestamp_ms:
          type: integer
    Record:
      allOf:
      - $ref: '#/components/schemas/RecordIn'
      - type: object
        properties:
          offset:
            type: integer
    CollectionSchema:
      type: object
      properties:
        fields:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              source_path:
                type: string
              kind:
                type: string
                examples:
                - text
                - keyword
                - integer
                - float
                - date
                - bool
              indexed:
                type: boolean
              fast:
                type: boolean
        vectors:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              dim:
                type: integer
              distance:
                type: string
                examples:
                - cosine
                - dot
                - l2
              index:
                type: object
        sparse_vectors:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              modifier:
                type: string
                examples:
                - idf
        dynamic:
          type: string
          enum:
          - strict
          - ignore
          - map
        max_fields:
          type: integer
        annotations:
          type: object
    CollectionInfo:
      type: object
      properties:
        name:
          type: string
        schema:
          $ref: '#/components/schemas/CollectionSchema'
        partitions:
          type: integer
        hot:
          type: object
    Document:
      type: object
      properties:
        id:
          type: string
        source:
          type: object
        vectors:
          type: object
          additionalProperties:
            type: array
            items:
              type: number
        sparse_vectors:
          type: object
        fields:
          type: object
        seq_no:
          type: integer
        partition:
          type: integer
    WriteOp:
      type: object
      description: Exactly one of `upsert`, `delete` or `patch`.
      properties:
        upsert:
          type: object
          required:
          - id
          properties:
            id:
              type: string
            source:
              type: object
            vectors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: number
            sparse_vectors:
              type: object
        delete:
          type: object
          required:
          - id
          properties:
            id:
              type: string
        patch:
          type: object
          required:
          - id
          properties:
            id:
              type: string
            mode:
              type: string
              enum:
              - merge_deep
              - merge_top
              - replace
            source:
              type: object
            delete_keys:
              type: array
              items:
                type: string
            vectors:
              type: object
            sparse_vectors:
              type: object
            upsert:
              type: boolean
    Consistency:
      description: '`"strong"` (default), `"eventual"`, `{"at_least": "<token>"}` or `{"pinned": {"manifest_version",
        "token"}}`.'
      oneOf:
      - type: string
        enum:
        - strong
        - eventual
      - type: object
        required:
        - at_least
        additionalProperties: false
        properties:
          at_least:
            type: string
      - type: object
        required:
        - pinned
        additionalProperties: false
        properties:
          pinned:
            type: object
            properties:
              manifest_version:
                type: integer
              token:
                type: string
    Filter:
      type: object
      description: 'Boolean filter: `and`, `or`, `not`, `term`, `terms`, `range` (`gt`, `gte`, `lt`, `lte`),
        `exists`, `ids`, `match`.'
    SearchRequest:
      type: object
      title: Full form
      required:
      - collection
      - retrievers
      properties:
        collection:
          type: string
        consistency:
          $ref: '#/components/schemas/Consistency'
        retrievers:
          type: array
          description: 'Retriever kinds: `vector`, `text`, `sparse`, `fused`, `rescore`.'
          items:
            type: object
        fusion:
          type: object
        filter:
          $ref: '#/components/schemas/Filter'
        sort:
          type: array
          items:
            type: object
        offset:
          type: integer
        limit:
          type: integer
          default: 10
        search_after:
          type: array
          items: {}
        score_threshold:
          type: number
        select:
          type: object
        aggregations:
          type: object
        highlight:
          type: object
        group_by:
          type: object
        track_total_hits:
          type:
          - boolean
          - integer
    HybridRequest:
      type: object
      title: Short hybrid form
      required:
      - from
      - retrieve
      properties:
        from:
          type: string
          description: Collection name.
        consistency:
          type: object
          properties:
            token:
              type: string
        retrieve:
          type: array
          items:
            type: object
            description: '`{"vector": {field, query, k, exact, nprobes, refine_factor, ef}}` or `{"text":
              {field, query, k, operator}}`.'
        filter:
          $ref: '#/components/schemas/Filter'
        fuse:
          description: '`rrf` or a fusion object.'
        select:
          type: object
        limit:
          type: integer
        offset:
          type: integer
    Operation:
      type: object
      properties:
        id:
          type: string
        kind:
          type: string
          examples:
          - import
        namespace:
          type: string
        target:
          type: string
        state:
          type: string
          enum:
          - queued
          - running
          - succeeded
          - failed
          - canceled
        progress:
          type: object
        result:
          type: object
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time