> ## Documentation Index
> Fetch the complete documentation index at: https://api.aodocs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Extract Metadata
> Extract metadata from files
## OpenAPI
````yaml https://document-assistant.us.aodocs.app/openapi.json post /assistant/api/v1/tenants/{tenant}/metadata:extract
openapi: 3.1.0
info:
title: Document Assistant API
description: |
The Document Assistant API enables developers to integrate document-based assistant
functionalities into their applications using AODocs.
The first step is to enable AIDA (AODocs Intelligent Document Assistant) in your tenant.
The support team will provide you with the necessary information on how to get started.
The second step is to enable AIDA on libraries. You need to be an administrator of the
library to do this.
AIDA can answer questions only from those documents that are in an AIDA enabled
library.
We create a vector store index for these documents. This can take some time. The get
library API provides the status of the indexation and an estimate of the time
remaining.
The content of the index is automatically kept up-to-date near real time with the
content changes.
The third step is to ask questions based on the AODocs documents.
AIDA automatically filters the results based on the user's permissions.
Authentication: All API endpoints require a valid OAuth2 token in the
Authorization header. Ensure the client ID of the OAuth2 token is whitelisted in AODocs.
version: 1.1.0
servers:
- url: https://document-assistant.us.aodocs.app
description: Production US
- url: https://document-assistant.eu.aodocs.app
description: Production EU
security: []
paths:
/assistant/api/v1/tenants/{tenant}/metadata:extract:
post:
tags:
- metadata
summary: Extract Metadata
description: Extract metadata from files
operationId: extract_metadata_assistant_api_v1_tenants__tenant__metadata_extract_post
parameters:
- name: tenant
in: path
required: true
schema:
anyOf:
- type: string
- type: 'null'
description: The domain of the customer
examples:
- example.com
title: Tenant
description: The domain of the customer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataExtractRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ExtendedExtractedMetadataList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
MetadataExtractRequest:
properties:
llm_provider:
anyOf:
- $ref: '#/components/schemas/LlmProvider'
- type: 'null'
description: >-
The LLM provider to use. If not provided, the default provider will
be used.
llm_model_prefix:
anyOf:
- type: string
- type: 'null'
title: Llm Model Prefix
description: >-
The prefix of the LLM model name to use. If not provided, the
default model will be used.
examples:
- gemini-2.5-pro
- gemini-2.5-pro-preview-05-06
- gpt-4.1
document_id:
type: string
title: Document Id
description: The document ID of the files
attachment_filters:
anyOf:
- items:
$ref: '#/components/schemas/AttachmentFilter'
type: array
- type: 'null'
title: Attachment Filters
description: |-
The attachments to extract metadata from.
If provided then only the attachments matching one of the rules are used.
If not provided then all attachments will be extracted.
Deprecated: use sources with an attachments entry instead.
deprecated: true
sources:
anyOf:
- items:
oneOf:
- $ref: '#/components/schemas/DescriptionExtractionSource'
- $ref: '#/components/schemas/AttachmentsExtractionSource'
discriminator:
propertyName: type
mapping:
attachments:
$ref: '#/components/schemas/AttachmentsExtractionSource'
description:
$ref: '#/components/schemas/DescriptionExtractionSource'
type: array
minItems: 1
- type: 'null'
title: Sources
description: |-
The ordered document content sources to extract metadata from.
If omitted, attachment-only extraction is used for backward compatibility.
Description sources are opt-in.
instruction:
anyOf:
- type: string
- type: 'null'
title: Instruction
description: The prompt extension for the metadata extraction
provide_location:
type: boolean
title: Provide Location
description: >-
Whether to calculate and return page locations (bounding boxes) for
the quote supporting each extracted field. Quotes are matched
against textual and scanned PDF attachments plus PNG, JPEG, and WebP
images without changing extracted values. Unsupported attachment
types and quotes that do not occur verbatim after normalization do
not produce boxes.
default: false
fields:
anyOf:
- items:
$ref: '#/components/schemas/FieldSpec'
type: array
- items:
type: string
type: array
- type: 'null'
title: Fields
description: >-
Specification which metadata to extract and how. If not provided,
all fields will be extracted.
example_documents:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Example Documents
description: >-
A list of example documents to use for metadata extraction. If
provided, the LLM will use these documents to better understand the
context and provide more accurate extractions.
registries:
anyOf:
- items:
$ref: '#/components/schemas/Registry'
type: array
- type: 'null'
title: Registries
description: >-
A list of metadata registries to use for metadata extraction. If
provided, the LLM will use these registries to better understand the
context and provide more accurate extractions.
type: object
required:
- document_id
title: MetadataExtractRequest
ExtendedExtractedMetadataList:
properties:
values:
items:
$ref: '#/components/schemas/ExtendedExtractedMetadata'
type: array
title: Values
registry_matches:
anyOf:
- items:
$ref: '#/components/schemas/RegistryMatch'
type: array
- type: 'null'
title: Registry Matches
description: >-
Information about the matched registry entries and the strength of
the match
type: object
required:
- values
title: ExtendedExtractedMetadataList
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
LlmProvider:
type: string
enum:
- OpenAI
- Google
- Altirnao
- MistralAI
- Anthropic
title: LlmProvider
AttachmentFilter:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: The name of the attachment to match (it can be a regular expression)
id:
anyOf:
- type: string
- type: 'null'
title: Id
description: The id of the matched attachment
mime_type:
anyOf:
- type: string
- type: 'null'
title: Mime Type
description: The mimetype of the matched attachment
type: object
title: AttachmentFilter
description: Match an attachment by identifier, MIME type, or name expression.
DescriptionExtractionSource:
properties:
type:
type: string
const: description
title: Type
default: description
type: object
title: DescriptionExtractionSource
AttachmentsExtractionSource:
properties:
type:
type: string
const: attachments
title: Type
default: attachments
include:
anyOf:
- items:
$ref: '#/components/schemas/AttachmentFilter'
type: array
- type: 'null'
title: Include
description: >-
Attachment filters to include. If omitted, all attachments are
included. If empty, no attachments are included.
exclude:
anyOf:
- items:
$ref: '#/components/schemas/AttachmentFilter'
type: array
- type: 'null'
title: Exclude
description: >-
Attachment filters to exclude after applying include filters.
Exclusion takes precedence over inclusion.
type: object
title: AttachmentsExtractionSource
FieldSpec:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: The name of the metadata field. Either the name or id is mandatory
id:
anyOf:
- type: string
- type: 'null'
title: Id
description: The id of the metadata field. Either the name or id is mandatory
instruction:
anyOf:
- type: string
maxLength: 1024
- type: 'null'
title: Instruction
description: Custom instruction for extracting this field
barcode:
type: boolean
title: Barcode
description: >-
Extract decoded barcode content and locations without using the LLM.
Supported only for STRING and TEXT fields.
default: false
integer_decimal_handling:
$ref: '#/components/schemas/IntegerDecimalHandling'
description: >-
How to coerce a decimal value the LLM returns for this integer-typed
field: `truncate` drops the fractional part (3.7 → 3), `round`
rounds to the nearest integer (3.5 → 4, 3.4 → 3), `roundup` always
rounds up toward positive infinity (3.2 → 4), `error` raises an
extraction error (default — current behavior). Applies only to
integer fields; ignored otherwise.
default: error
table_search:
anyOf:
- $ref: '#/components/schemas/TableSearchConfig'
- type: 'null'
description: >-
Optional request-scoped table-search configuration used to validate
and canonicalize STRING, CATEGORY, REFERENCE_CATALOG, or TABLE
values. Complete low-cardinality enum values remain available to the
extraction model; incomplete or high-cardinality enums are extracted
as plain text.
type: object
title: FieldSpec
Registry:
properties:
name:
type: string
title: Name
description: >-
The name of the metadata registry. This is used to identify the
registry in the request.
library_id:
type: string
title: Library Id
description: >-
The library ID that contains the metadata registry that should be
used for metadata extraction.
document_class_id:
type: string
title: Document Class Id
description: >-
The document class ID that contains the metadata registry that
should be used for metadata extraction.
match_mode:
$ref: '#/components/schemas/MatchMode'
description: >-
Specifies whether all key fields must match (ALL) or if any single
key field match is sufficient (ANY) to consider a registry entry as
a potential match.
default: ALL
field_mappings:
items:
$ref: '#/components/schemas/FieldMapping'
type: array
title: Field Mappings
description: |-
Mapping between the extracted fields and the registry
There should be at least one key field in this mapping.
type: object
required:
- name
- library_id
- document_class_id
- field_mappings
title: Registry
ExtendedExtractedMetadata:
properties:
id:
anyOf:
- type: string
- type: 'null'
title: Id
description: The id of the field
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: The name of the field
type:
anyOf:
- $ref: '#/components/schemas/FieldType'
- type: 'null'
description: The type of the field
quote:
anyOf:
- type: string
- type: 'null'
title: Quote
description: >-
A sentence quoted from text that proves the extracted value. At
least 10 words.
bounding_boxes:
anyOf:
- items:
$ref: '#/components/schemas/BoundingBox'
type: array
- type: 'null'
title: Bounding Boxes
description: >-
Locations of decoded values or quoted evidence in attachments, in
full-page normalized coordinates.
confidence:
anyOf:
- $ref: '#/components/schemas/ConfidenceLevel'
- type: 'null'
description: Confidence in the correcteness of the extraction
value:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Value
description: Human readable format of the extracted field value.
category_value:
anyOf:
- items:
$ref: '#/components/schemas/CategoryHierarchy'
type: array
- type: 'null'
title: Category Value
description: The extracted category value if the field type is category
reference_catalog_value:
anyOf:
- items:
$ref: '#/components/schemas/ReferenceCatalogValue'
type: array
- type: 'null'
title: Reference Catalog Value
description: >-
The extracted reference catalog value if the field type is reference
catalog
person_value:
anyOf:
- items:
$ref: '#/components/schemas/Person'
type: array
- type: 'null'
title: Person Value
description: The extracted person value if the field type is person
table_value:
anyOf:
- items:
$ref: '#/components/schemas/TableRow'
type: array
- type: 'null'
title: Table Value
description: The extracted table rows if the field type is table
error:
anyOf:
- type: string
- type: 'null'
title: Error
description: The error message if the extraction failed. Otherwise None.
note:
anyOf:
- type: string
- type: 'null'
title: Note
description: Any additional notes or comments about the extraction.
type: object
title: ExtendedExtractedMetadata
RegistryMatch:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: The name of the registry
document_id:
anyOf:
- type: string
- type: 'null'
title: Document Id
description: The id of the document in the registry
key_matches:
anyOf:
- items:
$ref: '#/components/schemas/KeyMatch'
type: array
- type: 'null'
title: Key Matches
description: >-
List of key matches between the extracted values and the registry
values
multiple_matches:
type: boolean
title: Multiple Matches
description: >-
Whether there are multiple registry entries that match the extracted
values
default: false
type: object
title: RegistryMatch
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
IntegerDecimalHandling:
type: string
enum:
- truncate
- round
- roundup
- error
title: IntegerDecimalHandling
TableSearchConfig:
properties:
dataset_id:
type: string
minLength: 1
title: Dataset Id
description: Tenant-scoped table-search dataset ID.
input_columns:
anyOf:
- items:
type: string
type: array
minItems: 1
- type: 'null'
title: Input Columns
description: >-
Dataset filter columns. Wrap a single STRING filter in a one-item
list.
output_columns:
anyOf:
- items:
$ref: '#/components/schemas/TableSearchOutputColumn'
type: array
minItems: 1
- type: 'null'
title: Output Columns
description: >-
Dataset output columns. Wrap a single STRING output in a one-item
list.
type: object
required:
- dataset_id
title: TableSearchConfig
MatchMode:
type: string
enum:
- ALL
- ANY
title: MatchMode
FieldMapping:
properties:
extracted_field:
type: string
title: Extracted Field
description: The id of the field in the extracted metadata
registry_field:
type: string
title: Registry Field
description: The id of the field in the metadata registry
key_field:
type: boolean
title: Key Field
description: >-
If true, the field is used to match the document to the metadata
registry.
We need at least one key field to match the document to the metadata
registry.
default: false
optional_key:
type: boolean
title: Optional Key
description: >-
If True, this key field is optional—if it's missing in the extracted
data, the match can still succeed as long as other key fields are
present and match.
default: false
similarity_threshold:
type: number
maximum: 1
minimum: 0
title: Similarity Threshold
description: >-
For key fields only: how closely the extracted and registry values
need to match (0.0 = no similarity, 1.0 = perfect match). If more
than one record matches, the one with the highest total similarity
across all key fields will be chosen.
default: 1
type: object
required:
- extracted_field
- registry_field
title: FieldMapping
FieldType:
type: string
enum:
- STRING
- TEXT
- CATEGORY
- DATE
- DATETIME
- TIME
- INTEGER
- DECIMAL
- PERSON
- BOOLEAN
- URL
- REFERENCE_CATALOG
- TABLE
title: FieldType
BoundingBox:
properties:
attachment_id:
type: string
title: Attachment Id
description: ID of the attachment containing the box
page:
type: integer
minimum: 1
title: Page
description: 1-based page number
x:
type: number
maximum: 1
minimum: 0
title: X
'y':
type: number
maximum: 1
minimum: 0
title: 'Y'
width:
type: number
maximum: 1
exclusiveMinimum: 0
title: Width
height:
type: number
maximum: 1
exclusiveMinimum: 0
title: Height
type: object
required:
- attachment_id
- page
- x
- 'y'
- width
- height
title: BoundingBox
description: >-
A rectangle in the full attachment page or image viewport.
Coordinates are normalized fractions in the range 0.0-1.0 with a
top-left
origin. PDF coordinates refer to the complete rotated page before
whitespace
trimming or tiling; standalone images use their EXIF-normalized
orientation.
ConfidenceLevel:
type: string
enum:
- low
- medium
- high
title: ConfidenceLevel
CategoryHierarchy:
properties:
hierarchy:
items:
$ref: '#/components/schemas/CategoryValue'
type: array
title: Hierarchy
description: >-
The full hierarchy of the value starting from the root. If the value
is not hierarchical then just a single value.
type: object
required:
- hierarchy
title: CategoryHierarchy
ReferenceCatalogValue:
properties:
id:
type: string
title: Id
description: The id of the value
name:
type: string
title: Name
description: The name of the value
type: object
required:
- id
- name
title: ReferenceCatalogValue
Person:
properties:
email:
anyOf:
- type: string
- type: 'null'
title: Email
description: The email of the person
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: The name of the person
type: object
title: Person
TableRow:
properties:
columns:
additionalProperties:
$ref: '#/components/schemas/ExtendedExtractedMetadata'
type: object
title: Columns
description: Column values for this row, keyed by column name
type: object
required:
- columns
title: TableRow
description: Represents a single row in a table field.
KeyMatch:
properties:
extracted_field_name:
type: string
title: Extracted Field Name
description: The name of the extracted field that matched the registry value
extracted_field_id:
type: string
title: Extracted Field Id
description: The id of the extracted field that matched the registry value
extracted_value:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Extracted Value
description: The value extracted from the document
registry_value:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Registry Value
description: The value matched in the registry
similarity:
type: number
title: Similarity
description: >-
How similar the extracted value is to the registry value (between
0.0 and 1.0). 1.0 means perfect match, 0.0 means no similarity.
type: object
required:
- extracted_field_name
- extracted_field_id
- extracted_value
- registry_value
- similarity
title: KeyMatch
TableSearchOutputColumn:
properties:
name:
type: string
minLength: 1
title: Name
description: >-
Dataset output column. For TABLE fields this must exactly match the
metadata table-column name.
id_column:
anyOf:
- type: string
minLength: 1
- type: 'null'
title: Id Column
description: >-
Companion dataset output column containing the category or reference
catalog value ID. It is not exposed as a separate extracted column.
type: object
required:
- name
title: TableSearchOutputColumn
CategoryValue:
properties:
id:
type: string
title: Id
description: The id of the value
name:
type: string
title: Name
description: The name of the value
type: object
required:
- id
- name
title: CategoryValue
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````