BPMN Validator API

Send a BPMN 2.0 file as XML and get a JSON report back: errors, warnings and information, each with the rule that raised it and its position in the file. The API is free and needs no account and no key. It runs the same engine as the online BPMN validator of LucidFlow. The XML is checked in memory and only the report is returned: the API code does not save the file.

One command

Replace process.bpmn with your file:

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

Request

One endpoint, one method. The API takes the content of the file, not a link to it.

A small file you can save as process.bpmn to try the command above. Its process has no end event, so the report below shows a warning:

<?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>}'

Response

A valid request answers 200 with a JSON report. A file that is not well-formed XML, or not BPMN, is not an HTTP error: the answer is still 200, with valid set to false and the problems listed in errors.

Abridged report for the sample file above: only the first warning is listed, and the second warning and the information items are left out. The lists and the counts depend on your file.

{
  "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": "..."
  }
}

Messages and rule names are in English. The rules are listed in the rules reference.

Errors

When the request itself is refused, the body is a JSON object with a code, a message and a link to the rules reference:

Example of a refused request:

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

Limits

Agents hosted in the cloud often share one IP address, so they can reach the rate limit sooner. The counters are shared by all servers; if the shared store is unavailable, each server counts alone and the limits apply per server. Do not send confidential documents: the XML is processed on LucidFlow servers.

Use it from an AI assistant

The API is a plain HTTP endpoint. Here is how to give it to Claude or ChatGPT.

Claude

Claude Code and any other agent that has a shell: ask it to run the command from the top of this page on your file, and to read valid and summary first.

In an application that uses the Anthropic Messages API, declare a client tool:

{
  "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"]
  }
}

When Claude asks for the tool, run this call in your code and send the text back as the tool result:

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

In a custom GPT, add an action and paste this OpenAPI schema. The GPT then calls the endpoint when you ask it to check a BPMN file. The XML must fit in the message: 50 KB at most.

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

Tips for agents

• Read valid and summary first, then fix the errors before the warnings.
• Send the corrected XML again to check it. Stop after a few rounds if the errors do not change.
• On a 429 answer, wait for the Retry-After delay before the next call.
• Do not send files that contain confidential data.

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"
    }
  }
}

Go further

The API checks a file. To draw, edit and analyze a process in LucidFlow, create a free account.