API du validateur BPMN

Envoyez un fichier BPMN 2.0 en XML et recevez un rapport JSON : erreurs, avertissements et informations, avec la règle concernée et sa position dans le fichier. L'API est gratuite et ne demande ni compte ni clé. Elle utilise le même moteur que le validateur BPMN en ligne de LucidFlow. Le XML est vérifié en mémoire et seul le rapport est renvoyé : le code de l'API n'enregistre pas le fichier.

Une commande

Remplacez process.bpmn par votre fichier :

curl -X POST https://lucidflow.ai/api/v1/bpmn/validate \
  -H "Content-Type: application/xml" \
  --data-binary @process.bpmn

Requête

Un point d'accès, une méthode. L'API prend le contenu du fichier, pas un lien vers le fichier.

Un petit fichier à enregistrer sous le nom process.bpmn pour essayer la commande ci-dessus. Son processus n'a pas d'événement de fin, donc le rapport ci-dessous montre un avertissement :

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
             id="defs" targetNamespace="http://example.com/bpmn">
  <process id="order" name="Order handling" isExecutable="true">
    <startEvent id="start"/>
    <task id="review" name="Review order"/>
    <sequenceFlow id="f1" sourceRef="start" targetRef="review"/>
  </process>
</definitions>

# Same call with a JSON body
curl -X POST https://lucidflow.ai/api/v1/bpmn/validate \
  -H "Content-Type: application/json" \
  -d '{"xml": "<definitions ...>...</definitions>}'

Réponse

Une requête valide reçoit 200 avec un rapport JSON. Un fichier qui n'est pas du XML bien formé, ou pas du BPMN, n'est pas une erreur HTTP : la réponse est quand même 200, avec valid à false et les problèmes listés dans errors.

Rapport abrégé pour le fichier d'exemple ci-dessus : seul le premier avertissement est listé, le second avertissement et les informations sont omis. Les listes et les compteurs dépendent de votre fichier.

{
  "version": 1,
  "generator": { "name": "...", "version": "...", "url": "..." },
  "valid": true,
  "summary": { "errors": 0, "warnings": 2, "info": 3 },
  "stats": {
    "processCount": 1,
    "taskCount": 1,
    "gatewayCount": 0,
    "eventCount": 1,
    "flowCount": 1,
    "laneCount": 0,
    "taskBreakdown": { "topLevel": 1, "nested": 0 }
  },
  "errors": [],
  "warnings": [
    {
      "severity": "warning",
      "rule": "noEndEvent",
      "message": "Process \"order\" has no end event",
      "location": { "line": 4, "column": 12 }
    }
  ],
  "info": [],
  "lucidflow": {
    "message": "...",
    "signup_url": "...",
    "tool_url": "..."
  }
}

Les messages et les noms de règles sont en anglais. Les règles sont listées dans la référence des règles.

Erreurs

Quand la requête elle-même est refusée, le corps est un objet JSON avec un code, un message et un lien vers la référence des règles :

Exemple de requête refusée :

{
  "error": {
    "code": "payload_too_large",
    "message": "The BPMN XML is larger than 50 KB.",
    "docs_url": "https://lucidflow.ai/docs/validator-rules"
  }
}

Limites

Les agents hébergés dans le cloud partagent souvent une même adresse IP et peuvent donc atteindre la limite de débit plus tôt. Les compteurs sont partagés entre les serveurs ; si le stockage partagé est indisponible, chaque serveur compte seul et les limites s'appliquent par serveur. N'envoyez pas de document confidentiel : le XML est traité sur les serveurs de LucidFlow.

L'utiliser depuis un assistant IA

L'API est un simple point d'accès HTTP. Voici comment la donner à Claude ou à ChatGPT.

Claude

Claude Code et tout autre agent qui dispose d'un terminal : demandez-lui de lancer la commande du début de cette page sur votre fichier, et de lire d'abord valid et summary.

Dans une application qui utilise l'API Messages d'Anthropic, déclarez un outil client :

{
  "name": "validate_bpmn",
  "description": "Validate a BPMN 2.0 XML document with the free LucidFlow validator. Returns errors, warnings and info. The XML must be under 50 KB.",
  "input_schema": {
    "type": "object",
    "properties": {
      "xml": { "type": "string", "description": "The BPMN 2.0 XML" }
    },
    "required": ["xml"]
  }
}

Quand Claude demande l'outil, exécutez cet appel dans votre code et renvoyez le texte comme résultat de l'outil :

async function validateBpmn(xml: string): Promise<string> {
  const res = await fetch("https://lucidflow.ai/api/v1/bpmn/validate", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ xml }),
  });
  if (res.status === 429) {
    return "Rate limited. Retry after " + res.headers.get("Retry-After") + " seconds.";
  }
  return JSON.stringify(await res.json());
}

ChatGPT

Dans un GPT personnalisé, ajoutez une action et collez ce schéma OpenAPI. Le GPT appelle ensuite le point d'accès quand vous lui demandez de vérifier un fichier BPMN. Le XML doit tenir dans le message : 50 Ko au plus.

openapi: 3.1.0
info:
  title: LucidFlow BPMN Validator
  version: "1"
servers:
  - url: https://lucidflow.ai
paths:
  /api/v1/bpmn/validate:
    post:
      operationId: validateBpmn
      summary: Validate a BPMN 2.0 XML document (50 KB at most)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [xml]
              properties:
                xml:
                  type: string
                  description: The BPMN 2.0 XML
      responses:
        "200":
          description: Validation report with errors, warnings and info
          content:
            application/json:
              schema:
                type: object
        "429":
          description: Too many requests, see the Retry-After header

Conseils pour un agent

• Lire valid et summary d'abord, puis corriger les erreurs avant les avertissements.
• Renvoyer le XML corrigé pour le vérifier. S'arrêter après quelques tours si les erreurs ne changent pas.
• Sur une réponse 429, attendre le délai Retry-After avant l'appel suivant.
• Ne pas envoyer de fichier qui contient des données confidentielles.

curl -X POST https://lucidflow.ai/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -X POST https://lucidflow.ai/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"validate_bpmn","arguments":{"xml":"<definitions ...>...</definitions>"}}}'

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"version\":1,\"valid\":true,\"summary\":{\"errors\":0,\"warnings\":1,\"info\":0}}"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "{\"error\":{\"code\":\"rate_limited\",\"message\":\"Too many requests. Try again later.\",\"docs_url\":\"https://lucidflow.ai/docs/validator-rules\",\"retry_after_seconds\":600}}"
      }
    ]
  }
}

claude mcp add --transport http lucidflow-bpmn-validator https://lucidflow.ai/api/mcp

{
  "mcpServers": {
    "lucidflow-bpmn-validator": {
      "type": "http",
      "url": "https://lucidflow.ai/api/mcp"
    }
  }
}

Aller plus loin

L'API vérifie un fichier. Pour dessiner, modifier et analyser un processus dans LucidFlow, créez un compte gratuit.