Affinda

Affinda Annotations API

Manually create, update, and delete annotations on uploaded documents. Annotations are the field-level extraction objects (value, confidence, bounding box, parent field) and provide the surface for human-in-the-loop validation and review. Supports batch create, update, and delete for high-throughput review workflows.

GitHub OpenAPI

Operations 8

GET /v3/annotations Get list of all annotations #
POST /v3/annotations Create a annotation #
GET /v3/annotations/{id} Get specific annotation #
PATCH /v3/annotations/{id} Update an annotation #
DELETE /v3/annotations/{id} Delete an annotation #
POST /v3/annotations/batch_create Batch create annotations #
POST /v3/annotations/batch_update Batch update annotations #
POST /v3/annotations/batch_delete Batch delete annotations #

Documentation

📖
Documentation
https://docs.affinda.com/reference/annotations

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/affinda/refs/heads/main/openapi/affinda-annotations-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/affinda-annotations-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

affinda-annotations-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  description: '# Introduction

    Affinda uses the latest advancements in AI technology to rapidly process documents with better-than-human accuracy.'
  version: v3
  title: Affinda Annotations API
  contact:
    email: contact@affinda.com
  license:
    name: MIT
    url: https://raw.githubusercontent.com/affinda/affinda-api-spec/master/LICENSE
  x-logo:
    url: https://api.affinda.com/static/documentation/affinda_logo.png
    backgroundColor: '#FFFFFF'
    altText: Affinda logo
servers:
- url: https://{region}.affinda.com
  description: 'Select the correct server for your instance: api (AUS/Global), api.us1 (US), or api.eu1 (EU).'
  variables:
    region:
      default: api
      description: The instance region. Use 'api' for AUS/Global, 'api.us1' for US, or 'api.eu1' for EU. You can find your region in the Affinda web app URL.
      enum:
      - api
      - api.eu1
      - api.us1
      x-ms-parameter-location: client
security:
- ApiKeyAuth: []
tags:
- name: Annotations
  description: 'Operations to manually create, update, delete annotations.


    Together with the data point endpoints, these helps to annotate your documents with arbitrary data,

    or to edit annotations that were created by the Affinda parser.'
paths:
  /v3/annotations:
    get:
      tags:
      - Annotations
      summary: Get list of all annotations
      operationId: getAllAnnotations
      description: Returns your annotations.
      parameters:
      - in: query
        name: document
        required: true
        schema:
          $ref: '#/components/schemas/DocumentMeta_properties-identifier'
        description: Filter by document.
      responses:
        '200':
          description: All matching annotations.
          content:
            application/json:
              schema:
                type: object
                required:
                - results
                - count
                allOf:
                - $ref: '#/components/schemas/PaginatedResponse'
                - type: object
                  properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/Annotation'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    post:
      tags:
      - Annotations
      summary: Create a annotation
      operationId: createAnnotation
      responses:
        '201':
          description: Successfully created a annotation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationWithValidationResults'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnotationCreate'
  /v3/annotations/{id}:
    get:
      tags:
      - Annotations
      summary: Get specific annotation
      operationId: getAnnotation
      description: Return a specific annotation.
      parameters:
      - in: path
        required: true
        name: id
        description: Annotation's ID
        schema:
          $ref: '#/components/schemas/Annotation_properties-id'
      responses:
        '200':
          description: Successfully retrieved annotation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Annotation'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    patch:
      tags:
      - Annotations
      summary: Update an annotation
      operationId: updateAnnotation
      description: Update data of an annotation.
      parameters:
      - in: path
        required: true
        name: id
        description: Annotation's ID
        schema:
          $ref: '#/components/schemas/Annotation_properties-id'
      requestBody:
        description: Annotation data to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnotationUpdate'
      responses:
        '200':
          description: Successfully updated annotation data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Annotation'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    delete:
      tags:
      - Annotations
      summary: Delete an annotation
      operationId: deleteAnnotation
      description: Deletes the specified annotation from the database.
      parameters:
      - in: path
        required: true
        name: id
        description: Annotation's ID
        schema:
          $ref: '#/components/schemas/Annotation_properties-id'
      responses:
        '200':
          description: Successfully deleted annotation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnotationDelete'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/annotations/batch_create:
    post:
      tags:
      - Annotations
      summary: Batch create annotations
      operationId: batchCreateAnnotations
      responses:
        '201':
          description: Successfully created annotations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchCreateAnnotationsResponse'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCreateAnnotationsRequest'
  /v3/annotations/batch_update:
    post:
      tags:
      - Annotations
      summary: Batch update annotations
      operationId: batchUpdateAnnotations
      responses:
        '200':
          description: Successfully updated annotations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchUpdateAnnotationsResponse'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUpdateAnnotationsRequest'
  /v3/annotations/batch_delete:
    post:
      tags:
      - Annotations
      summary: Batch delete annotations
      operationId: batchDeleteAnnotations
      responses:
        '200':
          description: Successfully deleted annotations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchDeleteAnnotationsResponse'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchDeleteAnnotationsRequest'
components:
  schemas:
    BatchDeleteAnnotationsRequest:
      type: array
      description: Array of annotation IDs to be deleted
      items:
        $ref: '#/components/schemas/Annotation_properties-id'
    rectangles:
      type: array
      items:
        $ref: '#/components/schemas/Rectangle'
      description: x/y coordinates for the rectangles containing the data. An annotation can be contained within multiple rectangles.
    parent:
      type:
      - integer
      - 'null'
      description: The parent annotation's ID
    BatchUpdateAnnotationsRequest:
      type: array
      items:
        $ref: '#/components/schemas/AnnotationBatchUpdate'
    pageIndex:
      type:
      - integer
      - 'null'
      example: 0
      minimum: 0
      description: The page number within the document, starting from 0.
    field:
      type:
      - string
      - 'null'
      description: Field's identifier
    Annotation_properties-id:
      type: integer
      description: Annotation's ID
      example: 1
      minimum: 1
    isClientVerified:
      type: boolean
      description: Indicates whether the data has been validated by a human
    dataPoint:
      type: string
      description: Data point's identifier
    DocumentMeta_properties-identifier:
      type: string
      description: Unique identifier for the document
    AnnotationCreate:
      type: object
      required:
      - document
      - pageIndex
      properties:
        rectangles:
          $ref: '#/components/schemas/rectangles'
        document:
          $ref: '#/components/schemas/DocumentMeta_properties-identifier'
        pageIndex:
          $ref: '#/components/schemas/pageIndex'
        dataPoint:
          $ref: '#/components/schemas/dataPoint'
        field:
          $ref: '#/components/schemas/field'
        raw:
          $ref: '#/components/schemas/raw'
        parsed:
          oneOf:
          - type:
            - string
            - 'null'
          - type:
            - integer
            - 'null'
          - type:
            - number
            - 'null'
          - type:
            - boolean
            - 'null'
          - type:
            - object
            - 'null'
            additionalProperties: true
          - type:
            - array
            - 'null'
            items:
              $ref: '#/components/schemas/AnnotationCreate'
        isClientVerified:
          $ref: '#/components/schemas/isClientVerified'
        parent:
          type:
          - integer
          - 'null'
          description: The parent annotation's ID
        validationResults:
          type: array
          description: The validation results created, changed or deleted as a result of creating the annotation.
          items:
            $ref: '#/components/schemas/ChangedValidationResults'
    ValidationResult:
      type: object
      additionalProperties: false
      description: Validation result arising from a ValidationRule
      required:
      - id
      - annotations
      - passed
      - ruleSlug
      - message
      - document
      properties:
        id:
          type: integer
          description: Validation Result's ID
          example: 1
          minimum: 1
        annotations:
          type: array
          items:
            type: integer
          description: List of annotation ids that were validated
          example:
          - 1
          - 2
          - 3
        passed:
          type:
          - boolean
          - 'null'
          description: Whether the validation passed or not, null if the validation was not applicable
          example: true
        ruleSlug:
          type: string
          description: The kebab-case slug of the validation rule that was applied
          example: supplier-name-is-alphanumeric
          pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
        message:
          type: string
          description: Message explaining why the validation failed
          example: Expected 'ThisInputShouldMatch' to match regex pattern '[0-9]*
        document:
          $ref: '#/components/schemas/DocumentMeta_properties-identifier'
    validationResults:
      type: array
      description: The validation results created, changed or deleted as a result of updating the annotation.
      items:
        $ref: '#/components/schemas/ChangedValidationResults'
    ChangedValidationResults:
      type:
      - object
      - 'null'
      additionalProperties: true
      properties:
        created:
          type: array
          description: List of validation results created during this operation.
          items:
            $ref: '#/components/schemas/ValidationResult'
        updated:
          type: array
          description: List of validation results updated during this operation.
          items:
            $ref: '#/components/schemas/ValidationResult'
        deleted:
          type: array
          description: List of validation results deleted during this operation.
          items:
            $ref: '#/components/schemas/ValidationResult'
    AnnotationContentType:
      type: string
      description: The different data types of annotations
      enum:
      - text
      - integer
      - float
      - decimal
      - date
      - datetime
      - daterange
      - boolean
      - enum
      - location
      - phonenumber
      - json
      - table
      - expectedremuneration
      - jobtitle
      - language
      - skill
      - yearsexperience
      - group
      - table_deprecated
      - url
      - image
      - docclf
    AnnotationBatchUpdate:
      type: object
      required:
      - id
      properties:
        id:
          $ref: '#/components/schemas/Annotation_properties-id'
        rectangles:
          $ref: '#/components/schemas/rectangles'
        document:
          $ref: '#/components/schemas/DocumentMeta_properties-identifier'
        pageIndex:
          $ref: '#/components/schemas/pageIndex'
        raw:
          $ref: '#/components/schemas/raw'
        parsed:
          $ref: '#/components/schemas/parsed'
        isClientVerified:
          $ref: '#/components/schemas/isClientVerified'
        dataPoint:
          $ref: '#/components/schemas/dataPoint'
        parent:
          $ref: '#/components/schemas/parent'
        validationResults:
          $ref: '#/components/schemas/validationResults'
    BatchUpdateAnnotationsResponse:
      type: array
      items:
        $ref: '#/components/schemas/Annotation'
    parsed:
      oneOf:
      - type:
        - string
        - 'null'
      - type:
        - integer
        - 'null'
      - type:
        - number
        - 'null'
      - type:
        - boolean
        - 'null'
      - type:
        - object
        - 'null'
        additionalProperties: true
      - type:
        - array
        - 'null'
        items:
          $ref: '#/components/schemas/AnnotationCreate'
    Rectangle:
      type: object
      additionalProperties: false
      required:
      - x0
      - y0
      - x1
      - y1
      properties:
        pageIndex:
          type: integer
          example: 1
          minimum: 0
        x0:
          type: number
          example: 2.43
        y0:
          type: number
          example: 4.55
        x1:
          type: number
          example: 4.56
        y1:
          type: number
          example: 6.32
    BatchCreateAnnotationsResponse:
      type: array
      items:
        $ref: '#/components/schemas/Annotation'
    AnnotationWithValidationResults:
      type:
      - object
      - 'null'
      allOf:
      - $ref: '#/components/schemas/Annotation'
      - type: object
        properties:
          validationResults:
            type: array
            description: List of validation results for this annotation.
            items:
              $ref: '#/components/schemas/ValidationResult'
    RequestError:
      type: object
      additionalProperties: false
      required:
      - type
      - errors
      properties:
        type:
          type: string
          example: validation_error
        errors:
          type: array
          items:
            type: object
            required:
            - attr
            - code
            - detail
            properties:
              attr:
                type:
                - string
                - 'null'
                example: non_field_errors
              code:
                type: string
                example: unique
              detail:
                type: string
                example: This index name has already been used
    Annotation:
      type:
      - object
      - 'null'
      additionalProperties: true
      required:
      - id
      - rectangle
      - rectangles
      - document
      - pageIndex
      - raw
      - confidence
      - classificationConfidence
      - textExtractionConfidence
      - isVerified
      - isClientVerified
      - isAutoVerified
      - contentType
      properties:
        id:
          type: integer
          description: Annotation's ID
          example: 1
          minimum: 1
        rectangle:
          $ref: '#/components/schemas/Rectangle'
          description: x/y coordinates for the rectangular bounding box containing the data
        rectangles:
          type: array
          items:
            $ref: '#/components/schemas/Rectangle'
          description: x/y coordinates for the rectangles containing the data. An annotation can be contained within multiple rectangles.
        document:
          $ref: '#/components/schemas/DocumentMeta_properties-identifier'
        pageIndex:
          type:
          - integer
          - 'null'
          example: 0
          minimum: 0
          description: The page number within the document, starting from 0.
        raw:
          type:
          - string
          - 'null'
          description: Raw data extracted from the before any post-processing
        confidence:
          type:
          - number
          - 'null'
          example: 0.86
          description: The overall confidence that the model's prediction is correct
        classificationConfidence:
          type:
          - number
          - 'null'
          example: 0.95
          description: The model's confidence that the text has been classified correctly
        textExtractionConfidence:
          type:
          - number
          - 'null'
          example: 0.9
          description: If the document was submitted as an image, this is the confidence that the text in the image has been correctly read by the model
        isVerified:
          type: boolean
          description: Indicates whether the data has been validated, either by a human using our validation tool or through auto-validation rules
        isClientVerified:
          type: boolean
          description: Indicates whether the data has been validated by a human
        isAutoVerified:
          type: boolean
          description: Indicates whether the data has been auto-validated
        dataPoint:
          type: string
          description: Data point's identifier
        field:
          type:
          - string
          - 'null'
          description: Field's identifier
        contentType:
          $ref: '#/components/schemas/AnnotationContentType'
        parent:
          type:
          - integer
          - 'null'
          description: The parent annotation's ID
    AnnotationUpdate:
      type: object
      properties:
        rectangles:
          $ref: '#/components/schemas/rectangles'
        document:
          $ref: '#/components/schemas/DocumentMeta_properties-identifier'
        pageIndex:
          $ref: '#/components/schemas/pageIndex'
        raw:
          $ref: '#/components/schemas/raw'
        parsed:
          oneOf:
          - type:
            - string
            - 'null'
          - type:
            - integer
            - 'null'
          - type:
            - number
            - 'null'
          - type:
            - boolean
            - 'null'
          - type:
            - object
            - 'null'
            additionalProperties: true
          - type:
            - array
            - 'null'
            items:
              $ref: '#/components/schemas/AnnotationCreate'
        isClientVerified:
          $ref: '#/components/schemas/isClientVerified'
        dataPoint:
          $ref: '#/components/schemas/dataPoint'
        field:
          $ref: '#/components/schemas/field'
        parent:
          $ref: '#/components/schemas/parent'
        validationResults:
          type: array
          description: The validation results created, changed or deleted as a result of updating the annotation.
          items:
            $ref: '#/components/schemas/ChangedValidationResults'
    raw:
      type:
      - string
      - 'null'
      description: Raw data extracted from the before any post-processing
    AnotationDelete:
      type: object
      properties:
        validationResults:
          type: object
          description: The validation results created, changed or deleted as a result of deleting the annotation.
          items:
            $ref: '#/components/schemas/ChangedValidationResults'
    BatchCreateAnnotationsRequest:
      type: array
      items:
        $ref: '#/components/schemas/AnnotationCreate'
    BatchDeleteAnnotationsResponse:
      type: object
      properties:
        validationResults:
          type: object
          description: The validation results created, changed or deleted as a result of deleting the annotations.
          items:
            $ref: '#/components/schemas/ChangedValidationResults'
    PaginatedResponse:
      type: object
      required:
      - count
      properties:
        count:
          type: integer
          example: 10
          description: Number of items in results.
          minimum: 0
        next:
          type:
          - string
          - 'null'
          description: URL to request next page of results.
        previous:
          type:
          - string
          - 'null'
          description: URL to request previous page of results.
  responses:
    400Error:
      description: Bad request. If it is a validation error will contain a list of each invalid field
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestError'
      x-ms-error-response: true
    401Error:
      description: Authorisation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestError'
      x-ms-error-response: true
    DefaultError:
      description: UnexpectedError
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestError'
      x-ms-error-response: true
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: 'Basic authentication using an API key, e.g. `{Authorization: Bearer aff_0bb4fbdf97b7e4111ff6c0015471094155f91}`.

        You can find your API key within the Settings page of the [Affinda web app](https://app.affinda.com/). You can obtain an API key by [signing up for a free trial](https://app.affinda.com/auth/register).'