Agents

This document describes agent management through the API: creation, retrieval, update, and deletion. All endpoints are scoped to your organization via your x-api-key token (see Retrieving Your Authentication Token).

Agents created through the API belong to your organization (not to a user) and are visible in the application to all its members.

Prerequisites

• An active DIMARC account.
• Administrator status in your organization.
• 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": "agent_not_found", "error": "Agent not found" }

Error codes: agent_not_found, invalid_agent_type, invalid_config, quota_exceeded, invalid_request, internal_error.

Some errors include a detail field with additional information: issues (Zod validation detail) for invalid_config, limit/current for quota_exceeded.

List Agents

GET /v2/agents

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

Response: data is a list of agents { reference, name, description, type, created_at, updated_at }. Only agents whose visibility is not private (organization or group) are returned.

Create an Agent

POST /v2/agents

curl --location 'https://api.dimarc.ai/v2/agents' \
  --header 'x-api-key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Invoice extractor",
    "type": "EXTRACTOR",
    "configuration": {
      "params": [
        {
          "name": "total_amount",
          "format": "number",
          "description": "Invoice total including tax",
          "items": []
        }
      ]
    }
  }'

• type: EXTRACTOR or DOCUMENTALIST. Personal assistant agents (PERSONAL) cannot be managed through the API.
• configuration (optional):
  • for an extractor: { "params": [...] }. Each parameter follows the same structure as for the Global Extractor: name, format (text, number, boolean, or list), description, and items — a required array on every parameter (sub-fields for format: "list", an empty array otherwise).
  • for a documentalist: { "consignes": [...], "sourceVisibility": true } (all fields are optional). The domains field is still accepted for backward compatibility but is deprecated: it is stored without being used by the agent.

Response 201: the created agent, with its configuration.

Possible errors: 403 quota_exceeded (organization’s agent quota reached), 404 agent_not_found (organization not found), 422 invalid_config.

Retrieve an Agent

GET /v2/agents/{reference} — detail including the configuration (absent for PERSONAL agents).

Update an Agent

PATCH /v2/agents/{reference} — partial body: name, description (can be cleared by sending null), configuration (same validations as on creation).

For an extractor, configuration.params entirely replaces the existing list. For a documentalist, the fields provided in configuration are merged with the existing configuration.

Possible errors: 404 agent_not_found, 422 invalid_config, or 422 invalid_agent_type.

Delete an Agent

DELETE /v2/agents/{reference} — deletes the agent, its documents (files and search index), and archives its conversations.

{ "status": "success", "data": { "reference": "01ABC…", "warnings": [] } }

Document deletion and conversation archiving are best-effort: if one of these steps fails but the agent itself is deleted, the response remains 200 with the failure detail in warnings. If deleting the agent itself fails, the response is 500 internal_error.

Possible errors: 404 agent_not_found, 422 invalid_agent_type (PERSONAL agent), 500 internal_error.

Support and assistance

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