Introduction

The Just Flow It API lets you build Just Flow It into your own systems. Manage your diagrams and folders, and turn plain-language descriptions of a process into ready-to-use BPMN diagrams — complete with rendered images — all over a clean REST interface. Everything is JSON over HTTPS, organized around predictable, resource-oriented URLs, standard HTTP verbs, and conventional status codes.

Quickstart

Create your first key and make a request in a few minutes.

Authentication

How API keys, Bearer auth, and scopes work.

API Reference

Every endpoint, parameter, and response shape.

Generate diagrams

Describe a process in words, get a diagram back.

Base URL

All endpoints are reached at a single base URL. Every request must use HTTPS.

https://justflow.it/api/v1

What you can do

Diagrams

Create diagrams from a natural-language prompt or by importing standard BPMN 2.0, organize them in folders, and export back to BPMN 2.0.

Folders

Organize diagrams into nestable folders, each with optional AI-steering context.

Generation

Generate a brand-new diagram from a natural-language prompt, then fetch a rendered PNG or SVG image in a light or dark theme.

You can also render any saved diagram to an image on demand — re-theme it light or dark, as PNG or SVG — without regenerating it.

Who can use it

The API is available on paid plans only.

Pro — personal key

A Pro user gets a personal key that acts on their own personal diagrams and folders.

Team — org key

A member of a Team organization gets an org key that acts on that organization’s diagrams and folders.

Free plans cannot use the API. Calls authenticated with a key that lacks an eligible plan return 403 with code plan_required.

Keys are created and revoked in the web app dashboard under Settings → API keys. The secret is shown in plaintext once at creation — copy it then, because only a SHA-256 hash is stored server-side.

Server-to-server only

API keys grant full access to your account’s diagrams and folders. They must never be exposed in a browser or client-side application. The API does not enable CORS — it is designed for server-to-server use only. Keep keys in a secret manager or server environment variables.

Making a request

Authenticate every request with your secret key in the Authorization header using the Bearer scheme.

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

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

import requests

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

A successful list response is cursor-paginated, newest first:

{
  "data": [
    {
      "object": "diagram",
      "id": "3f1c2b8a-9d4e-4a21-bc7f-1e2d3c4b5a6f",
      "name": "Customer onboarding",
      "folder_id": null,
      "organization_id": null,
      "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2026-06-07T10:00:00Z",
      "updated_at": "2026-06-07T10:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Key concepts

Scopes

Each key holds a subset of scopes. A request missing a required scope returns 403 with code insufficient_scope.

Scope	Grants
`diagrams:read`	Read diagrams and render their images
`diagrams:write`	Create, update, and delete diagrams
`folders:read`	Read folders
`folders:write`	Create, update, and delete folders
`generate`	Generate diagrams from a prompt

See Authentication for details.

Pagination

List endpoints are cursor-based.

integer

Number of items per page, 1–100. Defaults to 20.

string

Opaque cursor from a previous response. To get the next page, pass next_cursor as cursor.

Each response includes:

array

The page of resources, newest first (created_at descending).

boolean

Whether more results exist after this page.

string | null

The cursor to fetch the next page, or null when there are no more.

An invalid or expired cursor returns 400 with code invalid_cursor.

Rate limits & quotas

Limits are applied per key:

Burst: 120 requests per 60 seconds.
AI generation quota: 500 generations per rolling 30 days.

Every response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (seconds) headers. On a 429, a Retry-After (seconds) header is included.Rate-limit errors use type rate_limit_error with code rate_limit_exceeded or quota_exceeded.

Errors

Every error response uses the same envelope:

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "The API key is missing the required scope.",
    "param": null
  },
  "request_id": "req_8f2a1c9d4e3b"
}

Every response includes an X-Request-Id header; 401 responses also include WWW-Authenticate: Bearer.

`error.type`	HTTP	Codes
`invalid_request_error`	400	`invalid_json`, `missing_parameter`, `invalid_parameter`, `payload_too_large`, `invalid_cursor`
`authentication_error`	401	`missing_api_key`, `invalid_api_key`, `revoked_api_key`, `expired_api_key`
`permission_error`	403	`plan_required`, `insufficient_scope`
`not_found_error`	404	`resource_not_found`
`conflict_error`	409	—
`validation_error`	422	`validation_failed`
`rate_limit_error`	429	`rate_limit_exceeded`, `quota_exceeded`
`api_error`	500	`internal_error`

Live keys (jfi_sk_live_...) target production; test keys (jfi_sk_test_...) target staging. Both use the same base URL and behave identically.

Next steps

Quickstart

Get a key and make your first call.

Authentication

Bearer auth, scopes, and key safety.

API Reference

Full endpoint documentation.

Getting started

Core concepts

Endpoints

Quickstart

Authentication

API Reference

Generate diagrams

Base URL

What you can do

Diagrams

Folders

Generation

Who can use it

Pro — personal key

Team — org key

Server-to-server only

Making a request

Key concepts

Next steps

Quickstart

Authentication

API Reference

Quickstart

Authentication

API Reference

Generate diagrams

​Base URL

​What you can do

Diagrams

Folders

Generation

​Who can use it

Pro — personal key

Team — org key

​Server-to-server only

​Making a request

​Key concepts

​Next steps

Quickstart

Authentication

API Reference

Base URL

What you can do

Who can use it

Server-to-server only

Making a request

Key concepts

Next steps