openapi: 3.2.0
info:
  title: Anomalo Unstructured Data Documents API
  version: v1
  summary: Document collection, document issue and content-analysis endpoints for Anomalo's unstructured data monitoring.
  description: 'Anomalo''s unstructured data monitoring surface, exposed under the same `/api/public/v1/` base path as the

    Anomalo Public API but scoped to an organization (`/orgs/{org_id}/...`). Covers document collections

    (sets of unstructured documents sourced from a cloud object store bucket or a warehouse table column),

    the content-analysis check runs executed against them, the per-document and per-collection issues

    Anomalo detects, and the generated metadata breakdown (tone, sentiment, language, theme, writing level,

    score).


    DERIVATION NOTE: this description was derived mechanically by API Evangelist from `anomalo_api.py` in

    Anomalo''s first-party, Apache-2.0 licensed `anomalo-gemini-extension` repository, where the

    `AnomaloClient` subclass calls these endpoints via the inherited `_api_call()` helper. Every path, HTTP

    method and parameter below is read from those invocations. These endpoints are not exposed by the

    published `anomalo` PyPI client and back the MCP server''s experimental unstructured tools, which are

    gated behind the `ANOMALO_EXPERIMENTAL_UNSTRUCTURED_TOOLS` environment variable — treat them as

    experimental. Response schemas are documented from the MCP tool docstrings, which enumerate the fields

    Anomalo returns; nothing has been invented. This is an unofficial, derived description and is not

    endorsed by Anomalo.'
  contact:
    name: Anomalo
    url: https://www.anomalo.com/contact-us/
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  x-derived-from: https://github.com/datagravity-ai/anomalo-gemini-extension/blob/main/anomalo-mcp-server/anomalo_api.py
  x-derived-by: API Evangelist enrichment pipeline
  x-unofficial: true
  x-status: experimental
servers:
- url: https://{instance}/api/public/v1
  description: Anomalo is deployed per-tenant. The client reads the host from the `ANOMALO_INSTANCE_HOST` environment variable.
  variables:
    instance:
      default: app.anomalo.com
      description: Your Anomalo instance host, e.g. app.anomalo.com or my-company.anomalo.com
security:
- AnomaloToken: []
tags:
- name: Documents
  description: Individual documents within a collection, and the issues found in them.
paths:
  /orgs/{org_id}/documents:
    get:
      operationId: listDocuments
      summary: List the documents analyzed in a content-analysis check run
      tags:
      - Documents
      x-client-methods:
      - get_collection_breakdown
      parameters:
      - name: org_id
        in: path
        required: true
        description: Anomalo organization (tenant) identifier.
        schema:
          type: string
      - name: document_collection_checkrun_id
        in: query
        required: true
        description: The content-analysis check run whose documents should be returned.
        schema:
          type: string
      responses:
        '200':
          description: Documents included in the check run.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  responses:
    Forbidden:
      description: Authenticated but not permitted for this organization or resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request. Raised by the client as BadRequestException (not retried).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Server error. The first-party client retries these up to 5 times with exponential jitter backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      description: 'Error body. The first-party client raises BadRequestException for 4xx and RuntimeError for 5xx,

        carrying the raw response text; Anomalo does not publish a documented error envelope schema.'
      additionalProperties: true
  securitySchemes:
    AnomaloToken:
      type: apiKey
      in: header
      name: X-Anomalo-Token
      description: Anomalo API secret token, read from the `ANOMALO_API_SECRET_TOKEN` environment variable.
    BearerToken:
      type: http
      scheme: bearer
      description: 'Anomalo API secret token sent as `Authorization: Bearer <token>`.'