Diagrams

A Diagram is a saved BPMN process diagram in your workspace. You never read or write Just Flow It’s internal format — diagrams are created from a natural-language prompt or from standard BPMN 2.0 XML, and read back out as a rendered image or standard BPMN 2.0 XML.

All requests are server-to-server only and go to https://justflow.it/api/v1. Never expose jfi_sk_live_... keys in a browser or client app.

How diagrams are created

From a prompt

Describe the process in natural language. Runs asynchronously (generate → poll). See the Generate page.

From BPMN 2.0 XML

Send a standard BPMN 2.0 document and we import it as an editable diagram. Synchronous.

To change a diagram’s content after creation, edit it with a prompt — see Edit a diagram. PATCH only changes metadata (name, folder).

The Diagram object

string

Always "diagram".

string (uuid)

Unique identifier.

string

Human-readable name.

string (uuid) | null

The folder this diagram belongs to, or null for the root.

string (uuid) | null

Set when the diagram belongs to an organization (an org key); null for a personal diagram.

string (uuid)

The user who created the diagram.

string (ISO 8601)

Creation timestamp.

string (ISO 8601)

Last-modified timestamp.

{
  "object": "diagram",
  "id": "c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60",
  "name": "Invoice approval",
  "folder_id": null,
  "organization_id": null,
  "created_by": "1f0c9a44-6b2d-4e8a-9c31-2d5f7e0a1b22",
  "created_at": "2026-06-07T09:15:04Z",
  "updated_at": "2026-06-07T09:15:04Z"
}

Just Flow It’s internal diagram representation is never exposed by the API. To get a diagram’s content out, render it to an image or export it as BPMN 2.0.

Endpoints

List diagrams

Retrieve a diagram

Import BPMN 2.0

Update (metadata)

Delete a diagram

Render an image

Export as BPMN 2.0

Generate / edit by prompt

List diagrams

Returns a cursor-paginated list of your diagrams, newest first. Requires the diagrams:read scope.

Query parameters

integer

Items per page, 1–100. Defaults to 20.

string

Opaque cursor from a previous response (next_cursor).

string

Filter by folder UUID, or the literal null for diagrams at the root.

curl "https://justflow.it/api/v1/diagrams?limit=20" \
  -H "Authorization: Bearer jfi_sk_live_..."

const res = await fetch("https://justflow.it/api/v1/diagrams?limit=20", {
  headers: { Authorization: "Bearer jfi_sk_live_..." },
});
const { data, has_more, next_cursor } = await res.json();

import requests
res = requests.get(
    "https://justflow.it/api/v1/diagrams",
    params={"limit": 20},
    headers={"Authorization": "Bearer jfi_sk_live_..."},
)
data = res.json()["data"]

{
  "data": [
    {
      "object": "diagram",
      "id": "c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60",
      "name": "Invoice approval",
      "folder_id": null,
      "organization_id": null,
      "created_by": "1f0c9a44-6b2d-4e8a-9c31-2d5f7e0a1b22",
      "created_at": "2026-06-07T09:15:04Z",
      "updated_at": "2026-06-07T09:15:04Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

See Pagination for paging through large lists.

Retrieve a diagram

Requires the diagrams:read scope. Returns the Diagram object. Unknown id → 404 resource_not_found.

curl https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60 \
  -H "Authorization: Bearer jfi_sk_live_..."

const res = await fetch(
  "https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60",
  { headers: { Authorization: "Bearer jfi_sk_live_..." } }
);
const diagram = await res.json();

import requests
res = requests.get(
    "https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60",
    headers={"Authorization": "Bearer jfi_sk_live_..."},
)
diagram = res.json()

Import a BPMN 2.0 diagram

Create a diagram from a standard BPMN 2.0 XML document (the format exported by Camunda, Bizagi, Signavio, bpmn.io, etc.). The XML is parsed and laid out, then saved as an editable diagram in your workspace. Synchronous — returns 201 Created. Requires the diagrams:write scope.

Request body

string

required

A standard BPMN 2.0 XML document.

string

Optional name for the diagram. Defaults to the process name from the XML, or “Untitled Diagram”.

string (uuid) | null

Optional folder to place the diagram in.

curl -X POST https://justflow.it/api/v1/diagrams/import \
  -H "Authorization: Bearer jfi_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Imported from Camunda",
    "bpmn_xml": "<?xml version=\"1.0\"?><bpmn:definitions ...>...</bpmn:definitions>"
  }'

import { readFileSync } from "node:fs";
const res = await fetch("https://justflow.it/api/v1/diagrams/import", {
  method: "POST",
  headers: {
    Authorization: "Bearer jfi_sk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Imported from Camunda",
    bpmn_xml: readFileSync("process.bpmn", "utf8"),
  }),
});
const diagram = await res.json(); // 201

import requests
res = requests.post(
    "https://justflow.it/api/v1/diagrams/import",
    headers={"Authorization": "Bearer jfi_sk_live_..."},
    json={"name": "Imported from Camunda", "bpmn_xml": open("process.bpmn").read()},
)
diagram = res.json()  # 201

Returns the created Diagram object with a Location header. To get a rendered preview, call render an image on the new id.

Invalid or unsupported BPMN 2.0 returns 422 validation_failed with error.param set to bpmn_xml. Diagrams above the supported size (200 elements) are rejected with 422.

Update a diagram

Updates a diagram’s metadata only — name and folder_id. Requires the diagrams:write scope.

To change a diagram’s content, edit it with a prompt — see Edit a diagram. There is no way to write Just Flow It’s internal format directly.

Request body

string

New name.

string (uuid) | null

Move the diagram to a folder, or null for the root.

curl -X PATCH https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60 \
  -H "Authorization: Bearer jfi_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Invoice approval v2" }'

const res = await fetch(
  "https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer jfi_sk_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "Invoice approval v2" }),
  }
);
const diagram = await res.json();

import requests
res = requests.patch(
    "https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60",
    headers={"Authorization": "Bearer jfi_sk_live_..."},
    json={"name": "Invoice approval v2"},
)
diagram = res.json()

Delete a diagram

Permanently deletes a diagram. Requires the diagrams:write scope. Returns 204 No Content.

curl -X DELETE https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60 \
  -H "Authorization: Bearer jfi_sk_live_..."

await fetch(
  "https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60",
  { method: "DELETE", headers: { Authorization: "Bearer jfi_sk_live_..." } }
);

import requests
requests.delete(
    "https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60",
    headers={"Authorization": "Bearer jfi_sk_live_..."},
)

Render a diagram image

Renders the diagram to an image on demand (cached). Requires the diagrams:read scope. See the Diagram images page for full detail.

Query parameters

string

"light" (default) or "dark".

string

"png" (default) or "svg".

curl "https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60/image?theme=dark&format=png" \
  -H "Authorization: Bearer jfi_sk_live_..." --output diagram.png

const res = await fetch(
  "https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60/image?theme=dark&format=png",
  { headers: { Authorization: "Bearer jfi_sk_live_..." } }
);
const blob = await res.blob();

import requests
res = requests.get(
    "https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60/image",
    params={"theme": "dark", "format": "png"},
    headers={"Authorization": "Bearer jfi_sk_live_..."},
)
open("diagram.png", "wb").write(res.content)

Export as BPMN 2.0

Exports the diagram as a standard BPMN 2.0 XML document you can open in Camunda, Bizagi, Signavio, bpmn.io, and other BPMN tools. Requires the diagrams:read scope.

curl https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60/bpmn \
  -H "Authorization: Bearer jfi_sk_live_..." --output process.bpmn

const res = await fetch(
  "https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60/bpmn",
  { headers: { Authorization: "Bearer jfi_sk_live_..." } }
);
const bpmnXml = await res.text();

import requests
res = requests.get(
    "https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60/bpmn",
    headers={"Authorization": "Bearer jfi_sk_live_..."},
)
bpmn_xml = res.text

Returns 200 with Content-Type: application/xml (the BPMN 2.0 document). A round-trip is supported: a diagram you imported or generated can be exported back to BPMN 2.0.

Errors

Status	`type`	Notes
400	`invalid_request_error`	Bad JSON, missing/invalid parameter, or invalid cursor
401	`authentication_error`	Missing/invalid/revoked/expired key
403	`permission_error`	`plan_required` or `insufficient_scope`
404	`not_found_error`	No diagram with that id
422	`validation_error`	`validation_failed` — e.g. the `bpmn_xml` is not valid BPMN 2.0
429	`rate_limit_error`	Burst limit or generation quota

See Errors for the full envelope and codes.

Getting started

Core concepts

Endpoints

How diagrams are created

From a prompt

From BPMN 2.0 XML

The Diagram object

Endpoints

List diagrams

Retrieve a diagram

Import BPMN 2.0

Update (metadata)

Delete a diagram

Render an image

Export as BPMN 2.0

Generate / edit by prompt

List diagrams

Query parameters

Retrieve a diagram

Import a BPMN 2.0 diagram

Request body

Update a diagram

Request body

Delete a diagram

Render a diagram image

Query parameters

Export as BPMN 2.0

Errors

​How diagrams are created

From a prompt

From BPMN 2.0 XML

​The Diagram object

​Endpoints

List diagrams

Retrieve a diagram

Import BPMN 2.0

Update (metadata)

Delete a diagram

Render an image

Export as BPMN 2.0

Generate / edit by prompt

​List diagrams

​Query parameters

​Retrieve a diagram

​Import a BPMN 2.0 diagram

​Request body

​Update a diagram

​Request body

​Delete a diagram

​Render a diagram image

​Query parameters

​Export as BPMN 2.0

​Errors

How diagrams are created

The Diagram object

Endpoints

List diagrams

Query parameters

Retrieve a diagram

Import a BPMN 2.0 diagram

Request body

Update a diagram

Request body

Delete a diagram

Render a diagram image

Query parameters

Export as BPMN 2.0

Errors