> ## Documentation Index
> Fetch the complete documentation index at: https://docs.justflow.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Programmatically manage diagrams and folders and generate BPMN process diagrams from natural language with the Just Flow It API.

The **Just Flow It API** lets you build [Just Flow It](https://justflow.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.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/api-reference/quickstart">
    Create your first key and make a request in a few minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    How API keys, Bearer auth, and scopes work.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/diagrams">
    Every endpoint, parameter, and response shape.
  </Card>

  <Card title="Generate diagrams" icon="wand-magic-sparkles" href="/api-reference/diagrams">
    Describe a process in words, get a diagram back.
  </Card>
</CardGroup>

## 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

<CardGroup cols={3}>
  <Card title="Diagrams" icon="diagram-project">
    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.
  </Card>

  <Card title="Folders" icon="folder">
    Organize diagrams into nestable folders, each with optional AI-steering context.
  </Card>

  <Card title="Generation" icon="sparkles">
    Generate a brand-new diagram from a natural-language prompt, then fetch a rendered PNG or SVG image in a light or dark theme.
  </Card>
</CardGroup>

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**.

<CardGroup cols={2}>
  <Card title="Pro — personal key" icon="user">
    A Pro user gets a **personal key** that acts on their own personal diagrams and folders.
  </Card>

  <Card title="Team — org key" icon="users">
    A member of a Team organization gets an **org key** that acts on that organization's diagrams and folders.
  </Card>
</CardGroup>

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

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

<Warning>
  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.
</Warning>

## Making a request

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

<CodeGroup>
  ```bash curl theme={null}
  curl https://justflow.it/api/v1/diagrams \
    -H "Authorization: Bearer jfi_sk_live_..."
  ```

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

  ```python Python (requests) theme={null}
  import requests

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

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

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Scopes" icon="shield-halved">
    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](/api-reference/authentication) for details.
  </Accordion>

  <Accordion title="Pagination" icon="list">
    List endpoints are cursor-based.

    <ParamField query="limit" type="integer">
      Number of items per page, `1`–`100`. Defaults to `20`.
    </ParamField>

    <ParamField query="cursor" type="string">
      Opaque cursor from a previous response. To get the next page, pass `next_cursor` as `cursor`.
    </ParamField>

    Each response includes:

    <ResponseField name="data" type="array">
      The page of resources, newest first (`created_at` descending).
    </ResponseField>

    <ResponseField name="has_more" type="boolean">
      Whether more results exist after this page.
    </ResponseField>

    <ResponseField name="next_cursor" type="string | null">
      The cursor to fetch the next page, or `null` when there are no more.
    </ResponseField>

    An invalid or expired cursor returns `400` with code `invalid_cursor`.
  </Accordion>

  <Accordion title="Rate limits & quotas" icon="gauge-high">
    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`.
  </Accordion>

  <Accordion title="Errors" icon="triangle-exclamation">
    Every error response uses the same envelope:

    ```json theme={null}
    {
      "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`                                                                                |
  </Accordion>
</AccordionGroup>

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

## Next steps

<CardGroup cols={3}>
  <Card title="Quickstart" icon="rocket" href="/api-reference/quickstart">
    Get a key and make your first call.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Bearer auth, scopes, and key safety.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/diagrams">
    Full endpoint documentation.
  </Card>
</CardGroup>