naftiko: 1.0.0-alpha2
info:
  label: Affinda Annotations API — Annotations
  description: Affinda Annotations — create, list, update, delete field-level annotations on parsed
    documents, with batch operations for high-throughput human-in-the-loop review.
  tags:
  - Affinda
  - Annotations
  - Human in the Loop
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
- namespace: env
  keys:
    AFFINDA_API_KEY: AFFINDA_API_KEY
capability:
  consumes:
  - type: http
    namespace: annotations
    baseUri: https://api.affinda.com
    description: Affinda v3 Annotations.
    resources:
    - name: v3-annotations
      path: /v3/annotations
      operations:
      - name: listannotations
        method: GET
        description: List annotations with filters (document).
        outputRawFormat: json
        outputParameters: [{name: results, type: object, value: $.}]
        inputParameters:
        - {name: document, in: query, type: string}
      - name: createannotation
        method: POST
        description: Create an annotation.
        outputRawFormat: json
        outputParameters: [{name: annotation, type: object, value: $.}]
        inputParameters:
        - {name: body, in: body, type: object, required: true}
    - name: v3-annotations-id
      path: /v3/annotations/{id}
      operations:
      - name: updateannotation
        method: PATCH
        description: Update an annotation.
        outputRawFormat: json
        outputParameters: [{name: annotation, type: object, value: $.}]
        inputParameters:
        - {name: id, in: path, type: integer, required: true}
        - {name: body, in: body, type: object, required: true}
      - name: deleteannotation
        method: DELETE
        description: Delete an annotation.
        outputRawFormat: json
        outputParameters: [{name: result, type: object, value: $.}]
        inputParameters:
        - {name: id, in: path, type: integer, required: true}
    - name: v3-annotations-batch
      path: /v3/annotations/batch_create
      operations:
      - name: batchcreateannotations
        method: POST
        description: Batch-create annotations.
        outputRawFormat: json
        outputParameters: [{name: results, type: object, value: $.}]
        inputParameters:
        - {name: body, in: body, type: object, required: true}
    authentication:
      type: apikey
      key: Authorization
      value: 'Bearer {{env.AFFINDA_API_KEY}}'
      placement: header
  exposes:
  - type: mcp
    namespace: annotations-mcp
    port: 9090
    transport: http
    description: MCP adapter for Affinda Annotations.
    tools:
    - name: affinda-list-annotations
      description: List Affinda annotations for a document.
      hints: {readOnly: true, destructive: false, idempotent: true}
      call: annotations.listannotations
      with: {document: tools.document}
      outputParameters: [{type: object, mapping: $.}]
    - name: affinda-create-annotation
      description: Create an annotation on an Affinda document.
      hints: {readOnly: false, destructive: false, idempotent: false}
      call: annotations.createannotation
      with: {body: tools.body}
      outputParameters: [{type: object, mapping: $.}]
    - name: affinda-batch-create-annotations
      description: Batch create annotations on Affinda documents.
      hints: {readOnly: false, destructive: false, idempotent: false}
      call: annotations.batchcreateannotations
      with: {body: tools.body}
      outputParameters: [{type: object, mapping: $.}]