Agents

Ce document décrit la gestion des agents par l’API : création, consultation, mise à jour et suppression. Tous les endpoints sont scopés à votre organisation via votre token x-api-key (voir Récupération de votre Token d’Authentification).

Les agents créés par l’API appartiennent à votre organisation (pas à un utilisateur) et sont visibles dans l’application par tous ses membres.

Prérequis

• Un compte DIMARC actif.
• Être administrateur de votre organisation.
• Votre token d’authentification x-api-key (voir Récupération de votre Token d’Authentification)

Format de réponse

Toutes les réponses utilisent une enveloppe commune :

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

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

Codes d’erreur : agent_not_found, invalid_agent_type, invalid_config, quota_exceeded, invalid_request, internal_error.

Certaines erreurs incluent un champ detail avec des informations supplémentaires : issues (détail de validation Zod) pour invalid_config, limit/current pour quota_exceeded.

Lister les agents

GET /v2/agents

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

Réponse : data est une liste d’agents { reference, name, description, type, created_at, updated_at }. Seuls les agents dont la visibilité n’est pas privée (organisation ou groupe) sont renvoyés.

Créer un 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": "Extracteur factures",
    "type": "EXTRACTOR",
    "configuration": {
      "params": [
        {
          "name": "montant_ttc",
          "format": "number",
          "description": "Montant TTC de la facture",
          "items": []
        }
      ]
    }
  }'

• type : EXTRACTOR ou DOCUMENTALIST. Les agents Assistant personnel (PERSONAL) ne sont pas gérables via l’API.
• configuration (optionnel) :
  • pour un extracteur : { "params": [...] }. Chaque paramètre suit la même structure que pour l’Extracteur global : name, format (text, number, boolean ou list), description, et items — un tableau requis sur chaque paramètre (sous-champs pour format: "list", tableau vide sinon).
  • pour un documentaliste : { "consignes": [...], "sourceVisibility": true } (tous les champs sont optionnels). Le champ domains reste accepté pour rétrocompatibilité mais est obsolète : il est stocké sans être exploité par l’agent.

Réponse 201 : l’agent créé, avec sa configuration.

Erreurs possibles : 403 quota_exceeded (quota d’agents de l’organisation atteint), 404 agent_not_found (organisation introuvable), 422 invalid_config.

Consulter un agent

GET /v2/agents/{reference} — détail incluant la configuration (absente pour les agents PERSONAL).

Mettre à jour un agent

PATCH /v2/agents/{reference} — corps partiel : name, description (peut être vidé en envoyant null), configuration (mêmes validations qu’à la création).

Pour un extracteur, configuration.params remplace entièrement la liste existante. Pour un documentaliste, les champs fournis dans configuration sont fusionnés avec la configuration existante.

Erreurs possibles : 404 agent_not_found, 422 invalid_config ou 422 invalid_agent_type.

Supprimer un agent

DELETE /v2/agents/{reference} — supprime l’agent, ses documents (fichiers et index de recherche) et archive ses conversations.

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

La suppression des documents et l’archivage des conversations sont best-effort : si une de ces étapes échoue mais que l’agent est bien supprimé, la réponse reste 200 avec le détail de l’échec dans warnings. Si la suppression de l’agent lui-même échoue, la réponse est 500 internal_error.

Erreurs possibles : 404 agent_not_found, 422 invalid_agent_type (agent PERSONAL), 500 internal_error.

Support et assistance

Pour toute question concernant l’API Agents, contactez notre équipe de support à l’adresse contact@dimarc.fr