Affinda Usage API

openapi: 3.0.3
info:
  title: Affinda Usage API
  version: 3.0.0
  description: "Affinda Usage API \u2014 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: []
paths:
  /v3/usage:
    get:
      tags:
      - Usage
      summary: Get usage
      operationId: getUsage
      description: "Returns daily credits consumption for an organization over a date range. Optionally scope the report to\
        \ a single workspace or document type.\n`workspace` and `document_type` cannot be combined: usage data is aggregated\
        \ independently along each axis, so a per-(workspace \xD7 document type) slice is not available."
      parameters:
      - in: query
        name: organization
        required: true
        schema:
          $ref: '#/components/schemas/Organization_properties-identifier'
        description: Organization to report usage for. The caller must be an admin or owner.
      - in: query
        name: workspace
        schema:
          $ref: '#/components/schemas/identifier'
        description: Optionally scope the report to a single workspace within the organization.
      - in: query
        name: document_type
        schema:
          $ref: '#/components/schemas/properties-identifier'
        description: Optionally scope the report to a single document type within the organization.
      - in: query
        name: start
        schema:
          type: string
          format: date
        description: Inclusive start date of the report (YYYY-MM-DD). Defaults to 365 days before `end`.
      - in: query
        name: end
        schema:
          type: string
          format: date
        description: Inclusive end date of the report (YYYY-MM-DD). Defaults to today.
      responses:
        '200':
          description: Daily credits consumption for the requested scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
components:
  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).'
  schemas:
    Resume:
      allOf:
      - $ref: '#/components/schemas/Document'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/ResumeData'
      x-ms-discriminator-value: resume
    Invoice:
      allOf:
      - $ref: '#/components/schemas/Document'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/InvoiceData'
      x-ms-discriminator-value: invoice
    JobDescription:
      allOf:
      - $ref: '#/components/schemas/Document'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/JobDescriptionData'
      x-ms-discriminator-value: job-description
    ResumeRedact:
      allOf:
      - $ref: '#/components/schemas/Document'
      - type: object
        properties:
          data:
            type: object
            properties:
              redactedPdf:
                type: string
                description: URL to download the redacted resume.
      x-ms-discriminator-value: resume-redact
    DateRangeAnnotation:
      type: object
      nullable: true
      allOf:
      - $ref: '#/components/schemas/Annotation'
      - type: object
        properties:
          parsed:
            type: object
            properties:
              start:
                $ref: '#/components/schemas/DateRangeValue'
              end:
                $ref: '#/components/schemas/DateRangeValue'
    PhoneNumberAnnotation:
      type: object
      nullable: true
      allOf:
      - $ref: '#/components/schemas/Annotation'
      - type: object
        properties:
          parsed:
            type: object
            properties:
              rawText:
                type: string
                nullable: false
                example: '+61412632636'
                deprecated: true
              formattedNumber:
                type: string
                nullable: true
                example: +61 412 632 636
              countryCode:
                type: string
                nullable: true
                example: AU
              internationalCountryCode:
                type: integer
                nullable: true
                example: 61
                minimum: 1
              nationalNumber:
                type: string
                nullable: true
                example: 0412 632 636
    UrlAnnotation:
      type: object
      nullable: true
      allOf:
      - $ref: '#/components/schemas/Annotation'
      - type: object
        properties:
          parsed:
            type: object
            properties:
              url:
                type: string
                nullable: true
                example: https://2nb9s.com/hello/world?foo=bar#baz
              domain:
                type: string
                nullable: true
                example: 2nb9s.com
    identifier:
      type: string
      description: Uniquely identify a workspace.
      example: mEFayXdO
    properties-identifier:
      type: string
      description: Uniquely identify a collection.
      example: mEFayXdO
    DocumentState:
      type: string
      enum:
      - uploaded
      - review
      - validated
      - archived
      - rejected
    id:
      type: integer
      description: Uniquely identify a tag.
      example: 1
      minimum: 1
    DateRange:
      type: string
      enum:
      - today
      - yesterday
      - week
      - month
      - year
    DocumentMeta_properties-identifier:
      type: string
      description: Unique identifier for the document
    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
    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.
    FileName:
      type: string
      nullable: true
      description: Optional filename of the file
      example: Document.pdf
    ExpiryTime:
      type: string
      nullable: true
      format: date-time
      description: The date/time in ISO-8601 format when the document will be automatically deleted.  Defaults to no expiry.
    customIdentifier:
      type: string
      nullable: true
      description: Optional identifier for the document that you can set to track the document in the Affinda system.  Is
        not required to be unique.
      example: 46ab8b02-0e5b-420c-877c-8b678d46a834
    PageMeta:
      type: object
      required:
      - id
      - pageIndex
      - image
      - width
      - height
      - rotation
      properties:
        id:
          type: integer
          minimum: 1
        pageIndex:
          type: integer
          example: 0
          minimum: 0
          description: Page number within the document, starts from 0.
        image:
          type: string
          nullable: true
          example: https://affinda-api.s3.amazonaws.com/media/pages/Page.png?AWSAccessKeyId=KEY&Signature=SIG&Expires=1663302062
          description: The URL to the image of the page.
        imageTranslated:
          type: string
          nullable: true
          example: https://affinda-api.s3.amazonaws.com/media/pages/PageTranslated.png?AWSAccessKeyId=KEY&Signature=SIG&Expires=1663302062
          description: The URL to the translated image of the page.
        height:
          type: number
          example: 700
          description: Height of the page's image in px.
        width:
          type: number
          example: 500
          description: Width of the page's image in px.
        rotation:
          type: integer
          example: 90
          minimum: -360
          maximum: 360
          description: The degree of rotation applied to the page. Greater than 0 indicates clockwise rotation. Less than
            0 indicates counter-clockwise rotation.
    name:
      type: string
    Extractor_properties-identifier:
      type: string
      description: Uniquely identify an extractor.
      example: resume
    validatable:
      type: boolean
    Identifier:
      type: string
      description: A random string that uniquely identify the resource.
    ValidationRule:
      type: object
      additionalProperties: false
      nullable: false
      description: A validation rule for a collection
      required:
      - slug
      - dataPoints
      properties:
        slug:
          type: string
          description: The slug of the validation rule, in lowercase snake_case
          pattern: ^[a-z0-9_]+$
          example: supplier_name_is_alphanumeric
        dataPoints:
          type: array
          description: The data point identifier that this validation rule applies to, can be an empty list if the rule doens't
            use any data points as sources
          items:
            $ref: '#/components/schemas/Identifier'
    UserNullable:
      type: object
      nullable: true
      properties:
        id:
          type: integer
          description: Uniquely identify a user.
          example: 1
          minimum: 1
        name:
          type: string
          example: Carl Johnson
        username:
          type: string
          example: carljohnson
        email:
          type: string
          example: [email protected]
        avatar:
          type: string
          nullable: true
          description: URL of the user's avatar.
          example: https://affinda-api.s3.amazonaws.com/media/user-avatar.png?AWSAccessKeyId=KEY&Signature=SIG
    errorCode:
      type: string
      nullable: true
      example: document_conversion_failed
    errorDetail:
      type: string
      nullable: true
      example: Unable to convert word document
    Tag:
      type: object
      required:
      - id
      - name
      - workspace
      - documentCount
      properties:
        id:
          type: integer
          description: Uniquely identify a tag.
          example: 1
          minimum: 1
        name:
          type: string
        workspace:
          $ref: '#/components/schemas/identifier'
        documentCount:
          type: integer
          minimum: 0
          description: Number of documents tagged with this.
    User:
      type: object
      properties:
        id:
          type: integer
          description: Uniquely identify a user.
          example: 1
          minimum: 1
        name:
          type: string
          example: Carl Johnson
        username:
          type: string
          example: carljohnson
        email:
          type: string
          example: [email protected]
        avatar:
          type: string
          nullable: true
          description: URL of the user's avatar.
          example: https://affinda-api.s3.amazonaws.com/media/user-avatar.png?AWSAccessKeyId=KEY&Signature=SIG
    RegionBias:
      type: object
      nullable: true
      properties:
        country:
          type: string
          nullable: true
          description: A single alpha-2 country code (e.g. AU) used by google geocoding service
        countries:
          type: array
          items:
            type: string
          nullable: true
          description: A list of alpha-2 country codes used by Pelias
        squareCoordinates:
          type: array
          items:
            type: number
          nullable: true
          description: A list of coordinates used by Pelias in the shape of [min_lon, min_lat, max_lon, max_lat]
        strict:
          type: boolean
          description: 'If true, the location must be within the region, as opposed to prefering locations within the region.

            Default to false.

            '
          example: true
    DocumentMeta:
      type: object
      required:
      - identifier
      - pages
      - workspace
      properties:
        identifier:
          type: string
          description: Unique identifier for the document
        customIdentifier:
          type: string
          nullable: true
          description: Optional identifier for the document that you can set to track the document in the Affinda system.  Is
            not required to be unique.
          example: 46ab8b02-0e5b-420c-877c-8b678d46a834
        fileName:
          $ref: '#/components/schemas/FileName'
        ready:
          type: boolean
          nullable: false
          example: true
          description: If true, the document has finished processing. Particularly useful if an endpoint request specified
            wait=False, when polling use this variable to determine when to stop polling
        readyDt:
          type: string
          format: date-time
          example: '2020-12-10T01:43:32.276724Z'
          nullable: true
          description: The datetime when the document was ready
        failed:
          type: boolean
          nullable: false
          example: false
          description: If true, some exception was raised during processing. Check the 'error' field of the main return object.
        expiryTime:
          $ref: '#/components/schemas/ExpiryTime'
        language:
          type: string
          nullable: true
          example: en
          description: The document's language.
        pdf:
          type: string
          nullable: true
          example: https://affinda-api.s3.amazonaws.com/media/documents/Document.pdf?AWSAccessKeyId=KEY&Signature=SIG&Expires=1663302062
          description: The URL to the document's pdf (if the uploaded document is not already pdf, it's converted to pdf as
            part of the parsing process).
        parentDocument:
          type: object
          nullable: true
          description: If this document is part of a splitted document, this attribute points to the original document that
            this document is splitted from.
          properties:
            identifier:
              $ref: '#/components/schemas/DocumentMeta_properties-identifier'
            customIdentifier:
              $ref: '#/components/schemas/customIdentifier'
        childDocuments:
          type: array
          description: If this document has been splitted into a number of child documents, this attribute points to those
            child documents.
          items:
            type: object
            properties:
              identifier:
                $ref: '#/components/schemas/DocumentMeta_properties-identifier'
              customIdentifier:
                $ref: '#/components/schemas/customIdentifier'
        pages:
          type: array
          items:
            $ref: '#/components/schemas/PageMeta'
          description: The document's pages.
        isOcrd:
          type: boolean
        ocrConfidence:
          type: number
          nullable: true
        reviewUrl:
          type: string
          nullable: true
        documentType:
          type: string
          description: The document type's identifier.  Provide if you already know the document type.
          nullable: true
        collection:
          type: object
          nullable: true
          required:
          - identifier
          properties:
            identifier:
              $ref: '#/components/schemas/properties-identifier'
            name:
              $ref: '#/components/schemas/name'
            extractor:
              type: object
              nullable: true
              properties:
                identifier:
                  $ref: '#/components/schemas/Extractor_properties-identifier'
                name:
                  $ref: '#/components/schemas/name'
                baseExtractor:
                  type: string
                  description: Base extractor's identifier.
                  nullable: true
                validatable:
                  $ref: '#/components/schemas/validatable'
            validationRules:
              type: array
              items:
                $ref: '#/components/schemas/ValidationRule'
            autoRefreshValidationResults:
              type: boolean
              description: If True, validation results are refreshed whenever annotations are changed.
        workspace:
          type: object
          required:
          - identifier
          properties:
            identifier:
              $ref: '#/components/schemas/identifier'
            name:
              $ref: '#/components/schemas/name'
        archivedDt:
          type: string
          format: date-time
          nullable: true
        isArchived:
          type: boolean
        skipParse:
          type: boolean
        confirmedDt:
          type: string
          format: date-time
          nullable: true
        confirmedBy:
          $ref: '#/components/schemas/UserNullable'
        isConfirmed:
          type: boolean
        rejectedDt:
          type: string
          format: date-time
          nullable: true
        rejectedBy:
          $ref: '#/components/schemas/UserNullable'
        archivedBy:
          $ref: '#/components/schemas/UserNullable'
        isRejected:
          type: boolean
        createdDt:
          type: string
          format: date-time
        errorCode:
          $ref: '#/components/schemas/errorCode'
        errorDetail:
          $ref: '#/components/schemas/errorDetail'
        file:
          type: string
          nullable: true
          description: URL to view the file.
        html:
          type: string
          nullable: true
          description: URL to view the file converted to HTML.
        llmHint:
          type: string
          nullable: true
          description: Optional hint inserted into the LLM prompt when processing this document.
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        createdBy:
          $ref: '#/components/schemas/User'
        sourceEmail:
          type: string
          nullable: true
          description: If the document is created via email ingestion, this field stores the email file's URL.
        sourceEmailAddress:
          type: string
          nullable: true
          description: If the document is created via email ingestion, this field stores the email's From address.
        regionBias:
          $ref: '#/components/schemas/RegionBias'
    DocumentError:
      type: object
      additionalProperties: false
      properties:
        errorCode:
          type: string
          nullable: true
          example: document_conversion_failed
        errorDetail:
          type: string
          nullable: true
          example: Unable to convert word document
    DocumentWarning:
      type: object
      additionalProperties: false
      properties:
        warningCode:
          type: string
          nullable: true
          example: too_many_pages
        warningDetail:
          type: string
          nullable: true
          example: File exceeds maximum number of pages allowed, parsing the first 10 pages only.
    Document:
      type: object
      required:
      - meta
      - extractor
      properties:
        data:
          type: object
        extractor:
          type: string
        meta:
          $ref: '#/components/schemas/DocumentMeta'
        error:
          $ref: '#/components/schemas/DocumentError'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/DocumentWarning'
      discriminator:
        propertyName: extractor
      x-csharp-usage: input,output
    File:
      type: string
      format: binary
      description: 'File as binary data blob. Supported formats: PDF, DOC, DOCX, TXT, RTF, HTML, PNG, JPG, TIFF, ODT, XLS,
        XLSX'
    Wait:
      type: boolean
      description: If "true" (default), will return a response only after processing has completed. If "false", will return
        an empty data object which can be polled at the GET endpoint until processing is complete.
      example: true
      default: true
      nullable: false
    Language:
      type: string
      nullable: true
      description: Language code in ISO 639-1 format. Must specify zh-cn or zh-tw for Chinese.
      example: en
    RejectDuplicatesMaybeString:
      type: boolean
      description: If "true", parsing will fail when the uploaded document is duplicate of an existing document, no credits
        will be consumed. If "false", will parse the document normally whether its a duplicate or not. If not provided, will
        fallback to the workspace settings.
      example: true
      nullable: true
    DocumentCreate:
      type: object
      properties:
        file:
          $ref: '#/components/schemas/File'
        url:
          type: string
          nullable: true
          description: URL to download the document.
          example: https://api.affinda.com/static/sample_resumes/example.docx
        collection:
          $ref: '#/components/schemas/properties-identifier'
        documentType:
          type: string
          description: The document type's identifier.  Provide if you already know the document type.
          nullable: true
        workspace:
          $ref: '#/components/schemas/identifier'
        wait:
          $ref: '#/components/schemas/Wait'
        identifier:
          type: string
          description: Deprecated in favor of `customIdentifier`.
          deprecated: true
        customIdentifier:
          type: string
          description: Specify a custom identifier for the document if you need one, not required to be unique.
        fileName:
          $ref: '#/components/schemas/FileName'
        expiryTime:
          $ref: '#/components/schemas/ExpiryTime'
        language:
          $ref: '#/components/schemas/Language'
        rejectDuplicates:
          $ref: '#/components/schemas/RejectDuplicatesMaybeString'
        regionBias:
          type: string
          description: A JSON representation of the RegionBias object.
          example: '{"country": "vn"}'
        lowPriority:
          type: boolean
          description: Explicitly mark this document as low priority.
          example: true
        compact:
          type: boolean
          description: If true, the returned parse result (assuming `wait` is also true) will be a compact version of the
            full result.
          example: true
        deleteAfterParse:
          type: boolean
          description: 'If true, no data will be stored after parsing. Only compatible with requests where wait: True.'
          example: true
        enableValidationTool:
          type: boolean
          description: If true, the document will be viewable in the Affinda Validation Tool. Set to False to optimize parsing
            speed.
          example: true
        useOcr:
          type: boolean
          nullable: true
          description: If true, the document will be treated like an image, and the text will be extracted using OCR. If false,
            the document will be treated like a PDF, and the text will be extracted using the parser. If not set, we will
            determine whether to use OCR based on whether words are found in the document.
        llmHint:
          type: string
          nullable: true
          description: Optional hint inserted into the LLM prompt when processing this document.
        limitToExamples:
          type: array
          nullable: true
          description: Restrict LLM example selection to the specified document identifiers.
          items:
            type: string
        warningMessages:
          type: array
          items:
            $ref: '#/components/schemas/DocumentWarning'
    DocumentFormat:
      type: string
      enum:
      - json
      - xml
      - hr-xml
    isConfirmed:
      type: boolean
    isRejected:
      type: boolean
    isArchived:
      type: boolean
    skipParse:
      type: boolean
    DocumentUpdate:
      type: object
      properties:
        collection:
          $ref: '#/components/schemas/properties-identifier'
        workspace:
          $ref: '#/components/schemas/identifier'
        documentType:
          type: string
          description: The document type's identifier.  Provide if you already know the document type.
          nullable: true
        fileName:
          $ref: '#/components/schemas/FileName'
        expiryTime:
          $ref: '#/components/schemas/ExpiryTime'
        isConfirmed:
          $ref: '#/components/schemas/isConfirmed'
        isRejected:
          $ref: '#/components/schemas/isRejected'
        isArchived:
          $ref: '#/components/schemas/isArchived'
        skipParse:
          $ref: '#/components/schemas/skipParse'
        language:
          $ref: '#/components/schemas/Language'
        identifier:
          type: string
          description: Deprecated in favor of `customIdentifier`.
          deprecated: true
        customIdentifier:
          type: string
          description: Specify a custom identifier for the document if you need one, not required to be unique.
        llmHint:
          type: string
          nullable: true
          description: Optional hint inserted into the LLM prompt when processing this document.
        warningMessages:
          type: array
          items:
            $ref: '#/components/schemas/DocumentWarning'
    Organization_properties-identifier:
      type: string
      description: Uniquely identify an organization.
      example: mEFayXdO
    OrganizationRole:
      type: string
      enum:
      - admin
      - member
      example: admin
    PaletteColorOptions:
      type: object
      required:
      - main
      properties:
        main:
          type: string
        light:
          type: string
        dark:
          type: string
        contrastText:
          type: string
    ThemeConfig:
      type: object
      properties:
        palette:
          type: object
          properties:
            mode:
              type: string
              enum:
              - light
              - dark
            background:
              oneOf:
              - type: string
              - type: object
                properties:
                  default:
                    type: string
                  paper:
                    type: string
            text:
              type: object
              properties:
                primary:
                  type: string
                secondary:
                  type: string
                disabled:
                  type: string
            divider:
              type: string
            primary:
              $ref: '#/components/schemas/PaletteColorOptions'
            secondary:
              $ref: '#/components/schemas/PaletteColorOptions'
            success:
              $ref: '#/components/schemas/PaletteColorOptions'
            annotation:
              $ref: '#/components/schemas/PaletteColorOptions'
            error:
              $ref: '#/components/schemas/PaletteColorOptions'
            info:
              $ref: '#/components/schemas/PaletteColorOptions'
            warning:
              $ref: '#/components/schemas/PaletteColorOptions'
        typography:
          type: object
          properties:
            fontFamily:
              type: string
            fontSize:
              oneOf:
              - type: string
              - type: number
            fontWeightRegular:
              type: string
            fontWeightMedium:
              type: string
            fontWeightBold:
              type: string
        borderRadius:
          type: number
        fontUrl:
          type: string
    Organization:
      type: object
      properties:
        identifier:
          type: string
          description: Uniquely identify an organization.
          example: mEFayXdO
        name:
          type: string
          example: Grove Street King
        userRole:
          type: string
          allOf:
          - $ref: '#/components/schemas/OrganizationRole'
          nullable: true
          description: The role of the logged in user within the organization.
        avatar:
          type: string
          nullable: true
          description: URL of the organization's avatar.
          example: https://affinda-api.s3.amazonaws.com/media/org-avatar.png?AWSAccessKeyId=KEY&Signature=SIG
        resthookSignatureKey:
          type: string
          nullable: true
          description: Used to sign webhook payloads so you can verify their integrity.
          example: 465c6598bd34c0558f0ce256c43209d49fa85b0ff3e4c18b24e408b7563143ad
        isTrial:
          type: boolean
        validationToolConfig:
          type: object
          nullable: true
          description: Configuration of the embeddable validation tool.
          properties:
            theme:
              $ref: '#/components/schemas/ThemeConfig'
            hideActions:
              type: boolean
              description: Hide the confirm document button and other actions.
            hideCollection:
              type: boolean
              description: Hide the collection selector.
            hideEditPages:
              type: boolean
              description: Hide the edit pages button.
            hideExport:
              type: boolean
              description: Hide the export menu.
            hideFilename:
              type: boolean
              description: Hide the filename input.
            hideShowRawValues:
              type: boolean
              description: Hide the toggle for showing raw annotation values.
            hideReject:
              type: boolean
              description: Hide the reject document button.
            hideReparse:
              type: boolean
              description: Hide the reparse button.
            hideRunOcr:
              type: boolean
              description: Hide the run OCR button.
            hideTags:
              type: boolean
              description: Hide the tags editor.
            hideWarnings:
              type: boolean
              description: Hide the warnings panel.
            restrictDocumentSplitting:
              type: boolean
              description: Disable the page editor after a document has been split once.
            disableCurrencyFormatting:
              type: boolean
              description: Disable currency formatting of decimals values.
            disableEditDocumentMetadata:
              type: boolean
              description: Disable editing document metadata. Makes the collection selector, filename input and tags editor
                read only.
            disableManualAnnotationEditing:
              type: boolean
              description: Disable manual editing of annotation values via the validation popover.
            hideDocumentStatus:
 

# --- truncated at 32 KB (203 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/affinda/refs/heads/main/openapi/affinda-usage-api-openapi.yml