Flowral API v1.0.0

Start a first-party sign-in (authorization code + PKCE)

Browser-facing, not meant to be called by anything but a user-agent. Validates the request and redirects to the Flowral app's own sign-in screen; once the person signs in and allows the connection there, the app redirects on to redirect_uri with a one-time code. POST /oauth/token's authorization_code grant exchanges it for a token. client_id must name a registered first-party client (currently flowral-vscode) and redirect_uri must be a loopback address it owns.

Query

Responses

Exchange credentials for an access token

Three grants, all application/x-www-form-urlencoded: - client_credentials — a workspace credential's id/secret. May also be sent as HTTP Basic. - authorization_code — the code from /oauth/authorize, with the PKCE code_verifier. Issues a token that acts as the person who signed in, not a workspace credential — plus a refresh_token, since a person has no secret to silently re-present an hour later. - refresh_token — trades the refresh token from an authorization_code grant for a new access/refresh pair. Rotated: the old refresh token stops working the moment this succeeds. Pass org_id to move to a DIFFERENT workspace the same person belongs to, without a second trip through the browser — checked fresh against live membership, same as a new sign-in would be. Either way the token is a bearer token for this API and nothing else — it is not a planner session and cannot be used against the app.

Body application/x-www-form-urlencoded

Responses

Example

curl -X POST 'https://api.flowral.app/v1/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=fl_id_…&client_secret=fl_cs_…'

{
  "access_token": "fl_at_9c2f…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "flows:read flows:write work:write"
}

Revoke an access token

RFC 7009. Kills one issued token immediately. To kill the credential itself, delete it in the app — that also invalidates every token it ever issued.

Body application/x-www-form-urlencoded

Responses

Who this credential is

The workspace, the credential's role and scopes, and the plan. Cheap, and the right health check for an integration. For a person-token (authorization_code), also includes userId — the same id GET /team/members lists them under, for a client that wants "assign to me"/"my work" to work without asking the person to pick themselves out of their own team — and orgs: every workspace they belong to, for a client that wants to offer a "switch workspace" action (see POST /oauth/token's refresh_token grant). Unlike every other /v1 route, this one is NOT refused on a Free-plan workspace — it reports plan: "free" truthfully instead, which is what lets a client explain the refusal (or, for a person-token, offer switching to a different workspace) rather than just receiving one.

Responses

Example

curl 'https://api.flowral.app/v1/me' \
  -H 'Authorization: Bearer fl_sk_live_…'

{
  "workspaceId": "org_5c1",
  "workspaceName": "Acme Studio",
  "credentialId": "key_8fd2",
  "credentialName": "Acme CI",
  "role": "member",
  "scopes": [
    "flows:read",
    "flows:write",
    "work:write"
  ],
  "plan": "pro"
}

List flows

Flows in the workspace, newest first. Archived flows are excluded unless archived=true.

Scopes: flows:read

Query

Responses

Example

curl 'https://api.flowral.app/v1/flows?size=2' \
  -H 'Authorization: Bearer fl_sk_live_…'

{
  "total": 2,
  "items": [
    {
      "id": "flw_2b8e10",
      "name": "Acme: Website relaunch",
      "archived": false,
      "taskCount": 14,
      "doneCount": 6,
      "readyCount": 2,
      "dueDate": "2026-09-14T00:00:00.000Z"
    },
    {
      "id": "flw_77a301",
      "name": "Northwind: Brand refresh",
      "archived": false,
      "taskCount": 9,
      "doneCount": 9,
      "readyCount": 0,
      "dueDate": null
    }
  ]
}

Create a flow

Creates a flow and, optionally, its whole task graph in one call. A task's after references other tasks by index in this request, so the dependency chain arrives with the flow rather than in follow-up calls. Cycles are refused outright.

Scopes: flows:write · Role: member or higher

Body application/json

Responses

Example

curl -X POST 'https://api.flowral.app/v1/flows' \
  -H 'Authorization: Bearer fl_sk_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Acme: Website relaunch","dueDate":"2026-09-14","tasks":[{"name":"Brief"},{"name":"Design","after":[0]},{"name":"Client approval","after":[1]}]}'

{
  "id": "flw_2b8e10",
  "name": "Acme: Website relaunch",
  "archived": false,
  "dueDate": "2026-09-14T00:00:00.000Z",
  "tasks": [
    {
      "id": "tsk_1",
      "flowId": "flw_2b8e10",
      "name": "Brief",
      "status": "ready",
      "dependsOn": [],
      "blockedBy": []
    },
    {
      "id": "tsk_2",
      "flowId": "flw_2b8e10",
      "name": "Design",
      "status": "blocked",
      "dependsOn": [
        "tsk_1"
      ],
      "blockedBy": [
        "tsk_1"
      ]
    },
    {
      "id": "tsk_3",
      "flowId": "flw_2b8e10",
      "name": "Client approval",
      "status": "blocked",
      "dependsOn": [
        "tsk_2"
      ],
      "blockedBy": [
        "tsk_2"
      ]
    }
  ]
}

Get a flow

The flow with its full task graph and derived state — status, what is blocking what, and which tasks are on the critical path.

Scopes: flows:read

Path

Responses

Update a flow

Changes the flow itself. Tasks are edited through the task endpoints.

Scopes: flows:write · Role: member or higher

Path

Body application/json

Responses

Archive a flow

Archives rather than destroys: the flow leaves the list and can be restored. Nothing in Flowral deletes client history on a single call.

Scopes: flows:write · Role: member or higher

Path

Responses

Restore an archived flow

Scopes: flows:write · Role: member or higher

Path

Responses

Get the schedule

Runs the critical-path pass: earliest and latest start and finish per task, slack, and the projected finish for the flow. Computed from estimates and dependencies — no dates are stored, so this is always current.

Scopes: flows:read

Path

Query

Responses

Get the delivery report

Completion, effort remaining, workload per member, the tasks blocking the most work, and what is unestimated or orphaned. The same figures the Reporting view shows.

Scopes: flows:read

Path

Responses

Export a flow

Renders the flow through the same pipeline the app uses. pdf is the delivery document (diagram plus execution plan); png is the dependency diagram on its own. Responds with the bytes, Content-Disposition set.

Scopes: flows:read

Path

Body application/json

Responses

List a flow's guests

Clients and guests with access to this flow. Guests never occupy a seat, on any plan.

Scopes: flows:read

Path

Responses

Share a flow with a guest

Gives one person access to this flow only — they see its progress and nothing else in the workspace.

Scopes: flows:write · Role: member or higher

Path

Body application/json

Responses

Publish a flow

Makes the flow readable by anyone with its link, with no account and nothing to accept. The public view never includes assignees, comments, uploaded files or task notes, and its items cannot be opened. Returns the flow, including its publicUrl.

Scopes: flows:write · Role: member or higher

Path

Responses

Un-publish a flow

Takes the flow off the internet. Immediate and total: the link stops working for everyone who already has it, including anyone with the page open. Embeds of it go dark at the same moment.

Scopes: flows:write · Role: member or higher

Path

Responses

Remove a guest from a flow

Scopes: flows:write · Role: member or higher

Path

Responses

List a flow's tasks

Every task in the flow with its derived status. Filter by status to get just what is ready, or just what is blocked.

Scopes: flows:read

Path

Query

Responses

Add a task to a flow

Creates a task and links it in the same call. after are the tasks that must finish first; before are the tasks that now wait on this one — use it to insert a step into an existing chain.

Scopes: flows:write · Role: member or higher

Path

Body application/json

Responses

Get a task

Scopes: flows:read

Path

Responses

Update a task

Name, description and estimate. Status is not settable here — see the transition endpoints. Refused once work has started, the same rule the canvas applies.

Scopes: flows:write · Role: member or higher

Path

Body application/json

Responses

Delete a task

Bridges the gap it leaves: whatever depended on this task now depends on what it depended on, so removing a step from the middle leaves a plan that still runs end to end.

Scopes: flows:write · Role: member or higher

Path

Responses

Add a sub-task

A breakdown of one task. A task that has sub-tasks completes through them rather than directly.

Scopes: flows:write · Role: member or higher

Path

Body application/json

Responses

Add a dependency

Makes this task wait on another. Refuses anything that would create a cycle.

Scopes: flows:write · Role: member or higher

Path

Body application/json

Responses

Remove a dependency

Scopes: flows:write · Role: member or higher

Path

Responses

Start a task

Ready → in progress. Refused while anything it depends on is unfinished, and assigned work only moves for its assignee.

Scopes: work:write · Role: member or higher

Path

Responses

Complete a task

In progress → done, and the response says what that unblocked — which is the next question every time. Refused if sub-tasks are outstanding or a required deliverable has not been handed in.

Scopes: work:write · Role: member or higher

Path

Body application/json

Responses

Example

curl -X POST 'https://api.flowral.app/v1/tasks/tsk_2/complete' \
  -H 'Authorization: Bearer fl_sk_live_…'

{
  "task": {
    "id": "tsk_2",
    "name": "Design",
    "status": "done",
    "criticalPath": true
  },
  "unblocked": [
    {
      "id": "tsk_3",
      "name": "Client approval",
      "status": "ready"
    }
  ]
}

Reopen a task

Done → in progress. Refused once anything downstream has been started: undoing a completion that the next person already acted on would rewrite work that is under way.

Scopes: work:write · Role: member or higher

Path

Responses

Assign a task

Sets the owner. Send null to unassign.

Scopes: work:write · Role: member or higher

Path

Body application/json

Responses

List comments

Scopes: flows:read

Path

Responses

Comment on a task

The one write a viewer credential can make, and the one that is never frozen by work having started.

Scopes: work:write

Path

Body application/json

Responses

Attach a file

A reference file on the task — a brief, a spec, a screenshot. multipart/form-data.

Scopes: flows:write · Role: member or higher

Path

Body multipart/form-data

Responses

Hand in a deliverable

Satisfies a file requirement on the task, which is what lets it complete. Different from an attachment: this one is the thing being asked for.

Scopes: work:write

Path

Body multipart/form-data

Responses

List brainstorms

Brainstorms in the workspace, newest first. Archived ones are excluded unless archived=true.

Scopes: flows:read

Query

Responses

Create a brainstorm

Creates a brainstorm and, optionally, its whole starting idea tree in one call. An idea's parent references another idea by index in this request, so a shape arrives with the board rather than in follow-up calls.

Scopes: flows:write · Role: member or higher

Body application/json

Responses

List the archive

This workspace's archived brainstorms, most recently deleted first. Requires an owner or admin role, same as the app's archive view.

Scopes: flows:read · Role: admin or higher

Responses

Get a brainstorm

The brainstorm with every idea on its board.

Scopes: flows:read

Path

Responses

Rename a brainstorm

Ideas are edited through the idea endpoints.

Scopes: flows:write · Role: member or higher

Path

Body application/json

Responses

Archive a brainstorm

Archives rather than destroys, so it can be restored — with one exception, same rule the app applies: a brainstorm with no ideas on it yet is deleted outright, since there is nothing in it to recover.

Scopes: flows:write · Role: member or higher

Path

Responses

Restore an archived brainstorm

Scopes: flows:write · Role: admin or higher

Path

Responses

List a brainstorm's guests

Scopes: flows:read

Path

Responses

Share a brainstorm with a guest

Gives one person access to this brainstorm only — they see it from their own workspace and never join the squad. Only existing Flowral accounts can be shared with this way; the API does not send invitation emails.

Scopes: flows:write · Role: member or higher

Path

Body application/json

Responses

Remove a guest from a brainstorm

Scopes: flows:write · Role: member or higher

Path

Responses

Publish a brainstorm

Makes the board readable by anyone with its link, with no account and nothing to accept. The public view shows the boxes, their tree position and their tags — never assignees, comments, files or notes. Returns the brainstorm, including its publicUrl.

Scopes: flows:write · Role: member or higher

Path

Responses

Un-publish a brainstorm

Takes the board off the internet. Immediate: the link stops working for everyone who already has it, including anyone with the page open.

Scopes: flows:write · Role: member or higher

Path

Responses

List a brainstorm's ideas

Every idea on the board, depth-first from its root ideas — the order the canvas reads as a tree.

Scopes: flows:read

Path

Responses

Add an idea

Adds one box to the board. Set parentId to nest it under an existing idea — omit it for a root idea.

Scopes: flows:write · Role: member or higher

Path

Body application/json

Responses

Get an idea

Scopes: flows:read

Path

Responses

Update an idea

Title, notes, tags, assignee, or its parent — moving parentId re-parents the box. Refused if the move would create a cycle or self-parent.

Scopes: flows:write · Role: member or higher

Path

Body application/json

Responses

Delete an idea

Bridges the gap it leaves: this idea's children are re-parented onto its own parent (or promoted to root ideas, if it had none), so removing a box from the middle of a branch doesn't orphan what nested under it. This cannot be undone.

Scopes: flows:write · Role: member or higher

Path

Responses

List comments

Scopes: flows:read

Path

Responses

Comment on an idea

Discussion is never frozen — commenting works whatever state the board or the idea is in.

Scopes: work:write

Path

Body application/json

Responses

Attach a file

A reference file on the idea. multipart/form-data.

Scopes: flows:write · Role: member or higher

Path

Body multipart/form-data

Responses

What is ready to start

Every unblocked, unstarted task across the workspace, critical-path work first. The single most useful call in this API.

Scopes: flows:read

Query

Responses

Example

curl 'https://api.flowral.app/v1/work/available' \
  -H 'Authorization: Bearer fl_sk_live_…'

{
  "total": 2,
  "items": [
    {
      "taskId": "tsk_3",
      "taskName": "Client approval",
      "flowId": "flw_2b8e10",
      "flowName": "Acme: Website relaunch",
      "status": "ready",
      "assigneeId": null,
      "criticalPath": true
    },
    {
      "taskId": "tsk_9",
      "taskName": "Write launch copy",
      "flowId": "flw_2b8e10",
      "flowName": "Acme: Website relaunch",
      "status": "ready",
      "assigneeId": "usr_41",
      "criticalPath": false
    }
  ]
}

What is assigned to the caller

Ready and in-progress work assigned to this credential's identity. For a service credential, pass assigneeId to /work/available instead — a credential is not a person and has nothing assigned to it.

Scopes: flows:read

Query

Responses

What is stuck, and on what

Blocked work with the unfinished tasks holding it up, ranked so the task blocking the most appears first. This is the "where is delivery actually stalling" call.

Scopes: flows:read

Query

Responses

What is under way

Scopes: flows:read

Query

Responses

The whole workspace in one call

Per-flow counts, workload per member and the flows at risk of their due date — so a dashboard does not have to fetch twelve flows to render.

Scopes: flows:read

Responses

List members

People in the workspace and their roles. Guests are not members and are not listed here — they belong to a flow (see /v1/flows/{flowId}/shares).

Scopes: team:read

Responses

List pending invitations

Scopes: team:read

Responses

Invite someone

Sends an invitation. A pending invite occupies a seat for the purposes of the plan limit, which is why this can be refused on a full workspace before anyone has accepted.

Scopes: team:write · Role: admin or higher

Body application/json

Responses

Change a member's role

Scopes: team:write · Role: admin or higher

Path

Body application/json

Responses

List templates

Saved flow shapes in this workspace.

Scopes: templates:read

Query

Responses

Get a template

The template with the task graph it will produce, so an integration can show what it is about to create.

Scopes: templates:read

Path

Responses

Start a flow from a template

Creates a new flow from the template and returns it, graph and all. Using a template is available on every plan; saving new ones is not.

Scopes: flows:write templates:read · Role: member or higher

Path

Body application/json

Responses

Search the workspace

Flows, tasks and templates matching a query — for a picker, or to resolve a name a human typed into an id.

Scopes: flows:read

Query

Responses

What a person is subscribed to

The settings that actually apply, after the account defaults and any flow overrides have been resolved. This is the answer, not the stored row — a true here means mail will be sent.

Scopes: notifications:read

Query

Responses

Example

curl 'https://api.flowral.app/v1/notifications/preferences?memberId=usr_41' \
  -H 'Authorization: Bearer fl_sk_live_…'

{
  "memberId": "usr_41",
  "flowId": null,
  "email": true,
  "muted": false,
  "events": {
    "assigned": true,
    "unlocked": true,
    "digest": true
  },
  "timezone": "Europe/Paris",
  "digestHour": 8
}

Change what a person is subscribed to

Sets the account defaults. Only the keys you send are changed; sending null for one resets it to the built-in default rather than turning it off.

Scopes: notifications:write · Role: admin or higher

Body application/json

Responses

Example

curl -X PUT 'https://api.flowral.app/v1/notifications/preferences' \
  -H 'Authorization: Bearer fl_sk_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"memberId":"usr_41","timezone":"America/New_York","digestHour":7}'

{
  "memberId": "usr_41",
  "flowId": null,
  "email": true,
  "muted": false,
  "events": {
    "assigned": true,
    "unlocked": true,
    "digest": true
  },
  "timezone": "America/New_York",
  "digestHour": 7
}

What a person is subscribed to on one flow

The account settings with this flow's override applied.

Scopes: notifications:read

Path

Query

Responses

Override a person's settings for one flow

The usual use is {"muted": true} — silence one noisy flow without touching anything else this person gets.

Scopes: notifications:write · Role: admin or higher

Path

Body application/json

Responses

Remove a flow override

The flow follows the person's account settings again. Not the same as turning everything off for it.

Scopes: notifications:write · Role: admin or higher

Path

Query

Responses

What was actually sent

One row per email that left the building, newest first — batches and digests alike. Use it to answer "did they get told", and to see what was suppressed because they had unsubscribed.

Scopes: notifications:read

Query

Responses

This person's digest, without sending it

What tomorrow morning's mail would say, built by the real builder and delivered to nobody. Also the cleanest per-person view of "what should I work on today" across every flow they can see — /v1/work/available answers that per workspace, this answers it per person.

Scopes: notifications:read

Query

Responses

Example

curl 'https://api.flowral.app/v1/notifications/digest?memberId=usr_41' \
  -H 'Authorization: Bearer fl_sk_live_…'

{
  "memberId": "usr_41",
  "wouldSend": true,
  "counts": {
    "ready": 2,
    "inProgress": 1,
    "blocked": 1,
    "available": 3,
    "doneByMe": 1,
    "doneByTeam": 4,
    "atRisk": 1,
    "flows": 3
  },
  "ready": [
    {
      "questId": "flw_2b8e10",
      "questName": "Acme: Website relaunch",
      "nodeId": "tsk_9",
      "nodeTitle": "Write launch copy",
      "hours": 8,
      "criticalPath": true
    }
  ],
  "atRisk": [
    {
      "questId": "flw_2b8e10",
      "questName": "Acme: Website relaunch",
      "dueDate": "2026-09-14",
      "projectedFinish": "2026-09-21",
      "workdaysOver": 5
    }
  ]
}