Generate a diagram

Turn a plain-language description of a process into a saved, laid-out diagram and a rendered image. Because generation runs an LLM and then renders the result, it can take many seconds — so the API is asynchronous: you create a generation job, then poll it until it finishes.

All requests are server-to-server only. Never expose jfi_sk_live_... keys in a browser or client app.

Why async?

A single generation involves an LLM call plus a server-side layout and render pass. That can comfortably exceed the lifetime of a normal HTTP request. Rather than hold a connection open (and risk timeouts), POST /v1/diagrams/generate returns immediately with 202 Accepted and a Generation job in queued status. You then poll GET /v1/generations/{id} until the job reaches a terminal state.

Webhooks for generation completion are planned for v2. Until then, poll the generation endpoint with backoff (see the example below).

The flow

Create the generation

POST /v1/diagrams/generate with your prompt. You get back 202 Accepted, a Generation with status: "queued", a Location header pointing at the poll URL, and a Retry-After hint.

Poll for status

GET the URL from the Location header. While status is queued or processing, wait and try again (respecting Retry-After and backing off).

Read the result

When status is succeeded, the diagram (the created, saved diagram) and image_url (the rendered image for the requested theme/format) are populated. When status is failed, error explains why.

Create a generation

Requires the generate scope. Counts against your monthly generation quota (500 generations per rolling 30 days).

Body

string

required

Natural-language description of the process to generate. Up to 20,000 characters; a longer prompt returns 400 invalid_parameter.

string

Theme for the rendered image: "light" (default) or "dark".

string

Image format: "png" (default) or "svg".

string

Optional name for the resulting diagram.

string | null

Optional folder (UUID) to place the diagram in, or null for the root.

array

Optional files the diagram should be based on: images, PDFs and text files. See Attachments.

curl https://justflow.it/api/v1/diagrams/generate \
  -H "Authorization: Bearer jfi_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "An employee submits an expense report. A manager approves or rejects it. If approved, finance reimburses the employee.",
    "theme": "light",
    "format": "png",
    "name": "Expense approval"
  }'

const res = await fetch("https://justflow.it/api/v1/diagrams/generate", {
  method: "POST",
  headers: {
    Authorization: "Bearer jfi_sk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt:
      "An employee submits an expense report. A manager approves or rejects it. If approved, finance reimburses the employee.",
    theme: "light",
    format: "png",
    name: "Expense approval",
  }),
});

// 202 Accepted — a queued generation job
const generation = await res.json();
const pollUrl = res.headers.get("Location");

import requests

res = requests.post(
    "https://justflow.it/api/v1/diagrams/generate",
    headers={"Authorization": "Bearer jfi_sk_live_..."},
    json={
        "prompt": "An employee submits an expense report. A manager approves or rejects it. If approved, finance reimburses the employee.",
        "theme": "light",
        "format": "png",
        "name": "Expense approval",
    },
)

# 202 Accepted — a queued generation job
generation = res.json()
poll_url = res.headers["Location"]

Response

202 Accepted

HTTP/1.1 202 Accepted
Location: /v1/generations/gen_3pK9xQ2mL7vR
Retry-After: 2
X-Request-Id: req_8aF2c1

{
  "object": "generation",
  "id": "gen_3pK9xQ2mL7vR",
  "status": "queued",
  "diagram": null,
  "image_url": null,
  "error": null,
  "created_at": "2026-06-07T14:22:05Z"
}

string

Always "generation".

string

The generation job id, prefixed with gen_. Use it to poll.

string

One of "queued", "processing", "succeeded", "failed".

object | null

The created, saved Diagram once status is "succeeded"; otherwise null.

string | null

Path to the rendered image (per the requested theme/format) once status is "succeeded"; otherwise null. It is relative to the API base (https://justflow.it) — prepend the base to fetch it.

object | null

{ "code": string, "message": string } when status is "failed"; otherwise null.

string

ISO-8601 UTC timestamp.

Poll the generation

Requires the generate scope. Poll until status reaches a terminal state (succeeded or failed).

curl https://justflow.it/api/v1/generations/gen_3pK9xQ2mL7vR \
  -H "Authorization: Bearer jfi_sk_live_..."

const res = await fetch(
  "https://justflow.it/api/v1/generations/gen_3pK9xQ2mL7vR",
  { headers: { Authorization: "Bearer jfi_sk_live_..." } }
);
const generation = await res.json();

import requests

res = requests.get(
    "https://justflow.it/api/v1/generations/gen_3pK9xQ2mL7vR",
    headers={"Authorization": "Bearer jfi_sk_live_..."},
)
generation = res.json()

Response — succeeded

200 OK

{
  "object": "generation",
  "id": "gen_3pK9xQ2mL7vR",
  "status": "succeeded",
  "diagram": {
    "object": "diagram",
    "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
    "name": "Expense approval",
    "folder_id": null,
    "organization_id": null,
    "created_by": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",
    "created_at": "2026-06-07T14:22:09Z",
    "updated_at": "2026-06-07T14:22:09Z"
  },
  "image_url": "/api/v1/diagrams/a1b2c3d4-5e6f-7890-abcd-ef1234567890/image?theme=light&format=png",
  "error": null,
  "created_at": "2026-06-07T14:22:05Z"
}

Response — failed

200 OK

{
  "object": "generation",
  "id": "gen_3pK9xQ2mL7vR",
  "status": "failed",
  "diagram": null,
  "image_url": null,
  "error": {
    "code": "validation_failed",
    "message": "The generated process could not be laid out as a valid diagram."
  },
  "created_at": "2026-06-07T14:22:05Z"
}

A failed generation returns 200 OK with status: "failed" — the HTTP request to poll succeeded; the job did not. Inspect generation.status and generation.error, not the HTTP status code, to decide outcome.

Full polling example

Poll the Location URL, respecting the initial Retry-After and then backing off, until the job is terminal.

#!/usr/bin/env bash
set -euo pipefail
KEY="jfi_sk_live_..."
BASE="https://justflow.it/api/v1"

# 1. Create the generation
RESP=$(curl -s -D - -o /tmp/gen.json "$BASE/diagrams/generate" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Order-to-cash process for a B2B SaaS company","format":"svg"}')

# The generation id is in the 202 body; poll it against the same BASE.
GEN_ID=$(jq -r '.id' /tmp/gen.json)
DELAY=$(printf '%s' "$RESP" | awk -F': ' 'tolower($1)=="retry-after"{print $2}' | tr -d '\r')
DELAY=${DELAY:-2}

# 2. Poll until terminal
while true; do
  curl -s "$BASE/generations/$GEN_ID" -H "Authorization: Bearer $KEY" -o /tmp/poll.json
  STATUS=$(jq -r '.status' /tmp/poll.json)
  echo "status: $STATUS"
  case "$STATUS" in
    succeeded) jq '{diagram_id: .diagram.id, image_url}' /tmp/poll.json; break ;;
    failed)    jq '.error' /tmp/poll.json; exit 1 ;;
    *)         sleep "$DELAY"; DELAY=$(( DELAY < 16 ? DELAY * 2 : 16 )) ;;
  esac
done

const KEY = "jfi_sk_live_...";
const BASE = "https://justflow.it/api/v1";
const auth = { Authorization: `Bearer ${KEY}` };
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

async function generateDiagram(prompt) {
  // 1. Create the generation
  const create = await fetch(`${BASE}/diagrams/generate`, {
    method: "POST",
    headers: { ...auth, "Content-Type": "application/json" },
    body: JSON.stringify({ prompt, format: "svg" }),
  });
  if (create.status !== 202) throw new Error(`unexpected ${create.status}`);

  // The generation id is in the 202 body; poll it against the same BASE.
  const { id } = await create.json();
  let delay = (Number(create.headers.get("Retry-After")) || 2) * 1000;

  // 2. Poll until terminal
  while (true) {
    const res = await fetch(`${BASE}/generations/${id}`, { headers: auth });
    const gen = await res.json();
    if (gen.status === "succeeded") {
      return { diagram: gen.diagram, imageUrl: gen.image_url };
    }
    if (gen.status === "failed") {
      throw new Error(`generation failed: ${gen.error.message}`);
    }
    await sleep(delay);
    delay = Math.min(delay * 2, 16000); // exponential backoff, capped at 16s
  }
}

import time
import requests

KEY = "jfi_sk_live_..."
BASE = "https://justflow.it/api/v1"
AUTH = {"Authorization": f"Bearer {KEY}"}


def generate_diagram(prompt: str) -> dict:
    # 1. Create the generation
    create = requests.post(
        f"{BASE}/diagrams/generate",
        headers=AUTH,
        json={"prompt": prompt, "format": "svg"},
    )
    if create.status_code != 202:
        raise RuntimeError(f"unexpected {create.status_code}")

    # The generation id is in the 202 body; poll it against the same BASE.
    gen_id = create.json()["id"]
    delay = int(create.headers.get("Retry-After", "2"))

    # 2. Poll until terminal
    while True:
        gen = requests.get(f"{BASE}/generations/{gen_id}", headers=AUTH).json()
        if gen["status"] == "succeeded":
            return {"diagram": gen["diagram"], "image_url": gen["image_url"]}
        if gen["status"] == "failed":
            raise RuntimeError(f"generation failed: {gen['error']['message']}")
        time.sleep(delay)
        delay = min(delay * 2, 16)  # exponential backoff, capped at 16s

Already have a saved diagram and just want to re-fetch or re-theme its image? Use GET /v1/diagrams/{id}/image with theme and format query params — no regeneration, no quota cost.

Edit an existing diagram

Change a saved diagram’s content with another natural-language instruction. Editing runs an LLM and a render too, so it uses the same asynchronous flow as generation: create an edit job, then poll. Requires the generate scope and counts against the generation quota.

Body

string

required

Natural-language instruction describing the change — e.g. “add a rejection path after the approval gateway” or “rename the first task to ‘Receive invoice’”. Up to 20,000 characters.

string

Theme for the re-rendered image: "light" (default) or "dark".

string

Image format: "png" (default) or "svg".

array

Optional files the diagram should be based on: images, PDFs and text files. See Attachments.

curl -X POST https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60/edit \
  -H "Authorization: Bearer jfi_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Add a rejection path after the approval gateway" }'

const res = await fetch(
  "https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60/edit",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer jfi_sk_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ prompt: "Add a rejection path after the approval gateway" }),
  }
);
const generation = await res.json(); // 202 — poll it like a generation

import requests
res = requests.post(
    "https://justflow.it/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60/edit",
    headers={"Authorization": "Bearer jfi_sk_live_..."},
    json={"prompt": "Add a rejection path after the approval gateway"},
)
generation = res.json()  # 202 — poll it like a generation

Returns 202 Accepted with a Generation (identical shape to generate). Poll GET /v1/generations/{id} exactly as above; on success, diagram is the updated diagram and image_url is the re-rendered image.

Editing applies the instruction to the diagram’s current content and updates it in place (same diagram id). It is the only way to change a diagram’s content — PATCH /v1/diagrams/{id} changes metadata (name, folder) only.

Attachments

generate and edit take an optional attachments array, so the AI can work from a process write-up, a spreadsheet, a whiteboard photo or a PDF. Each item has a name (with its extension) and one of:

data: the file’s bytes in base64. Works for every accepted type.
text: the file’s content as text. Only for text files.

Kind	Accepted	Read as
Images	PNG, JPEG, WebP (no GIF)	the image
PDF	`.pdf`, up to 20 pages	the document
Text	`.md` `.markdown` `.txt` `.csv` `.tsv` `.json` `.xml` `.bpmn` `.yaml` `.yml` `.html` `.htm` `.log`	text (UTF-8, UTF-16 with BOM or Windows-1252)

Limits per request: up to 4 images and 4 documents (PDF or text), 2.5 MB in total, and 40 PDF pages in total. A text file can have up to 2 MB. The AI reads up to 100,000 characters of each text file and 150,000 across all of them; a file past that is cut, or left out once the total is reached, and the AI is told so. Images and PDFs are recognised by their bytes, whatever the name. Anything else needs one of the text extensions above and must really be text, on both data and text. Audio is not accepted. Files are sent to the AI and not stored.

Python (requests)

import base64
import requests

with open("whiteboard.png", "rb") as f:
    image = base64.b64encode(f.read()).decode()
with open("process.md", encoding="utf-8") as f:
    notes = f.read()

res = requests.post(
    "https://justflow.it/api/v1/diagrams/generate",
    headers={"Authorization": "Bearer jfi_sk_live_..."},
    json={
        "prompt": "Draw the purchasing process described in these files",
        "attachments": [
            {"name": "process.md", "text": notes},
            {"name": "whiteboard.png", "data": image},
        ],
    },
)

An attachment that is not accepted returns 400 before any job is created, with error.param naming it (e.g. attachments[1]):

unsupported_attachment: a type that is not accepted, a GIF, a .pdf that is not a readable PDF (damaged or password-protected), a text file that is not text, or text sent for an image or PDF.
invalid_parameter: a malformed item, invalid base64, more than 4 images or 4 documents, a PDF over 20 pages or PDFs over 40 pages in total, or a text file over 2 MB. More than 8 items names attachments.

Attachments over 2.5 MB in total return 413 payload_too_large. Request bodies over 4.5 MB are refused by the hosting platform with a plain 413 and no error envelope, so keep files within 2.5 MB.

Quota & rate limits

Generation is metered on two axes, both per account (shared by all of its API keys and connected AI assistants):

Generation quota

500 generations per rolling 30 days. Every POST /v1/diagrams/generate and POST /v1/diagrams/{id}/edit counts once, including requests refused with an error (for example a 400 for an attachment) and jobs that later end in failed. Check attachments on your side before sending.

Burst limit

120 requests / 60s across all endpoints, including your poll calls.

Every response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (seconds). On a 429, a Retry-After (seconds) header tells you how long to wait.

When the monthly generation quota is exhausted, POST /v1/diagrams/generate returns 429 with error.code quota_exceeded. When you’re sending too fast, it returns 429 with rate_limit_exceeded. Back off using Retry-After.

Errors

Every error uses the standard envelope:

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This key is missing the required scope: generate."
  },
  "request_id": "req_8aF2c1"
}

Errors you may hit on this endpoint

Status	`type`	`code`	When
400	`invalid_request_error`	`missing_parameter`	`prompt` is absent
400	`invalid_request_error`	`invalid_parameter`	Bad `folder_id`, `theme`, `format`, or `attachments`
400	`invalid_request_error`	`invalid_json`	Malformed request body
400	`invalid_request_error`	`unsupported_attachment`	An attachment’s type is not accepted, or its content does not match it
413	`invalid_request_error`	`payload_too_large`	Attachments over 2.5 MB in total
401	`authentication_error`	`invalid_api_key`	Missing/invalid/revoked/expired key
403	`permission_error`	`plan_required`	Free plan — the API requires a paid plan
403	`permission_error`	`insufficient_scope`	Key lacks the `generate` scope
404	`not_found_error`	`resource_not_found`	Unknown generation `id` on poll
429	`rate_limit_error`	`rate_limit_exceeded`	Burst limit hit
429	`rate_limit_error`	`quota_exceeded`	Monthly generation quota exhausted
500	`api_error`	`internal_error`	Unexpected server error

Note: when a job’s content is invalid (e.g. it can’t be laid out as valid BPMN), the poll returns 200 with status: "failed" and error.code: "validation_failed" — not an HTTP 422.

Getting started

Core concepts

Endpoints

Why async?

The flow

Create a generation

Body

Response

Poll the generation

Response — succeeded

Response — failed

Full polling example

Edit an existing diagram

Body

Attachments

Quota & rate limits

Generation quota

Burst limit

Errors

​Why async?

​The flow

​Create a generation

​Body

​Response

​Poll the generation

​Response — succeeded

​Response — failed

​Full polling example

​Edit an existing diagram

​Body

​Attachments

​Quota & rate limits

Generation quota

Burst limit

​Errors

Why async?

The flow

Create a generation

Body

Response

Poll the generation

Response — succeeded

Response — failed

Full polling example

Edit an existing diagram

Body

Attachments

Quota & rate limits

Errors