Pagination

All list endpoints in the Just Flow It API (such as GET /v1/diagrams and GET /v1/folders) use cursor-based pagination. Instead of page numbers, you fetch results in batches and follow an opaque next_cursor to walk forward through the collection.

Results are always ordered newest first (created_at descending).

Query parameters

integer

default:"20"

How many items to return per page. Must be between 1 and 100. Defaults to 20.

string

An opaque pagination token. Omit it on the first request. To fetch the next page, pass the next_cursor value returned by the previous response.

The list envelope

Every paginated response wraps the results in a consistent envelope:

array

The array of resource objects for this page. Each item carries its own object discriminator (for example "diagram" or "folder").

boolean

true if there are more items beyond this page, false if this is the last page.

string | null

The cursor to pass as cursor on your next request to retrieve the following page. It is null when has_more is false.

Example response

{
  "data": [
    {
      "object": "diagram",
      "id": "3f9c2b1a-7d4e-4a2c-9b6f-1e8d5c0a2f31",
      "name": "Onboarding flow",
      "folder_id": null,
      "organization_id": null,
      "created_by": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "created_at": "2026-06-07T14:21:09Z",
      "updated_at": "2026-06-07T14:21:09Z"
    }
  ],
  "has_more": true,
  "next_cursor": "ZXlKamNtVmhkR1ZrWDJGMElqb2lNakF5Tmkwd05pMHdOMVF4TkRveU1Ub3dPVm9p"
}

Fetching a single page

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

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

const page = await res.json();
console.log(page.data);        // array of diagrams
console.log(page.has_more);    // boolean
console.log(page.next_cursor); // cursor for the next page (or null)

import requests

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

page = res.json()
print(page["data"])        # list of diagrams
print(page["has_more"])    # bool
print(page["next_cursor"]) # cursor for the next page (or None)

Looping through every page

To retrieve a full collection, keep requesting while has_more is true, passing the previous next_cursor as the next cursor.

Request the first page

Call the list endpoint with your desired limit and no cursor.

Process the data

Handle the items in data.

Check has_more

If has_more is false, you’ve reached the end. Otherwise continue.

Follow next_cursor

Request the next page with cursor set to the previous response’s next_cursor, and repeat from step 2.

async function listAllDiagrams() {
  const all = [];
  let cursor = null;

  do {
    const url = new URL("https://justflow.it/api/v1/diagrams");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const res = await fetch(url, {
      headers: { Authorization: "Bearer jfi_sk_live_..." },
    });

    const page = await res.json();
    all.push(...page.data);
    cursor = page.next_cursor;

    // Loop while there are more pages
    if (!page.has_more) break;
  } while (cursor);

  return all;
}

import requests

def list_all_diagrams():
    items = []
    cursor = None

    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor

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

        page = res.json()
        items.extend(page["data"])
        cursor = page["next_cursor"]

        if not page["has_more"]:
            break

    return items

Use the largest limit (100) when bulk-syncing to minimize the number of round trips. Keep your loop driven by has_more rather than by an empty data array.

Invalid or expired cursors

Cursors are opaque tokens — never construct, modify, or persist them across long periods. If you pass a malformed or expired cursor, the API responds with 400 and an invalid_cursor error.

Always start a fresh traversal from the first page (no cursor) rather than reusing a stale next_cursor from an earlier run.

400 Bad Request

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_cursor",
    "message": "The supplied cursor is invalid or has expired.",
    "param": "cursor"
  },
  "request_id": "req_8Kt2yq4vN1aBc3De"
}

Why cursor-based instead of page numbers?

Cursor pagination stays correct even when items are created or deleted between requests, since each cursor encodes a stable position in the created_at desc ordering. Offset/page-number pagination can skip or duplicate items when the underlying collection changes mid-traversal.

Getting started

Core concepts

Endpoints

Query parameters

The list envelope

Example response

Fetching a single page

Looping through every page

Invalid or expired cursors

​Query parameters

​The list envelope

​Example response

​Fetching a single page

​Looping through every page

​Invalid or expired cursors

Query parameters

The list envelope

Example response

Fetching a single page

Looping through every page

Invalid or expired cursors