Workflow (Task Management) API Task lists and tasks.

All workflow endpoints (except toggle) require the workflow feature to be enabled on the target workspace or share. Workflow GET endpoints support format=md query parameter for Markdown output (AI agent-friendly).

Share access: On shares, tasks require member or admin access — guests are blocked. Public guests remain blocked from everything. Toggle endpoints (enable/disable) remain Admin-only.

Endpoint Summary

Feature Toggle

Task Lists & Tasks

Workflow Agent Templates (v3.5+, admin-only)

Workspace-scoped persona templates that pair an agent-step instruction prompt with a tool allowlist. v3.5 ships storage + admin CRUD; the agent runtime consumes these in a later release. Write methods require workspace admin; list/read require workspace view.

Mutable fields via PATCH: name (max 128 chars), instruction_prompt (max 8192 chars), tool_allowlist (JSON array of tool id strings). Immutable: id, workspace_id, created_at, created_by_user_id.

Common Path Parameters

Common Error Responses

These errors apply to all workflow endpoints (except toggle):

Share Workflow Access Levels

On shares, tasks require member or admin access — guests are blocked. Update, delete, and bulk operations require member or admin permissions.

Feature Toggle

Enable or disable workflow on a workspace or share. Requires admin-level access. These endpoints do not require workflow to already be enabled.

Enable Workflow on Workspace

Auth: Required (JWT). Admin or owner.

Request Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/workflow/enable/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "message": "Workflow features enabled",
  "workflow": true
}

Response Fields

Access Levels

Error Responses

Disable Workflow on Workspace

Request Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/workflow/disable/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "message": "Workflow features disabled",
  "workflow": false
}

Error Responses

Share Toggle Endpoints

Behave identically to the workspace variants above, using {share_id} instead. Requires Admin-level access on the share.

Disabling workflow does not delete any data. All entities are preserved and become accessible again when re-enabled.

Task Lists & Tasks

Task lists are containers for tasks, scoped to a workspace or share. Tasks support statuses, priorities, assignees, dependencies, and file/folder node links.

Task Status Values

Valid Status Transitions

Task Priority (integer)

Task List Object

Task Object

The live attachment_count and comment_count fields are returned by the single-task detail endpoint and on every task row of the task list endpoints (GET /current/tasks/{list_id}/details/, GET /current/tasks/{list_id}/items/). The hydrated attachments array is returned only by the single-task detail endpoint.

List Task Lists

Backwards compatibility: The previous routes (/current/tasks/workspace/{workspace_id}/ and /current/tasks/share/{share_id}/) continue to work via automatic redirect.

Auth: Required (JWT). Rate limited.

Query Parameters

Request Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/tasks/?limit=50" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "task_lists": [
    {
      "id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
      "profile_id": "1234567890123456789",
      "name": "Sprint 12 Tasks",
      "description": "Tasks for the current sprint",
      "created_by": "9876543210987654321",
      "properties": {},
      "sort_order": 0,
      "created": "2025-06-01 09:00:00 UTC",
      "updated": "2025-06-10 14:30:00 UTC",
      "deleted": null
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1
  }
}

Create Task List

Backwards compatibility: The previous routes (/current/tasks/workspace/{workspace_id}/create/ and /current/tasks/share/{share_id}/create/) continue to work via automatic redirect.

Auth: Required (JWT). Rate limited.

Request Body

Request Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/tasks/create/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=Sprint%2012%20Tasks&description=Tasks%20for%20the%20current%20sprint"

Response

{
  "result": true,
  "task_list": {
    "id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
    "profile_id": "1234567890123456789",
    "name": "Sprint 12 Tasks",
    "description": "Tasks for the current sprint",
    "created_by": "9876543210987654321",
    "properties": {},
    "sort_order": 0,
    "created": "2025-06-01 09:00:00 UTC",
    "updated": "2025-06-01 09:00:00 UTC",
    "deleted": null
  }
}

Get Task List Details

Auth: Required (JWT). Rate limited.

Query Parameters

Response

{
  "result": true,
  "task_list": {
    "id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
    "profile_id": "1234567890123456789",
    "name": "Sprint 12 Tasks",
    "description": "Tasks for the current sprint",
    "created_by": "9876543210987654321",
    "properties": {},
    "sort_order": 0,
    "created": "2025-06-01 09:00:00 UTC",
    "updated": "2025-06-10 14:30:00 UTC",
    "deleted": null
  },
  "tasks": [
    {
      "id": "x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5",
      "task_list_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
      "profile_id": "1234567890123456789",
      "title": "Implement login flow",
      "description": "Build the OAuth2 login flow",
      "status": "in_progress",
      "assignee_id": "9876543210987654321",
      "priority": 3,
      "sort_order": 0,
      "dependencies": null,
      "node_id": null,
      "properties": {},
      "attachment_count": 1,
      "comment_count": 2,
      "created": "2025-06-01 09:30:00 UTC",
      "updated": "2025-06-10 14:30:00 UTC",
      "deleted": null
    }
  ]
}

Update Task List

Auth: Required (JWT). Rate limited.

Request Body

Delete Task List

Auth: Required (JWT). Rate limited.

Restore Task List

Auth: Required (JWT). Rate limited.

Response

{
  "result": true,
  "task_list": {
    "id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
    "profile_id": "1234567890123456789",
    "name": "Sprint 12 Tasks",
    "description": null,
    "created_by": "9876543210987654321",
    "properties": {},
    "sort_order": 0,
    "created": "2026-06-13 09:30:00 UTC",
    "updated": "2026-06-13 16:37:29 UTC",
    "deleted": null
  }
}

List Tasks

Auth: Required (JWT). Rate limited.

Query Parameters

Create Task

Auth: Required (JWT). Rate limited.

Request Body

Request Example

curl -X POST "https://api.fast.io/current/tasks/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5/items/create/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "title=Implement%20login%20flow&priority=3&assignee_id=9876543210987654321"

Response

{
  "result": true,
  "task": {
    "id": "x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5",
    "task_list_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
    "profile_id": "1234567890123456789",
    "title": "Implement login flow",
    "description": null,
    "status": "pending",
    "assignee_id": "9876543210987654321",
    "priority": 3,
    "sort_order": 0,
    "dependencies": null,
    "node_id": null,
    "properties": {},
    "created": "2025-06-01 09:30:00 UTC",
    "updated": "2025-06-01 09:30:00 UTC",
    "deleted": null
  }
}

Get Task Details

Auth: Required (JWT). Rate limited.

Query Parameters

Response

{
  "result": true,
  "task": {
    "id": "x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5",
    "task_list_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
    "profile_id": "1234567890123456789",
    "title": "Implement login flow",
    "description": "Build the OAuth2 login flow",
    "status": "in_progress",
    "assignee_id": "9876543210987654321",
    "priority": 3,
    "sort_order": 0,
    "dependencies": null,
    "node_id": null,
    "created_by": "9876543210987654321",
    "properties": {},
    "attachment_count": 1,
    "attachments": [
      {
        "target_id": "n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5",
        "target_type": "node",
        "kind": "node",
        "display_name": "spec.pdf",
        "available": true
      }
    ],
    "comment_count": 2,
    "created": "2026-06-09 09:30:00 UTC",
    "updated": "2026-06-09 14:30:00 UTC",
    "deleted": null
  }
}

Update Task

Auth: Required (JWT). Rate limited.

Request Body

Delete Task

Auth: Required (JWT). Rate limited.

Restore Task

Auth: Required (JWT). Rate limited.

Response

{
  "result": true,
  "task": {
    "id": "x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5",
    "task_list_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
    "profile_id": "1234567890123456789",
    "title": "Implement login flow",
    "description": "Build the OAuth2 login flow",
    "status": "in_progress",
    "assignee_id": "9876543210987654321",
    "priority": 3,
    "sort_order": 0,
    "dependencies": null,
    "node_id": null,
    "created_by": "9876543210987654321",
    "properties": {},
    "created": "2026-06-13 09:30:00 UTC",
    "updated": "2026-06-13 16:37:29 UTC",
    "deleted": null
  }
}

Change Task Status

Auth: Required (JWT). Rate limited.

Request Body

Request Example

curl -X POST "https://api.fast.io/current/tasks/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5/items/x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5/status/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "status=in_progress"

Response

{
  "result": true,
  "task": {
    "id": "x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5",
    "status": "in_progress",
    "...": "..."
  },
  "old_status": "pending",
  "new_status": "in_progress"
}

Assign Task

Auth: Required (JWT). Rate limited.

Request Body

The assignee_id can refer to a pending member (an invited user who has not yet signed up). Pending members have a valid user ID and can be assigned to tasks before they create their account. When the user claims their account, the assignment is preserved.

Move Task

Auth: Required (JWT). Rate limited.

Request Body

Constraints: Target list must exist, not be deleted, and belong to the same profile. Source and target list cannot be the same.

Example

curl -X POST "https://api.fast.io/current/tasks/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5/items/x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5/move/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"target_task_list_id": "p1q2r3s4t5u6v7w8x9y0z1a2b3c4d5"}'

Response: Updated task object with old_task_list_id and new_task_list_id.

Bulk Update Task Status

Auth: Required (JWT). Rate limited.

Request Body

Request Example

curl -X POST "https://api.fast.io/current/tasks/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5/items/bulk-status/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"tasks": [{"task_id": "x1y2z3...", "status": "complete"}, {"task_id": "p1q2r3...", "status": "in_progress"}]}'

Response

{
  "result": true,
  "success": true,
  "updated_count": 2,
  "failed_count": 0,
  "total_count": 2,
  "results": [
    {"task_id": "x1y2z3...", "success": true, "error": null},
    {"task_id": "p1q2r3...", "success": true, "error": null}
  ]
}

Response Fields

Reorder Tasks

Auth: Required (JWT). Rate limited.

Request Body (JSON)

Each entry in the order array specifies a task ID and its new sort order. All task IDs must belong to the specified task list.

Request Example

curl -X POST "https://api.fast.io/current/tasks/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5/items/reorder/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"order": [{"id": "x1y2z3...", "sort_order": 0}, {"id": "p1q2r3...", "sort_order": 1}]}'

Response

{
  "result": true,
  "reordered": 2,
  "list_id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5"
}

Response Fields

Reorder Task Lists

Backwards compatibility: The previous routes (/current/tasks/workspace/{workspace_id}/reorder/ and /current/tasks/share/{share_id}/reorder/) continue to work via automatic redirect.

Auth: Required (JWT). Rate limited.

Request Body (JSON)

Each entry in the order array specifies a task list ID and its new sort order. All task list IDs must belong to the specified workspace or share.

Request Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/tasks/reorder/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"order": [{"id": "a1b2c3...", "sort_order": 0}, {"id": "d4e5f6...", "sort_order": 1}]}'

Response

{
  "result": true,
  "reordered": 2,
  "profile_id": "1234567890123456789"
}

Response Fields

Task Attachments

Attach arbitrary platform objects to a task to give it context — a file or folder, a note, a workflow, a sign-envelope, a share, a File Share, or another task. An attachment is a lightweight reference: it records what is attached, not a copy of it.

• A task can hold up to 100 attachments.
• Attaching is idempotent — re-attaching an object that is already attached is a no-op and does not count against the cap.
• Attaching does not verify that the target exists or is accessible; display names are resolved (and access-gated) on read.
• All attachment endpoints require the workflow feature on the owning workspace or share. On shares, member or admin access is required — guests are blocked. A soft-deleted task returns 404.

Attachment Object (hydrated)

Every attachment returned by the API is hydrated and access-gated to the caller: an object the caller cannot see (or that no longer exists) is returned with available: false and display_name: null rather than leaking its name.

List Task Attachments

Auth: Required (JWT). Rate limited.

Response

{
  "result": true,
  "task_id": "x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5",
  "attachments": [
    {
      "target_id": "n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5",
      "target_type": "node",
      "kind": "node",
      "display_name": "spec.pdf",
      "available": true
    },
    {
      "target_id": "9876543210987654321",
      "target_type": "share",
      "kind": "share",
      "display_name": null,
      "available": false
    }
  ],
  "count": 2
}

Response Fields

Attach Objects to a Task

Auth: Required (JWT). Rate limited. Content-Type: application/json.

Request Body

The target_id (or each entry in target_ids) is the ID of any file/folder node, note, workflow, sign-envelope, share, File Share, workspace, or task. A request whose new attachments would push the task over the 100-attachment cap is rejected before anything is written.

Request Example — single

curl -X POST "https://api.fast.io/current/tasks/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5/items/x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5/attachments/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"target_id": "n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5"}'

Request Example — bulk

curl -X POST "https://api.fast.io/current/tasks/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5/items/x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5/attachments/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"target_ids": ["n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5", "9876543210987654321"]}'

Response

{
  "result": true,
  "task_id": "x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5",
  "attached": 1,
  "attachments": [
    {
      "target_id": "n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5",
      "target_type": "node",
      "kind": "node",
      "display_name": "spec.pdf",
      "available": true
    }
  ],
  "count": 1
}

Response Fields

Error Responses

Detach an Object from a Task

Auth: Required (JWT). Rate limited. Content-Type: application/json.

Request Body

Request Example

curl -X POST "https://api.fast.io/current/tasks/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5/items/x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5/attachments/detach/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"target_id": "n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5"}'

Response

{
  "result": true,
  "task_id": "x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5",
  "removed": true,
  "attachments": [],
  "count": 0
}

Response Fields

Task Comments

Collaborate on a task with a dedicated comment thread. Task comments support the full comment feature set — threaded replies, @-mentions, emoji reactions, edit/delete, and edited/created timestamps. The comment shape and threading/mention/reference semantics match the Comments reference; only the list/create surface is task-specific.

• Task comments require the workflow feature on the owning workspace or share. On shares, member or admin access is required — guests are blocked. A soft-deleted task returns 404.
• Task comments are private to the task: they are not returned by the general comment listing (GET /current/comments/{entity_type}/{parent_id}/) and do not appear in the global comment search.
• Reactions, edit, and delete of a task comment use the existing comment-by-id endpoints (POST /current/comments/{comment_id}/reactions/, POST /current/comments/{comment_id}/update/ to edit, DELETE /current/comments/{comment_id}/delete/). See the Comments reference.
• The single-task detail endpoint and task list rows return a live comment_count.
• Realtime routing: comment events (comment_created, comment_updated, comment_deleted, comment_reaction, mention/reply notifications) for a task comment carry linked_entity_type: "task" and linked_entity_id (the task id) in their payload, so clients can route them to the right task thread.

List Task Comments

Auth: Required (JWT). Rate limited.

Query Parameters

Response

{
  "result": true,
  "task_id": "x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5",
  "comments": [
    {
      "id": "cmt1opaqueid",
      "entity": "x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5",
      "user_id": "9876543210987654321",
      "parent_id": null,
      "body": "Started on this — first draft is in spec.pdf.",
      "profile_type": "workspace",
      "profile_id": "1234567890123456789",
      "linked_entity_type": "task",
      "linked_entity_id": "x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5",
      "reference": null,
      "mentions": [],
      "reactions": {"👍": 1},
      "user_reaction": null,
      "version": 1,
      "can_edit": false,
      "can_delete": false,
      "can_reply": true,
      "created": "2026-06-09 10:00:00 UTC",
      "updated": "2026-06-09 10:00:00 UTC"
    }
  ],
  "count": 1,
  "limit": 50,
  "offset": 0
}

Response Fields

Post a Task Comment

Auth: Required (JWT). Rate limited. Content-Type: application/json.

Request Body

Mentions are parsed from the body markup and validated against the task's workspace/share membership; client-supplied mention lists are ignored.

This endpoint is create-only: a body containing a comment_id field is rejected with 400 Invalid Input (it never edits and never creates a duplicate), and trailing path segments after …/comments/ return 404. To edit a task comment use POST /current/comments/{comment_id}/update/.

Request Example

curl -X POST "https://api.fast.io/current/tasks/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5/items/x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5/comments/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{"body": "Looks good — @[user:1234567890123456789:Jane Smith] can you take the review?"}'

Response

201 Created with the created comment object:

{
  "result": true,
  "comment": {
    "id": "cmt2opaqueid",
    "entity": "x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5",
    "user_id": "9876543210987654321",
    "parent_id": null,
    "body": "Looks good — @[user:1234567890123456789:Jane Smith] can you take the review?",
    "profile_type": "workspace",
    "profile_id": "1234567890123456789",
    "linked_entity_type": "task",
    "linked_entity_id": "x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5",
    "reference": null,
    "mentions": ["1234567890123456789"],
    "reactions": {},
    "user_reaction": null,
    "version": 1,
    "can_edit": true,
    "can_delete": true,
    "can_reply": true,
    "created": "2026-06-09 10:05:00 UTC",
    "updated": "2026-06-09 10:05:00 UTC"
  }
}

Error Responses

Profile-Scoped Filtered Lists & Summaries

Tasks support profile-scoped filtered list and summary endpoints. Workspace context provides a personal view (filtered to the current user). Share context provides a group view for members and admins. Tasks on shares are restricted to members and admins. All endpoints support ?limit= (default 50, max 100) and ?offset= (default 0).

Task Filtered Lists

Task Summaries

Workflow Events

Tasks emit events on all state changes. Filter with:

GET /current/events/search/?workspace_id={id}&category=workflow

Task Events

• task_list_created
• task_list_updated
• task_list_deleted
• task_list_restored
• task_created
• task_updated
• task_deleted
• task_restored
• task_status_changed
• task_assigned
• task_moved
• task_completed
• tasks_reordered
• task_lists_reordered
• task_attachment_added
• task_attachment_removed

All workflow events use event category workflow and subcategory workflow.