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

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

OpenAPI Specification

affinda-annotations-api-openapi.yml Raw ↑ 
openapi: 3.0.3
info:
  title: Affinda Add x-hidden to endpoints Annotations API
  version: 3.0.0
  description: Affinda Annotations API — subset of the Affinda v3 Document Processing API.
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
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
      description: Create a annotation
      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
      description: Batch create annotations
      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
      description: Batch update annotations
      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
      description: Batch delete annotations
      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:
    Annotation:
      type: object
      additionalProperties: true
      nullable: 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'
          nullable: true
          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
          nullable: true
          example: 0
          minimum: 0
          description: The page number within the document, starting from 0.
        raw:
          type: string
          nullable: true
          description: Raw data extracted from the before any post-processing
        confidence:
          type: number
          nullable: true
          example: 0.86
          description: The overall confidence that the model's prediction is correct
        classificationConfidence:
          type: number
          nullable: true
          example: 0.95
          description: The model's confidence that the text has been classified correctly
        textExtractionConfidence:
          type: number
          nullable: true
          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
          description: Field's identifier
          nullable: true
        contentType:
          $ref: '#/components/schemas/AnnotationContentType'
        parent:
          type: integer
          description: The parent annotation's ID
          nullable: true
    field:
      type: string
      description: Field's identifier
      nullable: true
    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'
    AnnotationWithValidationResults:
      type: object
      nullable: true
      allOf:
      - $ref: '#/components/schemas/Annotation'
      - type: object
        properties:
          validationResults:
            type: array
            description: List of validation results for this annotation.
            items:
              $ref: '#/components/schemas/ValidationResult'
    pageIndex:
      type: integer
      nullable: true
      example: 0
      minimum: 0
      description: The page number within the document, starting from 0.
    BatchCreateAnnotationsResponse:
      type: array
      items:
        $ref: '#/components/schemas/Annotation'
    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
                nullable: true
                example: non_field_errors
              code:
                type: string
                example: unique
              detail:
                type: string
                example: This index name has already been used
    DocumentMeta_properties-identifier:
      type: string
      description: Unique identifier for the document
    Rectangle:
      type: object
      additionalProperties: false
      nullable: false
      required:
      - x0
      - y0
      - x1
      - y1
      properties:
        pageIndex:
          type: integer
          nullable: false
          example: 1
          minimum: 0
        x0:
          type: number
          nullable: false
          example: 2.43
        y0:
          type: number
          nullable: false
          example: 4.55
        x1:
          type: number
          nullable: false
          example: 4.56
        y1:
          type: number
          nullable: false
          example: 6.32
    isClientVerified:
      type: boolean
      description: Indicates whether the data has been validated by a human
    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
    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.
    PaginatedResponse:
      type: object
      required:
      - count
      properties:
        count:
          type: integer
          example: 10
          description: Number of items in results.
          minimum: 0
        next:
          type: string
          nullable: true
          description: URL to request next page of results.
        previous:
          type: string
          nullable: true
          description: URL to request previous page of results.
    ValidationResult:
      type: object
      additionalProperties: false
      nullable: 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
          nullable: false
          example:
          - 1
          - 2
          - 3
        passed:
          type: boolean
          description: Whether the validation passed or not, null if the validation was not applicable
          example: true
          nullable: 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'
    BatchCreateAnnotationsRequest:
      type: array
      items:
        $ref: '#/components/schemas/AnnotationCreate'
    ChangedValidationResults:
      type: object
      additionalProperties: true
      nullable: 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'
    BatchUpdateAnnotationsRequest:
      type: array
      items:
        $ref: '#/components/schemas/AnnotationBatchUpdate'
    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
            nullable: true
          - type: integer
            nullable: true
          - type: number
            nullable: true
          - type: boolean
            nullable: true
          - type: object
            nullable: true
            additionalProperties: true
          - type: array
            nullable: true
            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'
    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'
    dataPoint:
      type: string
      description: Data point's identifier
    BatchDeleteAnnotationsRequest:
      type: array
      description: Array of annotation IDs to be deleted
      items:
        $ref: '#/components/schemas/Annotation_properties-id'
    BatchUpdateAnnotationsResponse:
      type: array
      items:
        $ref: '#/components/schemas/Annotation'
    validationResults:
      type: array
      description: The validation results created, changed or deleted as a result of updating the annotation.
      items:
        $ref: '#/components/schemas/ChangedValidationResults'
    parent:
      type: integer
      description: The parent annotation's ID
      nullable: true
    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'
    parsed:
      oneOf:
      - type: string
        nullable: true
      - type: integer
        nullable: true
      - type: number
        nullable: true
      - type: boolean
        nullable: true
      - type: object
        nullable: true
        additionalProperties: true
      - type: array
        nullable: true
        items:
          $ref: '#/components/schemas/AnnotationCreate'
    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
            nullable: true
          - type: integer
            nullable: true
          - type: number
            nullable: true
          - type: boolean
            nullable: true
          - type: object
            nullable: true
            additionalProperties: true
          - type: array
            nullable: true
            items:
              $ref: '#/components/schemas/AnnotationCreate'
        isClientVerified:
          $ref: '#/components/schemas/isClientVerified'
        parent:
          type: integer
          description: The parent annotation's ID
          nullable: true
        validationResults:
          type: array
          description: The validation results created, changed or deleted as a result of creating the annotation.
          items:
            $ref: '#/components/schemas/ChangedValidationResults'
    raw:
      type: string
      nullable: true
      description: Raw data extracted from the before any post-processing
    Annotation_properties-id:
      type: integer
      description: Annotation's ID
      example: 1
      minimum: 1
  responses:
    DefaultError:
      description: UnexpectedError
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestError'
      x-ms-error-response: true
    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
  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).'