Quickstart

Get from zero to a generated diagram in three steps: create a key, list your diagrams, then generate a new diagram from a natural-language prompt and poll for its image_url.

The Just Flow It API is server-to-server only. There is no CORS support — never embed an API key in a browser or mobile client. All requests go to https://justflow.it/api/v1.

Create an API key

API keys are created in the web app, not via the API.

Open Just Flow It and go to Settings → API keys.
Click Create key and choose the scopes you need (diagrams:read, diagrams:write, folders:read, folders:write, generate).
Copy the key immediately — it is shown in plaintext only once at creation. Only a SHA-256 hash is stored server-side.

Keys look like jfi_sk_live_xxxxx (production) or jfi_sk_test_xxxxx (staging).

The API is available on paid plans only. A Pro user receives a personal key that acts on their personal diagrams and folders; a member of a Team organization receives an org key that acts on that org’s resources. Free-plan keys are rejected with 403 plan_required.

Store the key in an environment variable so it never lands in source control:

export JFI_API_KEY="jfi_sk_live_xxxxx"

Make your first authenticated request

Authenticate with HTTP Bearer auth and list your diagrams. This call requires the diagrams:read scope.

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

const res = await fetch("https://justflow.it/api/v1/diagrams?limit=20", {
  headers: {
    Authorization: `Bearer ${process.env.JFI_API_KEY}`,
  },
});
const body = await res.json();
console.log(body.data);

import os
import requests

res = requests.get(
    "https://justflow.it/api/v1/diagrams",
    params={"limit": 20},
    headers={"Authorization": f"Bearer {os.environ['JFI_API_KEY']}"},
)
res.raise_for_status()
print(res.json()["data"])

A successful response is a 200 with a cursor-paginated list of diagrams:

{
  "data": [
    {
      "object": "diagram",
      "id": "9b2d6f1c-3a8e-4c2b-9f10-7a1e5d4c8b00",
      "name": "Onboarding process",
      "folder_id": null,
      "organization_id": null,
      "created_by": "1f0c9a44-6b2d-4e8a-9c31-2d5f7e0a1b22",
      "created_at": "2026-06-01T12:30:00Z",
      "updated_at": "2026-06-01T12:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

To page through results, pass next_cursor back as the cursor query parameter on your next request.

If you get a 401 or 403

Every error uses the same envelope, and the response carries an X-Request-Id header:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid."
  },
  "request_id": "req_8f3a9c2e1b"
}

401 missing_api_key / invalid_api_key / revoked_api_key / expired_api_key — check the Authorization header. 401 responses also include a WWW-Authenticate: Bearer header.
403 plan_required — your plan does not include API access.
403 insufficient_scope — the key is missing the diagrams:read scope.

Generate a diagram from a prompt

Diagram generation runs an LLM and a render, so it is asynchronous: you create a generation job, then poll it until it succeeds. This call requires the generate scope and counts against your monthly generation quota.

curl -X POST https://justflow.it/api/v1/diagrams/generate \
  -H "Authorization: Bearer $JFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "An invoice approval process: receive invoice, validate, route to manager for approval, then pay or reject.",
    "name": "Invoice approval",
    "theme": "light",
    "format": "png"
  }'

const res = await fetch("https://justflow.it/api/v1/diagrams/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.JFI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt:
      "An invoice approval process: receive invoice, validate, route to manager for approval, then pay or reject.",
    name: "Invoice approval",
    theme: "light",
    format: "png",
  }),
});
const generation = await res.json();
console.log(generation.id, generation.status); // gen_..., "queued"

import os
import requests

res = requests.post(
    "https://justflow.it/api/v1/diagrams/generate",
    headers={"Authorization": f"Bearer {os.environ['JFI_API_KEY']}"},
    json={
        "prompt": "An invoice approval process: receive invoice, validate, "
        "route to manager for approval, then pay or reject.",
        "name": "Invoice approval",
        "theme": "light",
        "format": "png",
    },
)
res.raise_for_status()
generation = res.json()
print(generation["id"], generation["status"])  # gen_..., "queued"

The request returns 202 Accepted with a Generation in the queued state, plus a Location header pointing to the poll URL and a Retry-After hint:

{
  "object": "generation",
  "id": "gen_4a7c2f9e8b1d",
  "status": "queued",
  "diagram": null,
  "image_url": null,
  "error": null,
  "created_at": "2026-06-07T09:15:00Z"
}

Now poll GET /v1/generations/{id} until status becomes succeeded (or failed). Honor the Retry-After hint between polls.

curl https://justflow.it/api/v1/generations/gen_4a7c2f9e8b1d \
  -H "Authorization: Bearer $JFI_API_KEY"

async function poll(id) {
  while (true) {
    const res = await fetch(
      `https://justflow.it/api/v1/generations/${id}`,
      { headers: { Authorization: `Bearer ${process.env.JFI_API_KEY}` } }
    );
    const gen = await res.json();
    if (gen.status === "succeeded") return gen;
    if (gen.status === "failed") throw new Error(gen.error.message);
    await new Promise((r) => setTimeout(r, 2000));
  }
}

const done = await poll("gen_4a7c2f9e8b1d");
console.log(done.image_url);

import os
import time
import requests

def poll(generation_id):
    url = f"https://justflow.it/api/v1/generations/{generation_id}"
    headers = {"Authorization": f"Bearer {os.environ['JFI_API_KEY']}"}
    while True:
        gen = requests.get(url, headers=headers).json()
        if gen["status"] == "succeeded":
            return gen
        if gen["status"] == "failed":
            raise RuntimeError(gen["error"]["message"])
        time.sleep(2)

done = poll("gen_4a7c2f9e8b1d")
print(done["image_url"])

When the job succeeds, the 200 response populates diagram (the created, saved diagram) and image_url (the rendered image in the requested theme and format):

{
  "object": "generation",
  "id": "gen_4a7c2f9e8b1d",
  "status": "succeeded",
  "diagram": {
    "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"
  },
  "image_url": "/api/v1/diagrams/c4e8a1b2-5d6f-4a9c-8e30-1b2c3d4e5f60/image?theme=light&format=png",
  "error": null,
  "created_at": "2026-06-07T09:15:00Z"
}

Already have a saved diagram and just need an image (or a different theme)? Call GET /v1/diagrams/{id}/image directly — it renders on demand and is cached, with no generation quota cost.

Next steps

Authentication

Key formats, the live vs test prefix, and the full list of scopes.

Errors

The error envelope, every type/code pairing, and X-Request-Id tracing.

Rate limits

The 120-req/60s burst, the 500-generations/30-day quota, and RateLimit-* headers.

Diagrams API

List, create, read, update, delete diagrams and render images on demand.

Getting started

Core concepts

Endpoints

Next steps

Authentication

Errors

Rate limits

Diagrams API

​Next steps

Authentication

Errors

Rate limits

Diagrams API

Next steps