openapi: 3.2.0
info:
  title: Anomalo Unstructured Data Document Collections 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: Document Collections
  description: Sets of unstructured documents Anomalo monitors and analyzes.
paths:
  /orgs/{org_id}/document_collections:
    get:
      operationId: listDocumentCollections
      summary: List the unstructured document collections monitored in an organization
      description: 'Retrieves the unstructured document collections being monitored by Anomalo for the given organization.

        A collection is a set of unstructured documents Anomalo has analyzed and enriched with metadata,

        classification and quality issues. The source may be a cloud object storage bucket or a column in a

        data warehouse table.'
      tags:
      - Document Collections
      x-client-methods:
      - get_collections
      parameters:
      - name: org_id
        in: path
        required: true
        description: Anomalo organization (tenant) identifier.
        schema:
          type: string
      responses:
        '200':
          description: The collections monitored in this organization.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Collection'
        '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'
  /orgs/{org_id}/document_collections/{collection_id}:
    get:
      operationId: getDocumentCollection
      summary: Retrieve a single unstructured document collection
      tags:
      - Document Collections
      x-client-methods:
      - get_collection
      parameters:
      - name: org_id
        in: path
        required: true
        description: Anomalo organization (tenant) identifier.
        schema:
          type: string
      - name: collection_id
        in: path
        required: true
        description: Document collection identifier.
        schema:
          type: string
      responses:
        '200':
          description: The requested collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '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'
  /orgs/{org_id}/document_collections/{collection_id}/metadata:
    get:
      operationId: listDocumentCollectionMetadata
      summary: Retrieve the generated metadata breakdown for a document collection
      description: 'Returns the metadata categories Anomalo generates for a collection — tone, sentiment, language,

        theme, writing_level and score — with their respective entries and counts.'
      tags:
      - Document Collections
      x-client-methods:
      - get_collection_metadata
      parameters:
      - name: org_id
        in: path
        required: true
        description: Anomalo organization (tenant) identifier.
        schema:
          type: string
      - name: collection_id
        in: path
        required: true
        description: Document collection identifier.
        schema:
          type: string
      responses:
        '200':
          description: Metadata categories and their entry counts.
          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'
  /orgs/{org_id}/document_collection_checkruns:
    get:
      operationId: listDocumentCollectionCheckRuns
      summary: List content-analysis check runs for a document collection
      description: 'Returns the content-analysis runs executed against a document collection, most recent first. The

        first-party adapter requests `limit=5` and filters by `document_collection_id` to locate the most

        recent completed run.'
      tags:
      - Document Collections
      x-client-methods:
      - get_last_collection_check_run
      parameters:
      - name: org_id
        in: path
        required: true
        description: Anomalo organization (tenant) identifier.
        schema:
          type: string
      - name: document_collection_id
        in: query
        required: true
        description: Document collection to list check runs for.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Maximum number of check runs to return.
        schema:
          type: integer
      responses:
        '200':
          description: Content-analysis check runs for the collection.
          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:
    Collection:
      type: object
      description: 'An unstructured document collection. Field list taken verbatim from the `get_unstructured_collections`

        MCP tool docstring in Anomalo''s first-party MCP server.'
      properties:
        id:
          type: string
          description: The unique identifier for the collection.
        name:
          type: string
          description: The name of the collection.
        description:
          type: string
          description: A description of the collection.
        organization_id:
          type: string
          description: The ID of the Anomalo organization that contains the collection.
        source_type:
          type: string
          description: The type of source for the collection.
          examples:
          - s3
          - data_warehouse
        bucket_name:
          type: string
          description: The bucket where the collection's documents are stored, if applicable.
        path_prefix:
          type: string
          description: The prefix path within the bucket where the documents are stored, if applicable.
        mime_types:
          type: array
          description: MIME types the collection is configured to process.
          items:
            type: string
        ai_model:
          type: string
          description: The AI model used for analyzing the documents in the collection.
      additionalProperties: true
    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>`.'