Manage document type definitions — the model configuration governing how a specific document category (invoice, resume, custom contract) is parsed. Each document type exposes a JSON Schema and optional Pydantic model representation. Document types are configured in the dashboard or natural-language workflow builder and reused across workspaces and collections.
openapi: 3.0.3
info:
title: Affinda Annotations Add x-hidden to endpoints Document Types 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: Document Types
paths:
/v3/document_types:
get:
tags:
- Document Types
summary: List document types
description: Returns a list of document types that the user has access to.
operationId: getDocumentTypes
parameters:
- name: organization
in: query
description: Filter by organization identifier
required: false
schema:
type: string
- name: workspace
in: query
description: Filter by workspace identifier
required: false
schema:
type: string
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DocumentType'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
post:
tags:
- Document Types
summary: Create a document type
description: Create a new document type in the specified organization.
operationId: createDocumentType
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentTypeCreate'
responses:
'201':
description: Document type created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentType'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
description: Forbidden - User doesn't have permission to create document types in this organization
default:
$ref: '#/components/responses/DefaultError'
/v3/document_types/{identifier}:
get:
tags:
- Document Types
summary: Get a document type
description: Returns the details of a specific document type.
operationId: getDocumentType
parameters:
- in: path
required: true
name: identifier
description: Document type identifier
schema:
type: string
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentType'
'401':
$ref: '#/components/responses/401Error'
'404':
description: Document type not found
default:
$ref: '#/components/responses/DefaultError'
patch:
tags:
- Document Types
summary: Update a document type
description: Update an existing document type.
operationId: updateDocumentType
parameters:
- in: path
required: true
name: identifier
description: Document type identifier
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentTypeUpdate'
responses:
'200':
description: Document type updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentType'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
description: Forbidden - User doesn't have permission to update this document type
'404':
description: Document type not found
default:
$ref: '#/components/responses/DefaultError'
delete:
tags:
- Document Types
summary: Delete a document type
description: Delete a document type.
operationId: deleteDocumentType
parameters:
- in: path
required: true
name: identifier
description: Document type identifier
schema:
type: string
responses:
'204':
$ref: '#/components/responses/204NoContent'
'401':
$ref: '#/components/responses/401Error'
'403':
description: Forbidden - User doesn't have permission to delete this document type
'404':
description: Document type not found
default:
$ref: '#/components/responses/DefaultError'
/v3/document_types/{identifier}/json_schema:
get:
tags:
- Document Types
summary: Generate JSON schema from a document type
operationId: jsonSchemaFromDocumentType
description: Generate JSON schema from a document type.
parameters:
- in: path
required: true
name: identifier
description: Document type's identifier
schema:
$ref: '#/components/schemas/DocumentType_properties-identifier'
- in: query
name: title
description: Title for the JSON schema
schema:
type: string
responses:
'200':
description: JSON schema for the document type.
content:
application/json:
schema:
type: object
additionalProperties: true
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
/v3/document_types/{identifier}/pydantic_models:
get:
tags:
- Document Types
summary: Generate Pydantic models from a document type
operationId: pydanticModelsFromDocumentType
description: Generate Pydantic models from a document type.
parameters:
- in: path
required: true
name: identifier
description: Document type's identifier
schema:
$ref: '#/components/schemas/DocumentType_properties-identifier'
- in: query
name: model_name
description: Name for the Pydantic model
schema:
type: string
responses:
'200':
description: Pydantic models for the document type.
content:
application/json:
schema:
$ref: '#/components/schemas/PydanticModelsResponse'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
components:
schemas:
DocumentTypeUpdate:
type: object
properties:
name:
type: string
description: The new name of the document type.
description:
type: string
nullable: true
description: A new description of the document type.
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
DocumentTypeCreate:
type: object
required:
- name
- organization
properties:
name:
type: string
description: The name of the document type.
description:
type: string
nullable: true
description: A description of the document type.
organization:
type: string
description: The identifier of the organization this document type belongs to.
DocumentType_properties-identifier:
type: string
description: Uniquely identify a document type.
example: mEFayXdO
PydanticModelsResponse:
type: object
required:
- code
properties:
code:
type: string
description: Pydantic model code
DocumentType:
type: object
required:
- identifier
- name
- organization
properties:
identifier:
type: string
description: Uniquely identify a document type.
example: mEFayXdO
name:
type: string
description: The name of the document type.
description:
type: string
nullable: true
description: A description of the document type.
ingest_email:
type: string
description: The email address that can be used to email documents directly to this document type.
organization:
type: string
description: The identifier of the organization this document type belongs to.
responses:
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
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
204NoContent:
description: Delete successful, no content returned
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).'