Diagram images

Every diagram you store in Just Flow It can be rendered to an image. There are two ways to get one:

On-demand image endpoint

GET /v1/diagrams/{id}/image — render any saved diagram to PNG or SVG, in light or dark theme, at any time.

image_url from a generation

When a POST /v1/diagrams/generate job reaches status: "succeeded", the resulting Generation carries an image_url rendered with the theme/format you requested.

When to use which

Use the image endpoint when…

You already have a diagram id and want its picture — for example to display an existing diagram, re-theme it (light ↔ dark), or switch format (PNG ↔ SVG). It does not call the AI model and does not count against your generation quota.

Use image_url when…

You just generated a brand-new diagram and want the rendered image that matches the theme/format you asked for, without a second round trip. It is only present once the generation has status: "succeeded".

Both paths render the same saved diagram. If you need a different theme or format than the one a generation produced, call the image endpoint on the new diagram’s id — no need to regenerate.

Get an image on demand

GET /v1/diagrams/{id}/image

Renders the saved diagram to an image on demand. Requires the diagrams:read scope.

string

required

The UUID of the diagram to render.

string

default:"light"

Color theme of the rendered image. One of light or dark.

string

default:"png"

Image format. One of png or svg.

Request

curl -L "https://justflow.it/api/v1/diagrams/d290f1ee-6c54-4b01-90e6-d701748f0851/image?theme=dark&format=png" \
  -H "Authorization: Bearer jfi_sk_live_..." \
  -o diagram.png

const res = await fetch(
  "https://justflow.it/api/v1/diagrams/d290f1ee-6c54-4b01-90e6-d701748f0851/image?theme=dark&format=png",
  { headers: { Authorization: "Bearer jfi_sk_live_..." } }
);

if (!res.ok) {
  throw new Error(`Image request failed: ${res.status}`);
}

const buffer = Buffer.from(await res.arrayBuffer());
// e.g. fs.writeFileSync("diagram.png", buffer)

import requests

res = requests.get(
    "https://justflow.it/api/v1/diagrams/d290f1ee-6c54-4b01-90e6-d701748f0851/image",
    params={"theme": "dark", "format": "png"},
    headers={"Authorization": "Bearer jfi_sk_live_..."},
)
res.raise_for_status()

with open("diagram.png", "wb") as f:
    f.write(res.content)

Response

image

The rendered diagram image (or a link to it), in the requested theme and format. The response carries the standard X-Request-Id and RateLimit-* headers.

The image endpoint never calls the AI model and does not consume your monthly generation quota. It is still subject to the per-key burst limit (120 requests / 60s).

Errors

404 — unknown diagram

A diagram id that doesn’t exist (or isn’t visible to your key) returns not_found_error / resource_not_found.

{
  "error": {
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "Diagram not found."
  },
  "request_id": "req_8f2c1a9b"
}

400 — invalid theme or format

An unsupported theme or format value returns invalid_request_error / invalid_parameter, with param naming the offending query parameter.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "format must be one of: png, svg.",
    "param": "format"
  },
  "request_id": "req_3d77e0a4"
}

403 — missing scope

A key without the diagrams:read scope returns permission_error / insufficient_scope.

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

`image_url` from a generation

When you create a diagram from natural language with POST /v1/diagrams/generate, the job runs asynchronously. You poll GET /v1/generations/{id} until it finishes. On success, the Generation object includes both the saved diagram and an image_url rendered with the theme and format you requested at generation time.

Start the generation

POST /v1/diagrams/generate with your prompt (and optional theme, format, name, folder_id) returns 202 Accepted with status: "queued" and a Location header pointing at the generation.

Poll until succeeded

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

Read image_url

On success, image_url is populated alongside the created diagram.

A succeeded generation looks like this:

{
  "object": "generation",
  "id": "gen_5f9a2b3c4d",
  "status": "succeeded",
  "diagram": {
    "object": "diagram",
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "name": "Customer onboarding",
    "folder_id": null,
    "organization_id": null,
    "created_by": "a1b2c3d4-0000-0000-0000-000000000000",
    "created_at": "2026-06-07T12:00:05Z",
    "updated_at": "2026-06-07T12:00:05Z"
  },
  "image_url": "/api/v1/diagrams/d290f1ee-6c54-4b01-90e6-d701748f0851/image?theme=light&format=png",
  "error": null,
  "created_at": "2026-06-07T12:00:00Z"
}

string | null

The rendered image for the generated diagram, in the theme/format requested on the generate call. null until the job reaches status: "succeeded". It is a path relative to the API base (https://justflow.it) — prepend the base to fetch it, e.g. https://justflow.it{image_url}.

Don’t read image_url (or diagram) before the job succeeds — both are null while status is queued or processing, and on failed you’ll instead find details in error.

Embedding the image

Because API keys are server-side only (no CORS, never exposed in a browser), don’t point an <img src> directly at the endpoint with a key attached. Instead, fetch the bytes on your server and serve or store them yourself.

import { writeFile } from "node:fs/promises";

async function fetchDiagramImage(id, { theme = "light", format = "png" } = {}) {
  const url = new URL(`https://justflow.it/api/v1/diagrams/${id}/image`);
  url.searchParams.set("theme", theme);
  url.searchParams.set("format", format);

  const res = await fetch(url, {
    headers: { Authorization: "Bearer jfi_sk_live_..." },
  });
  if (!res.ok) throw new Error(`Image request failed: ${res.status}`);

  return Buffer.from(await res.arrayBuffer());
}

const png = await fetchDiagramImage("d290f1ee-6c54-4b01-90e6-d701748f0851", {
  theme: "dark",
});
await writeFile("onboarding.png", png);
// Now serve onboarding.png from your own CDN / static host and embed it:
//   <img src="/assets/onboarding.png" alt="Customer onboarding" />

import requests

res = requests.get(
    "https://justflow.it/api/v1/diagrams/d290f1ee-6c54-4b01-90e6-d701748f0851/image",
    params={"theme": "light", "format": "svg"},
    headers={"Authorization": "Bearer jfi_sk_live_..."},
)
res.raise_for_status()

svg_markup = res.text  # inline this into your own HTML, server-side

Pick svg when you want crisp scaling or to inline the markup into a page; pick png when you need a flat raster for email, slides, or thumbnails.

Getting started

Core concepts

Endpoints

On-demand image endpoint

image_url from a generation

When to use which

Use the image endpoint when…

Use image_url when…

Get an image on demand

Request

Response

Errors

`image_url` from a generation

Embedding the image

On-demand image endpoint

image_url from a generation

​When to use which

Use the image endpoint when…

Use image_url when…

​Get an image on demand

​Request

​Response

​Errors

​image_url from a generation

​Embedding the image

When to use which

Get an image on demand

Request

Response

Errors

`image_url` from a generation

Embedding the image