Folders

Folders organize your diagrams. They nest into trees through parent_id, and each folder can hold an optional context string that steers AI generation for diagrams created inside it.

All requests run server-to-server over HTTPS and authenticate with an API key. Never expose a key in a browser or client app. See Authentication for details.

The Folder object

string

Always "folder".

string

UUID of the folder.

string

Display name of the folder.

string | null

UUID of the parent folder, or null if the folder lives at the root. This is how folders nest.

string | null

Optional free-text context used to steer AI generation for diagrams in this folder. null when unset.

string | null

UUID of the owning organization for org keys, or null for personal keys.

string

ISO-8601 UTC timestamp of creation.

string

ISO-8601 UTC timestamp of the last update.

The Folder object

{
  "object": "folder",
  "id": "8b1f6c2e-3a4d-4e9b-9c1a-2f7d8e0a5b3c",
  "name": "Onboarding processes",
  "parent_id": null,
  "context": "Customer onboarding for a B2B SaaS. Prefer swimlanes per department.",
  "organization_id": null,
  "created_at": "2026-06-01T12:00:00Z",
  "updated_at": "2026-06-01T12:00:00Z"
}

Endpoints

List folders

GET /v1/folders

Create a folder

POST /v1/folders

Retrieve a folder

GET /v1/folders/{id}

Update a folder

PATCH /v1/folders/{id}

Delete a folder

DELETE /v1/folders/{id}

List folders

GET /v1/folders

Returns a cursor-paginated list of folders, newest first (created_at descending). Requires the folders:read scope.

Query parameters

integer

Number of folders to return. Integer between 1 and 100. Defaults to 20.

string

Opaque pagination cursor. Pass the next_cursor from a previous response to fetch the next page. An invalid or expired cursor returns 400 invalid_cursor.

Response

array

Array of Folder objects.

boolean

true if more folders are available beyond this page.

string | null

Cursor to pass as cursor for the next page, or null on the last page.

curl https://justflow.it/api/v1/folders?limit=20 \
  -H "Authorization: Bearer jfi_sk_live_..."

const res = await fetch("https://justflow.it/api/v1/folders?limit=20", {
  headers: { Authorization: "Bearer jfi_sk_live_..." },
});
const page = await res.json();

import requests

res = requests.get(
    "https://justflow.it/api/v1/folders",
    params={"limit": 20},
    headers={"Authorization": "Bearer jfi_sk_live_..."},
)
page = res.json()

200 OK

{
  "data": [
    {
      "object": "folder",
      "id": "8b1f6c2e-3a4d-4e9b-9c1a-2f7d8e0a5b3c",
      "name": "Onboarding processes",
      "parent_id": null,
      "context": "Customer onboarding for a B2B SaaS. Prefer swimlanes per department.",
      "organization_id": null,
      "created_at": "2026-06-01T12:00:00Z",
      "updated_at": "2026-06-01T12:00:00Z"
    },
    {
      "object": "folder",
      "id": "1d2c3b4a-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Q2 audit subprocesses",
      "parent_id": "8b1f6c2e-3a4d-4e9b-9c1a-2f7d8e0a5b3c",
      "context": null,
      "organization_id": null,
      "created_at": "2026-05-28T09:15:00Z",
      "updated_at": "2026-05-28T09:15:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

To walk every page, keep calling with cursor=next_cursor until has_more is false.

Create a folder

POST /v1/folders

Creates a new folder. Requires the folders:write scope. Returns 201 Created with a Location header pointing at the new folder.

Body parameters

string

required

Display name of the folder.

string | null

UUID of the parent folder to nest under. Omit or set to null to create the folder at the root.

string

Optional free-text context that steers AI generation for diagrams created inside this folder.

curl https://justflow.it/api/v1/folders \
  -H "Authorization: Bearer jfi_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding processes",
    "parent_id": null,
    "context": "Customer onboarding for a B2B SaaS. Prefer swimlanes per department."
  }'

const res = await fetch("https://justflow.it/api/v1/folders", {
  method: "POST",
  headers: {
    Authorization: "Bearer jfi_sk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Onboarding processes",
    parent_id: null,
    context:
      "Customer onboarding for a B2B SaaS. Prefer swimlanes per department.",
  }),
});
const folder = await res.json();

import requests

res = requests.post(
    "https://justflow.it/api/v1/folders",
    headers={
        "Authorization": "Bearer jfi_sk_live_...",
        "Content-Type": "application/json",
    },
    json={
        "name": "Onboarding processes",
        "parent_id": None,
        "context": "Customer onboarding for a B2B SaaS. Prefer swimlanes per department.",
    },
)
folder = res.json()

201 Created

{
  "object": "folder",
  "id": "8b1f6c2e-3a4d-4e9b-9c1a-2f7d8e0a5b3c",
  "name": "Onboarding processes",
  "parent_id": null,
  "context": "Customer onboarding for a B2B SaaS. Prefer swimlanes per department.",
  "organization_id": null,
  "created_at": "2026-06-01T12:00:00Z",
  "updated_at": "2026-06-01T12:00:00Z"
}

Use context to pass domain knowledge once (industry, conventions, terminology) so every diagram generated into the folder inherits that steering.

Retrieve a folder

GET /v1/folders/{id}

Returns a single folder by id. Requires the folders:read scope. An unknown id returns 404 resource_not_found.

Path parameters

string

required

UUID of the folder to retrieve.

curl https://justflow.it/api/v1/folders/8b1f6c2e-3a4d-4e9b-9c1a-2f7d8e0a5b3c \
  -H "Authorization: Bearer jfi_sk_live_..."

const id = "8b1f6c2e-3a4d-4e9b-9c1a-2f7d8e0a5b3c";
const res = await fetch(`https://justflow.it/api/v1/folders/${id}`, {
  headers: { Authorization: "Bearer jfi_sk_live_..." },
});
const folder = await res.json();

import requests

folder_id = "8b1f6c2e-3a4d-4e9b-9c1a-2f7d8e0a5b3c"
res = requests.get(
    f"https://justflow.it/api/v1/folders/{folder_id}",
    headers={"Authorization": "Bearer jfi_sk_live_..."},
)
folder = res.json()

200 OK

{
  "object": "folder",
  "id": "8b1f6c2e-3a4d-4e9b-9c1a-2f7d8e0a5b3c",
  "name": "Onboarding processes",
  "parent_id": null,
  "context": "Customer onboarding for a B2B SaaS. Prefer swimlanes per department.",
  "organization_id": null,
  "created_at": "2026-06-01T12:00:00Z",
  "updated_at": "2026-06-01T12:00:00Z"
}

Update a folder

PATCH /v1/folders/{id}

Updates the supplied fields on a folder. Requires the folders:write scope. Send any subset of the body fields; omitted fields are left unchanged. Returns 200 OK with the updated folder.

Path parameters

string

required

UUID of the folder to update.

Body parameters

string

New display name.

string

New AI-steering context.

string | null

New parent folder UUID, or null to move the folder to the root.

curl -X PATCH https://justflow.it/api/v1/folders/8b1f6c2e-3a4d-4e9b-9c1a-2f7d8e0a5b3c \
  -H "Authorization: Bearer jfi_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Onboarding (2026)", "parent_id": null }'

const id = "8b1f6c2e-3a4d-4e9b-9c1a-2f7d8e0a5b3c";
const res = await fetch(`https://justflow.it/api/v1/folders/${id}`, {
  method: "PATCH",
  headers: {
    Authorization: "Bearer jfi_sk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Onboarding (2026)", parent_id: null }),
});
const folder = await res.json();

import requests

folder_id = "8b1f6c2e-3a4d-4e9b-9c1a-2f7d8e0a5b3c"
res = requests.patch(
    f"https://justflow.it/api/v1/folders/{folder_id}",
    headers={
        "Authorization": "Bearer jfi_sk_live_...",
        "Content-Type": "application/json",
    },
    json={"name": "Onboarding (2026)", "parent_id": None},
)
folder = res.json()

200 OK

{
  "object": "folder",
  "id": "8b1f6c2e-3a4d-4e9b-9c1a-2f7d8e0a5b3c",
  "name": "Onboarding (2026)",
  "parent_id": null,
  "context": "Customer onboarding for a B2B SaaS. Prefer swimlanes per department.",
  "organization_id": null,
  "created_at": "2026-06-01T12:00:00Z",
  "updated_at": "2026-06-07T10:42:00Z"
}

Delete a folder

DELETE /v1/folders/{id}

Deletes a folder. Requires the folders:write scope. Returns 204 No Content with an empty body.

Path parameters

string

required

UUID of the folder to delete.

curl -X DELETE https://justflow.it/api/v1/folders/8b1f6c2e-3a4d-4e9b-9c1a-2f7d8e0a5b3c \
  -H "Authorization: Bearer jfi_sk_live_..."

const id = "8b1f6c2e-3a4d-4e9b-9c1a-2f7d8e0a5b3c";
const res = await fetch(`https://justflow.it/api/v1/folders/${id}`, {
  method: "DELETE",
  headers: { Authorization: "Bearer jfi_sk_live_..." },
});
// res.status === 204

import requests

folder_id = "8b1f6c2e-3a4d-4e9b-9c1a-2f7d8e0a5b3c"
res = requests.delete(
    f"https://justflow.it/api/v1/folders/{folder_id}",
    headers={"Authorization": "Bearer jfi_sk_live_..."},
)
# res.status_code == 204

204 No Content

HTTP/1.1 204 No Content
X-Request-Id: req_8f3c2a1b9d7e

Errors

Every error uses the standard envelope. The type maps to the HTTP status, and every response carries an X-Request-Id header (mirrored as request_id in the body).

Error envelope

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "Missing required parameter: name.",
    "param": "name"
  },
  "request_id": "req_8f3c2a1b9d7e"
}

400 — invalid_request_error

Codes: invalid_json, missing_parameter, invalid_parameter, payload_too_large, invalid_cursor. Returned when name is missing on create, a field is malformed, or a pagination cursor is invalid or expired.

401 — authentication_error

Codes: missing_api_key, invalid_api_key, revoked_api_key, expired_api_key. Responses include a WWW-Authenticate: Bearer header.

403 — permission_error

Codes: plan_required (the API is paid-plans only), insufficient_scope (the key lacks folders:read or folders:write).

404 — not_found_error

Code: resource_not_found. The folder id does not exist or is not accessible to your key.

429 — rate_limit_error

Codes: rate_limit_exceeded, quota_exceeded. Responses include a Retry-After header (seconds). The per-key burst limit is 120 requests / 60s.

500 — api_error

Code: internal_error. Something failed on our side. Retry with backoff and include the request_id if you contact support.

Folder endpoints fail with 403 insufficient_scope if your key is missing the right scope: reads need folders:read, writes (create / update / delete) need folders:write.

Getting started

Core concepts

Endpoints

The Folder object

Endpoints

List folders

Create a folder

Retrieve a folder

Update a folder

Delete a folder

List folders

Query parameters

Response

Create a folder

Body parameters

Retrieve a folder

Path parameters

Update a folder

Path parameters

Body parameters

Delete a folder

Path parameters

Errors

​The Folder object

​Endpoints

List folders

Create a folder

Retrieve a folder

Update a folder

Delete a folder

​List folders

​Query parameters

​Response

​Create a folder

​Body parameters

​Retrieve a folder

​Path parameters

​Update a folder

​Path parameters

​Body parameters

​Delete a folder

​Path parameters

​Errors

The Folder object

Endpoints

List folders

Query parameters

Response

Create a folder

Body parameters

Retrieve a folder

Path parameters

Update a folder

Path parameters

Body parameters

Delete a folder

Path parameters

Errors