DIMARC API - Documentation

⚠️ v2 Migration (breaking changes)

What changes in API responses — extractor, documentalist, token, authentication

🔐 Authentication

Retrieving and using your authentication token

🚀 Agents

Creating, configuring, and deleting your agents through the API

📄 Documents

Ingesting, listing, and deleting a Documentalist agent’s documents

🔍 Documentalist Agent

Communication with your Documentalist agents via the API

📄 Extractor Agent

Extracting structured data from documents

🗂️ Classification

Splitting and classifying a batch of pages by category

🪝 Webhooks

Configure signed webhooks for ingestion and extraction events

⭐ Usage

View your organization’s subscription, quotas, and consumption

📚 Error codes

The full set of machine codes the API can return

v2 Migration

• Summary of changes
• Extractor
• Documentalist
• Token
• Authentication rejections
• Error codes

Authentication

Tip

All API calls require authentication with an organization API key (dk_…).

• Prerequisites
• Create an API key
• Retrieving the token
• Using the token
• Security best practices
• Troubleshooting

Documentalist Agent

• Prerequisites
• Retrieving an agent’s ID
• Communication with the agent
• Managing history
• Limitations and considerations

Extractor Agent

• Prerequisites
• Two extraction approaches
• Processing modes
• Synchronous extraction
• Error codes
• Asynchronous extraction
• Parameters structure
• Limitations and considerations

Webhooks

• Events
• Event Envelope
• Configuring a Webhook
• Signature Verification
• Retry Policy

Usage

• Retrieve Usage
• period vs current_period_end

Error codes

Every error from the /v2 endpoints comes back in the same envelope:

{ "status": "error", "code": "agent_not_found", "error": "Agent not found", "detail": { } }

code is a stable machine identifier, error a human-readable message that can change without notice, detail an optional object. The OpenAI-compatible API has its own error format — see OpenAI-compatible API.

The full set of codes the API can return:

Code	Meaning
agent_not_found	Agent not found, wrong type, private, or invalid organization
thread_not_found	The thread_id provided does not belong to this agent
infected_file	File rejected by the antivirus
antivirus_unavailable	Antivirus service unavailable
agent_unavailable	Agent temporarily unavailable (processing queue)
agent_timeout	Agent response timed out
extraction_failed	Processing failed (extraction or knowledge response)
no_data_extracted	The document holds no usable data
classification_failed	Classification processing failed
invalid_request	Invalid request (body or URL validation)
internal_error	Unexpected internal error
unsupported_file_type	Unsupported file type
file_too_large	File above the maximum allowed size
document_already_exists	Document already exists
document_not_found	Document not found
document_synced	Document synchronized from a drive folder
quota_exceeded	Usage quota exceeded
spending_limit_reached	Organization spending limit reached
rate_limit_exceeded	Rate exceeded; Retry-After carries the seconds until the next window
concurrent_limit_exceeded	Too many concurrent jobs for the organization; Retry-After carries the seconds to wait before retrying
queue_saturated	Processing engine saturated; Retry-After carries the seconds to wait before retrying
turn_not_found	GET /v2/turns/{turn_id}: identifier unknown, expired, or from another organization
maintenance	Service temporarily closed to new requests (503); reading results (GET /v2/turns/{turn_id}) stays available, retry in a few minutes
invalid_agent_type	Invalid agent type for this endpoint
invalid_config	Invalid agent configuration
webhook_not_found	No webhook configured for this event
organization_not_found	Organization not found
unauthorized	Missing or invalid authentication
invalid_client	Invalid client credentials (/v2/token)
forbidden	API access disabled for the organization

Tip

Drive your error handling off code, never off error (a human-readable message, subject to change) nor off the HTTP status alone — several codes can share the same status (e.g. agent_not_found and thread_not_found are both 404).

Support and Assistance

For any questions regarding the DIMARC API, contact our technical support team at contact@dimarc.fr