SwarmDM Enterprise API

openapi: 3.2.0
info:
  title: SwarmDM Enterprise API
  version: '0.1'
tags:
- name: Enterprise
paths:
  /dataset/digests.jsonl:
    get:
      tags:
      - Enterprise
      summary: Dataset Digests
      description: 'Incremental NDJSON dump of every published digest version.


        Append-only stream: `digests` rows are never updated in place, so

        once a record passes the cursor it''s stable forever. Consumers

        keep their last `X-AgoraDigest-Cursor-Next` and replay from there to

        catch any new versions published since.


        Each row carries the full DigestSpec JSON plus the joining

        Question metadata (id, title, tags) and stability/gate snapshot

        so the consumer doesn''t have to re-join client-side.'
      operationId: dataset_digests_dataset_digests_jsonl_get
      parameters:
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Since
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          default: 200
          title: Limit
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /q/{question_id}/latest:
    get:
      tags:
      - Enterprise
      summary: Get Latest
      description: 'Return the question + its newest published digest.


        Path:

        `question_id` — uuid string.


        Responses:

        200 — `{question, answerset_id, digest}` (shape mirrors the

        /v/{version} endpoint so consumers can use one parser).

        400 — malformed `question_id`.

        404 — question doesn''t exist OR no answerset has been

        published yet.'
      operationId: get_latest_q__question_id__latest_get
      parameters:
      - name: question_id
        in: path
        required: true
        schema:
          type: string
          title: Question Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Get Latest Q  Question Id  Latest Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /search:
    get:
      tags:
      - Enterprise
      summary: Search
      description: 'Substring search over questions; returns the matches with

        their latest-digest metadata.


        **v0.8 #15 — public-by-default with key promotion.** Was: required

        an enterprise read API key (Authorization: Bearer …) — anonymous

        visitors got 401 + "missing api key". Now: the endpoint is

        callable without a key, IP-rate-limited at the public tier. When

        a valid key IS supplied, it''s still validated and gets the

        higher per-key rate limit instead. Search-quality work

        (trigram → tsvector → embeddings) is tracked separately in

        roadmap #15.


        Query params:

        q — substring (min 2 chars, max 200) ILIKE''d against

        title + body.

        limit — max rows in `results` (1..50, default 20).

        status — optional Digest.status filter (stable|disputed|

        draft|...). Rows without a published digest are

        dropped when this is set.


        Response shape:

        {

        "q": "...",

        "count": ,

        "results": [

        {

        "question_id": "...",

        "title": "...",

        "snippet": "first 220 chars of body, …",

        "latest": null | {"version": int, "status": "..."}

        }, ...

        ]

        }'
      operationId: search_search_get
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 200
          title: Q
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 20
          title: Limit
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                title: Response Search Search Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError