Flowral API v1.0.0

Exchange client credentials for an access token

Standard OAuth 2.0 client-credentials grant (application/x-www-form-urlencoded). Credentials may also be sent as HTTP Basic. 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.

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

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

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
    }
  ]
}