> ## Documentation Index
> Fetch the complete documentation index at: https://docs.justflow.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagrams

> List, retrieve, import, update, delete, render, and export BPMN process diagrams with the Just Flow It API.

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**.

<Note>
  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.
</Note>

## How diagrams are created

<CardGroup cols={2}>
  <Card title="From a prompt" icon="wand-magic-sparkles" href="/api-reference/generate">
    Describe the process in natural language. Runs asynchronously (generate → poll). See the [Generate](/api-reference/generate) page.
  </Card>

  <Card title="From BPMN 2.0 XML" icon="file-import" href="#import-a-bpmn-2-0-diagram">
    Send a standard BPMN 2.0 document and we import it as an editable diagram. Synchronous.
  </Card>
</CardGroup>

To change a diagram's **content** after creation, edit it with a prompt — see [Edit a diagram](/api-reference/generate#edit-an-existing-diagram). `PATCH` only changes metadata (name, folder).

## The Diagram object

<ResponseField name="object" type="string">
  Always `"diagram"`.
</ResponseField>

<ResponseField name="id" type="string (uuid)">
  Unique identifier.
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable name.
</ResponseField>

<ResponseField name="folder_id" type="string (uuid) | null">
  The folder this diagram belongs to, or `null` for the root.
</ResponseField>

<ResponseField name="organization_id" type="string (uuid) | null">
  Set when the diagram belongs to an organization (an org key); `null` for a personal diagram.
</ResponseField>

<ResponseField name="created_by" type="string (uuid)">
  The user who created the diagram.
</ResponseField>

<ResponseField name="created_at" type="string (ISO 8601)">
  Creation timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string (ISO 8601)">
  Last-modified timestamp.
</ResponseField>

```json theme={null}
{
  "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"
}
```

<Note>
  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](#render-a-diagram-image) or export it as [BPMN 2.0](#export-as-bpmn-2-0).
</Note>

## Endpoints

<CardGroup cols={2}>
  <Card title="List diagrams" icon="list" href="#list-diagrams" />

  <Card title="Retrieve a diagram" icon="magnifying-glass" href="#retrieve-a-diagram" />

  <Card title="Import BPMN 2.0" icon="file-import" href="#import-a-bpmn-2-0-diagram" />

  <Card title="Update (metadata)" icon="pen" href="#update-a-diagram" />

  <Card title="Delete a diagram" icon="trash" href="#delete-a-diagram" />

  <Card title="Render an image" icon="image" href="#render-a-diagram-image" />

  <Card title="Export as BPMN 2.0" icon="file-export" href="#export-as-bpmn-2-0" />

  <Card title="Generate / edit by prompt" icon="wand-magic-sparkles" href="/api-reference/generate" />
</CardGroup>

## List diagrams

<ParamField path="GET /v1/diagrams" />

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

### Query parameters

<ParamField query="limit" type="integer">
  Items per page, `1`–`100`. Defaults to `20`.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque cursor from a previous response (`next_cursor`).
</ParamField>

<ParamField query="folder_id" type="string">
  Filter by folder UUID, or the literal `null` for diagrams at the root.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl "https://justflow.it/api/v1/diagrams?limit=20" \
    -H "Authorization: Bearer jfi_sk_live_..."
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  import requests
  res = requests.get(
      "https://justflow.it/api/v1/diagrams",
      params={"limit": 20},
      headers={"Authorization": "Bearer jfi_sk_live_..."},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

```json theme={null}
{
  "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](/api-reference/pagination) for paging through large lists.

## Retrieve a diagram

<ParamField path="GET /v1/diagrams/{id}" />

Requires the `diagrams:read` scope. Returns the [Diagram object](#the-diagram-object). Unknown id → `404 resource_not_found`.

<CodeGroup>
  ```bash curl theme={null}
  curl https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60 \
    -H "Authorization: Bearer jfi_sk_live_..."
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

## Import a BPMN 2.0 diagram

<ParamField path="POST /v1/diagrams/import" />

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

<ParamField body="bpmn_xml" type="string" required>
  A standard BPMN 2.0 XML document.
</ParamField>

<ParamField body="name" type="string">
  Optional name for the diagram. Defaults to the process name from the XML, or "Untitled Diagram".
</ParamField>

<ParamField body="folder_id" type="string (uuid) | null">
  Optional folder to place the diagram in.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  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>"
    }'
  ```

  ```javascript JavaScript theme={null}
  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
  ```

  ```python Python theme={null}
  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
  ```
</CodeGroup>

Returns the created [Diagram object](#the-diagram-object) with a `Location` header. To get a rendered preview, call [render an image](#render-a-diagram-image) on the new id.

<Warning>
  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`.
</Warning>

## Update a diagram

<ParamField path="PATCH /v1/diagrams/{id}" />

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

<Note>
  To change a diagram's **content**, edit it with a prompt — see [Edit a diagram](/api-reference/generate#edit-an-existing-diagram). There is no way to write Just Flow It's internal format directly.
</Note>

### Request body

<ParamField body="name" type="string">
  New name.
</ParamField>

<ParamField body="folder_id" type="string (uuid) | null">
  Move the diagram to a folder, or `null` for the root.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  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" }'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

## Delete a diagram

<ParamField path="DELETE /v1/diagrams/{id}" />

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

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60 \
    -H "Authorization: Bearer jfi_sk_live_..."
  ```

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

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

## Render a diagram image

<ParamField path="GET /v1/diagrams/{id}/image" />

Renders the diagram to an image on demand (cached). Requires the `diagrams:read` scope. See the [Diagram images](/api-reference/images) page for full detail.

### Query parameters

<ParamField query="theme" type="string">
  `"light"` (default) or `"dark"`.
</ParamField>

<ParamField query="format" type="string">
  `"png"` (default) or `"svg"`.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  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
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

## Export as BPMN 2.0

<ParamField path="GET /v1/diagrams/{id}/bpmn" />

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.

<CodeGroup>
  ```bash curl theme={null}
  curl https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60/bpmn \
    -H "Authorization: Bearer jfi_sk_live_..." --output process.bpmn
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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
  ```
</CodeGroup>

Returns `200` with `Content-Type: application/xml` (the BPMN 2.0 document). A round-trip is supported: a diagram you [imported](#import-a-bpmn-2-0-diagram) or [generated](/api-reference/generate) 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](/api-reference/errors) for the full envelope and codes.