Documents

This document describes document ingestion into a Documentalist agent’s corpus: upload, status retrieval, listing, and deletion. These endpoints are reserved for DOCUMENTALIST agents and scoped to your organization via your x-api-key token (see Retrieving Your Authentication Token).

Prerequisites

• An active DIMARC account.
• An existing Documentalist agent (see Agents).
• Your authentication token x-api-key (see Retrieving Your Authentication Token)

Response Format

All responses use a common envelope:

{ "status": "success", "data": { } }

{ "status": "error", "code": "document_not_found", "error": "Document not found" }

Error codes: agent_not_found, invalid_agent_type, quota_exceeded, storage_full, invalid_request, unsupported_file_type, file_too_large, document_already_exists, document_not_found, document_synced, infected_file, antivirus_unavailable, internal_error.

An unexpected internal failure is returned as 500 internal_error in this same envelope; technical details are never returned.

Some errors include a detail field: supported (accepted extensions) for unsupported_file_type, limit/size for file_too_large, document_reference for document_already_exists, limit/current for quota_exceeded, capacity_bytes/used_bytes/incoming_bytes for storage_full.

Formats and Limits

• Accepted formats: pdf, docx, xlsx, csv, msg, eml, jpg, jpeg, png, heic (determined by the filename extension).
• Maximum size: 60 MB per file (your plan may enforce a lower limit — the effective cap is then returned in the detail of the 413 file_too_large error).
• Content is transmitted base64-encoded in the request body.
• A request body larger than 84 MB, well beyond an encoded 60 MB file, is rejected with a 413 carrying no JSON body and no code, before it is read.

Upload a Document

POST /v2/agents/{reference}/documents

curl --location 'https://api.dimarc.ai/v2/agents/01ABC.../documents' \
  --header 'x-api-key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "filename": "annual-report.pdf",
    "file": "<base64_content>",
    "path": "finance/2026"
  }'

• filename (required): file name, with its extension.
• file (required): base64-encoded file content.
• path (optional): logical classification path within the document corpus.

Response 202:

{ "status": "success", "data": { "document_reference": "01ABC...", "status": "pending" } }

Ingestion is asynchronous: the document is created with status pending, then moves to ready or error once processed. Configure the document.ingestion_completed webhook to be notified of the outcome, or retrieve the status by polling via the listing endpoint or the agent’s document list.

Possible errors: 403 quota_exceeded (agent’s document quota reached), 403 storage_full (organization storage capacity reached: 2 GB per seat (2 GB minimum), plus 10 GB per pack and any volume included in your contract; free up space or add a pack from your settings), 404 agent_not_found, 409 document_already_exists (same file — name and path — already present; see Replacing a Document), 413 file_too_large, 422 invalid_agent_type (non-Documentalist agent), 422 invalid_request (invalid base64 or path — leading/trailing slash, empty segment, length), 422 unsupported_file_type, 422 infected_file (file flagged as infected by the antivirus scan), 500 internal_error (unexpected internal failure: the document may remain in error, delete it before uploading it again), 503 antivirus_unavailable.

List Documents

GET /v2/agents/{reference}/documents

curl 'https://api.dimarc.ai/v2/agents/01ABC.../documents' \
  --header 'x-api-key: <your_api_key>'

Response:

{
  "status": "success",
  "data": [
    {
      "reference": "01ABC...",
      "name": "annual-report.pdf",
      "path": "finance/2026",
      "status": "ready",
      "size": 245678,
      "mime": "application/pdf",
      "error_reason": null,
      "created_at": "2026-07-18T09:30:00.000Z",
      "updated_at": "2026-07-18T09:31:12.000Z"
    }
  ]
}

status is pending, ready, or error. Use this endpoint to track an ongoing ingestion (polling). On error, error_reason carries the reason when the file was rejected (unsupported format, empty file); it stays null for an internal failure.

Possible errors: 404 agent_not_found, 422 invalid_agent_type.

Delete a Document

DELETE /v2/agents/{reference}/documents/{documentReference}

curl --location --request DELETE 'https://api.dimarc.ai/v2/agents/01ABC.../documents/01XYZ...' \
  --header 'x-api-key: <your_api_key>'

Response 200:

{ "status": "success", "data": { "reference": "01XYZ..." } }

Deletes the stored file and its search index.

Possible errors: 404 agent_not_found, 404 document_not_found, 409 document_synced (document synchronized from a drive folder: remove it from the source folder), 422 invalid_agent_type.

Replacing a Document

There is no in-place update: a document is identified by its filename and path. To replace an existing document, delete it first (DELETE) then re-upload it (POST). Uploading a document with the same name and path as an existing one returns 409 document_already_exists without modifying it.

Retrying a Failed Document

A document that reaches status error is not automatically retried by the server. To retry processing, delete it and re-upload it.

Support and Assistance

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