Skip to main content
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

​
object
string
Always "folder".
​
id
string
UUID of the folder.
​
name
string
Display name of the folder.
​
parent_id
string | null
UUID of the parent folder, or null if the folder lives at the root. This is how folders nest.
​
context
string | null
Optional free-text context used to steer AI generation for diagrams in this folder. null when unset.
​
organization_id
string | null
UUID of the owning organization for org keys, or null for personal keys.
​
created_at
string
ISO-8601 UTC timestamp of creation.
​
updated_at
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

​
limit
integer
Number of folders to return. Integer between 1 and 100. Defaults to 20.
​
cursor
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

​
data
array
Array of Folder objects.
​
has_more
boolean
true if more folders are available beyond this page.
​
next_cursor
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_..."
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

​
name
string
required
Display name of the folder.
​
parent_id
string | null
UUID of the parent folder to nest under. Omit or set to null to create the folder at the root.
​
context
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."
  }'
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

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

​
id
string
required
UUID of the folder to update.

​
Body parameters

​
name
string
New display name.
​
context
string
New AI-steering context.
​
parent_id
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 }'
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

​
id
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_..."
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"
}
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.
Codes: missing_api_key, invalid_api_key, revoked_api_key, expired_api_key. Responses include a WWW-Authenticate: Bearer header.
Codes: plan_required (the API is paid-plans only), insufficient_scope (the key lacks folders:read or folders:write).
Code: resource_not_found. The folder id does not exist or is not accessible to your key.
Codes: rate_limit_exceeded, quota_exceeded. Responses include a Retry-After header (seconds). The per-key burst limit is 120 requests / 60s.
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.