API ACCESS

Generate process maps with our API

Send a text prompt, get back BPMN 2.0 XML. Refine existing diagrams with follow-up prompts. Try it below with a built-in mock — no signup required.

Generate BPMN from a text prompt
Refine existing diagrams with follow-ups
Built-in Test Console in the dashboard

Try the mock demo Contact us

TRY IT

Mock the API in your browser

Pick Initial to see what a fresh generation returns (3 BPMN options) or Refinement to see how a follow-up prompt updates an existing diagram (1 result). Same UX as the in-product Test Console.

Choose request type

Request body

Initial

POST

/api/v1/process-maps/generations

{
  "mode": "initial",
  "prompt": "Map the customer support ticket triage process from intake to resolution.",
  "language": "english"
}

In a real request you'd send Authorization: Bearer bac_sk_… and Content-Type: application/json. This sandbox skips the network call entirely.

Send

This sandbox returns a sample response instantly. No API key required, no generations are used.

Response

Send the mock request to preview the BPMN diagram here.

Want to call the live API?

Open Test Console

QUICK START

Three steps to live

1. Create an API key

2. Test in the console

Use the in-product Test Console to send mock or live requests, inspect the BPMN preview, JSON, and XML — all without writing code.

3. Call from your code

POST to /api/v1/process-maps/generations with your bearer token. Use mode "initial" for new diagrams, "refinement" to evolve them.

REFERENCE

API Reference

Two modes, one endpoint. The full machine-readable contract is at /api/v1/openapi.json.

Initial generation

Returns 3 options

Send a text prompt describing the process. The API returns three distinct BPMN 2.0 options so you (or your user) can pick the best starting point.

Request

POST /api/v1/process-maps/generations
Authorization: Bearer bac_sk_...
Content-Type: application/json

{
  "mode": "initial",
  "prompt": "Map the customer support ticket triage process from intake to resolution.",
  "language": "english"
}

Response

200 OK
Content-Type: application/json

{
  "id": "33333333-3333-4333-8333-333333333333",
  "status": "succeeded",
  "mode": "initial",
  "request_id": "0d6cf3b1-9e07-4a6a-8b1f-3c2c0e9a7c54",
  "created_at": "2025-01-15T12:34:56.000Z",
  "completed_at": "2025-01-15T12:35:08.000Z",
  "links": {
    "self": "https://ba-copilot.com/api/v1/process-maps/generations/33333333-3333-4333-8333-333333333333"
  },
  "options": [
    {
      "option_number": 1,
      "versions": [{ "version_number": 1, "bpmn_xml": "<?xml version=\"1.0\"?>..." }]
    },
    {
      "option_number": 2,
      "versions": [{ "version_number": 1, "bpmn_xml": "<?xml version=\"1.0\"?>..." }]
    },
    {
      "option_number": 3,
      "versions": [{ "version_number": 1, "bpmn_xml": "<?xml version=\"1.0\"?>..." }]
    }
  ]
}

Refinement

Returns 1 result

Refine an existing process map with a follow-up prompt. The example below references a stored generation by id; you can also pass inline BPMN XML via source: { bpmn_xml: "..." } — see the OpenAPI spec for the full schema.

Request

POST /api/v1/process-maps/generations
Authorization: Bearer bac_sk_...
Content-Type: application/json

{
  "mode": "refinement",
  "prompt": "Add an escalation path for high-severity tickets.",
  "source": {
    "generation_id": "33333333-3333-4333-8333-333333333333",
    "option_number": 2,
    "version_number": 1
  }
}

Response

200 OK
Content-Type: application/json

{
  "id": "44444444-4444-4444-8444-444444444444",
  "status": "succeeded",
  "mode": "refinement",
  "request_id": "1f4ab2c0-2d3a-44f7-9d2c-7b6c4a3e1f02",
  "created_at": "2025-01-15T12:40:11.000Z",
  "completed_at": "2025-01-15T12:40:18.000Z",
  "links": {
    "self": "https://ba-copilot.com/api/v1/process-maps/generations/44444444-4444-4444-8444-444444444444"
  },
  "result": {
    "option_number": 1,
    "version_number": 1,
    "bpmn_xml": "<?xml version=\"1.0\"?>...",
    "source": {
      "generation_id": "33333333-3333-4333-8333-333333333333",
      "option_number": 2,
      "version_number": 1
    }
  }
}

Sync or async, your choice

By default the request waits for completion (?wait=true) and returns the BPMN inline. Set ?wait=false to start the job in the background and poll the returned links.self URL. Send an Idempotency-Key header for safe retries.

Running response (poll the self link)

202 Accepted
Content-Type: application/json

{
  "id": "22222222-2222-4222-8222-222222222222",
  "status": "running",
  "request_id": "8a3b1e6c-5f48-4c2b-a1e8-9b3d2f0c7e11",
  "links": {
    "self": "https://ba-copilot.com/api/v1/process-maps/generations/22222222-2222-4222-8222-222222222222"
  }
}

List & retrieve generations

GET /api/v1/process-maps/generations          # list (cursor paginated)
GET /api/v1/process-maps/generations/{id}     # retrieve one

# Generation deletion is available in the dashboard UI.

Have questions?

We're happy to help with anything pre or post integration — auth, quotas, error handling, or unusual prompts.

OpenAPI spec Contact support