Introduction - Just Flow It

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_..."

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.

limit

integer

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

cursor

string

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

Each response includes:

data

array

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

has_more

boolean

Whether more results exist after this page.

next_cursor

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.

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