Checklists

A checklist is a running instance of a template — the thing people actually work through. These routes find checklists, start new ones from a template, read one in full and change what can be changed about it as a whole: its name, its completion stamp, its due date, whether it is archived, its public share link and its tags. See Create a Checklist and Managing Checklists for the same actions in the app.

The tasks inside a checklist — completing them, setting their due dates and assignees, filling in their fields — have their own routes under /v3/checklists/{checklistKey}/tasks, documented on Checklist Tasks. Standalone tasks attached to a checklist are listed here but read and written on Standalone Tasks. Moving running checklists onto a newer template version is done from the template; see Templates.

Every request is made as the member your API key acts as (see Who a Key Acts As), and that member's permissions decide what is allowed:

Action	Who may do it
List and search checklists	Anyone. Results are narrowed to what the member's checklist permissions let them see. A key that acts as the workspace sees every checklist.
Create a checklist	An Administrator, a key that acts as the workspace, or a member with the Checklist.Creator permission whose checklist permission on the template is Run and View or Run and View Assigned To.
Read one checklist by key, its activity, attached tasks, share settings and tags	An Administrator, a key that acts as the workspace, or a member whose checklist permission on the template is Run and View or View But Not Run. A member with Run and View Assigned To, View Assigned To But Not Run or no permission on the template may read a checklist only when something in it is assigned to them, directly or through a group. This is the rule the app applies when a member opens a checklist.
Rename, set the due date, complete, reopen, share, stop sharing, delete	An Administrator, or a member whose checklist permission on the template is Run and View or Run and View Assigned To. Guests are always refused.
Archive and unarchive	Administrators only.
Tag and untag	Any key for the workspace.

A key that acts as the workspace may read every checklist and create checklists from any template. For the other writes it acts as the workspace's anonymous member. That member is not an Administrator, so archiving is refused, and the run-gated writes are refused unless a template permission grants the anonymous member run access.

A refusal is 403 FORBIDDEN. It comes after the checklist or template is looked up, so another workspace's checklist is still 404 CHECKLIST_NOT_FOUND, and another workspace's template 404 TEMPLATE_NOT_FOUND.

Every write on this page accepts an Idempotency-Key header, and every route is charged to the standard rate limit budget.

Endpoints

Method	Path	Description	MCP tool
`GET`	`/v3/checklists`	List checklists	`list_checklists`
`POST`	`/v3/checklists`	Create a checklist	`create_checklist`
`POST`	`/v3/checklists/search`	Search checklists by field value	`search_checklists`
`GET`	`/v3/checklists/{key}`	Get a checklist	`get_checklist`
`PATCH`	`/v3/checklists/{key}`	Update a checklist	`update_checklist`
`DELETE`	`/v3/checklists/{key}`	Delete a checklist	`delete_checklist`
`GET`	`/v3/checklists/{key}/activity`	Get checklist activity	`get_checklist_activity`
`POST`	`/v3/checklists/{key}/archive`	Archive a checklist	`set_checklist_archived`
`DELETE`	`/v3/checklists/{key}/archive`	Unarchive a checklist	`set_checklist_archived`
`POST`	`/v3/checklists/{key}/complete`	Mark a checklist complete	`set_checklist_complete`
`DELETE`	`/v3/checklists/{key}/complete`	Reopen a checklist	`set_checklist_complete`
`GET`	`/v3/checklists/{key}/attached-tasks`	List attached tasks	`list_attached_tasks`
`GET`	`/v3/checklists/{key}/share`	Get share settings	`get_checklist_share`
`PUT`	`/v3/checklists/{key}/share`	Share a checklist	`set_checklist_share`
`DELETE`	`/v3/checklists/{key}/share`	Stop sharing a checklist	`stop_sharing_checklist`
`GET`	`/v3/checklists/{key}/tags`	List checklist tags	—
`POST`	`/v3/checklists/{key}/tags`	Tag a checklist	`add_checklist_tags`
`DELETE`	`/v3/checklists/{key}/tags`	Untag a checklist	`remove_checklist_tag`

The Checklist Object

The list, the search and the archive routes return this shape. It is read without the checklist's tasks, so it carries nothing that has to be worked out from them.

Field	Type	Description
`key`	`string` (GUID)	The checklist's key — the `{key}` in every route on this page.
`name`	`string`	The checklist's name.
`url`	`string`	Where to open the checklist in the app.
`status`	`string`	`Scheduled`, `InProgress` or `Complete`. See Checklist Status.
`scheduledDateTime`	`string` (date-time)	When a scheduled checklist was due to start. Absent when it was not scheduled.
`startDateTime`	`string` (date-time)	When the checklist started, or starts if it is still `Scheduled`.
`endDateTime`	`string` (date-time)	When the checklist was marked complete. Absent while it is not.
`createdDateTime`	`string` (date-time)	Currently always the same value as `startDateTime`.
`isShared`	`boolean`	Whether the checklist has a public share link.
`sharedUrl`	`string`	The public link. Absent when `isShared` is `false`. See Share a Checklist.
`isArchived`	`boolean`	Whether the checklist is archived.
`template`	template reference	The template the checklist runs on.

{
  "key": "9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "name": "Invoice Review — INV-2041",
  "url": "https://app.checkflow.io/Checklist/Index?checklistKey=9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "status": "InProgress",
  "startDateTime": "2026-09-14T08:12:40.513Z",
  "createdDateTime": "2026-09-14T08:12:40.513Z",
  "isShared": false,
  "isArchived": false,
  "template": {
    "key": "3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
    "name": "Invoice Review",
    "url": "https://app.checkflow.io/Template/Index?templateKey=3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
    "description": "Check, approve and schedule payment of a supplier invoice.",
    "version": 3
  }
}

Template Reference

Field	Type	Description
`key`	`string` (GUID)	The template's key. Every version of a template shares it.
`name`	`string`	The template's name, as it reads in the version this checklist runs on.
`url`	`string`	Where to open the template in the app.
`description`	`string`	The template's description. Absent when it has none.
`version`	`integer`	The template version this checklist runs on. A checklist keeps the version it was started from until it is upgraded.
`createdDateTime`	`string` (date-time)	Not loaded by the checklist routes, so absent here.

Checklist Status

status is read off the checklist's dates, the same way the status filter on the list selects on them:

`status`	Means
`Scheduled`	The start date has not arrived yet.
`InProgress`	The checklist has started and has not been marked complete.
`Complete`	Somebody marked the checklist complete.

Complete means the checklist carries a completion stamp, not that its work is done. A checklist can be marked complete with tasks still outstanding — the app shows this as Marked Complete — and a checklist whose tasks are all done is still InProgress until somebody marks it complete. Whether the work is done is allTasksComplete, which only the detail read and the completion routes report, because only they read the tasks.

The Checklist Detail Object

Get a checklist, Create a checklist and Update a checklist return every field of the Checklist object plus these:

Field	Type	Description
`dueDate`	`string` (date-time)	When the work still outstanding is due: the earliest due date among the checklist's visible, unfinished tasks. A checklist has no due date of its own. Absent when nothing outstanding has a due date.
`allTasksComplete`	`boolean`	Whether every visible task that is not a heading is finished.
`tags`	`array` of `string`	The checklist's own tags, ordered by name. Tags on its tasks are not included. Only Get a Checklist fills this in; the create and update responses currently return it empty, so read the checklist or its tags when you need them.
`parameters`	`array` of parameter	The template parameters and the values this checklist was given.
`tasks`	`array` of task	Every task and heading the template wrote down, in checklist order, with its assignees, fields and comments. The task shape is documented on Checklist Tasks. Standalone tasks attached to the checklist are not included — see List Attached Tasks.

{
  "dueDate": "2026-09-21T17:00:00Z",
  "allTasksComplete": false,
  "tags": ["q3-audit", "urgent"],
  "parameters": [
    {
      "key": "b71c5e0d-4a2f-4c9b-8e13-6f2d9a0c7e55",
      "name": "Supplier",
      "type": "string",
      "value": "Northwind Supplies"
    },
    {
      "key": "e0a94f3c-2d6b-47e1-9c58-1b7f3a2e8d06",
      "name": "Approver",
      "type": "member_or_group",
      "value": "[{\"assignableType\":1,\"id\":1042}]"
    }
  ],
  "tasks": [
    {
      "assignees": [],
      "fields": [],
      "comments": [],
      "key": "5c2e8a1f-0b7d-4e39-a6c4-8d1f2b9e7a30",
      "name": "Receive the Invoice",
      "order": 1,
      "isHeading": true,
      "isComplete": false,
      "isNotApplicable": false,
      "isCurrentlyHalted": false,
      "isCurrentlyHidden": false,
      "isAssignedExclusively": false
    },
    {
      "assignees": [
        { "id": 1043, "type": "TeamMember", "name": "James Okafor" }
      ],
      "fields": [
        {
          "key": "a3d6f9b2-7e1c-4b5a-9f08-2c4e6d8b1a73",
          "name": "Invoice Number",
          "type": "ShortText",
          "isRequired": true,
          "value": "INV-2041"
        }
      ],
      "comments": [],
      "key": "1f8b3d6e-9a2c-4f7b-b0e5-3c7a9d1e4f62",
      "name": "Check the invoice details",
      "order": 2,
      "isHeading": false,
      "status": "Incomplete",
      "isComplete": false,
      "isNotApplicable": false,
      "isCurrentlyHalted": false,
      "isCurrentlyHidden": false,
      "isAssignedExclusively": false,
      "dueDateTime": "2026-09-21T17:00:00Z"
    }
  ],
  "key": "9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "name": "Invoice Review — INV-2041",
  "url": "https://app.checkflow.io/Checklist/Index?checklistKey=9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "status": "InProgress",
  "startDateTime": "2026-09-14T08:12:40.513Z",
  "createdDateTime": "2026-09-14T08:12:40.513Z",
  "isShared": false,
  "isArchived": false,
  "template": {
    "key": "3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
    "name": "Invoice Review",
    "url": "https://app.checkflow.io/Template/Index?templateKey=3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
    "description": "Check, approve and schedule payment of a supplier invoice.",
    "version": 3
  }
}

A task's fields are its input controls; their types and value shapes are on Task Fields and Control Types.

Parameter

A template parameter and the value this checklist was given for it.

Field	Type	Description
`key`	`string` (GUID)	The parameter's key.
`name`	`string`	The parameter's name. Absent for a value stored against a parameter the template no longer has.
`type`	`string`	`string`, `datetime` or `member_or_group`. Absent for a value stored against a parameter the template no longer has. See Parameter Values.
`value`	`string`	The value. Absent when the parameter was given none.

The Completion Object

Mark a checklist complete and Reopen a checklist return both halves of completion, because a checklist can be one without the other.

Field	Type	Description
`key`	`string` (GUID)	The checklist's key.
`name`	`string`	The checklist's name.
`url`	`string`	Where to open the checklist in the app.
`isComplete`	`boolean`	Whether the checklist is now marked complete — the state you asked for.
`endDateTime`	`string` (date-time)	When it was marked complete. Absent once it has been reopened.
`allTasksComplete`	`boolean`	Whether every visible task on it is actually finished.

{
  "key": "9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "name": "Invoice Review — INV-2041",
  "url": "https://app.checkflow.io/Checklist/Index?checklistKey=9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "isComplete": true,
  "endDateTime": "2026-09-22T10:04:17.220Z",
  "allTasksComplete": false
}

isComplete: true with allTasksComplete: false is a checklist closed with work outstanding. isComplete: false with allTasksComplete: true is the opposite: every task is done and nobody has marked the checklist complete.

The Activity Entry Object

One thing that happened on a checklist. There is no event type: activity is recorded as a sentence at the moment the event happens, and nothing structured is stored beside it except which task and field it concerns. See Activity Feed for what the app records.

Field	Type	Description
`occurredAt`	`string` (date-time)	When it happened.
`actor`	user reference	Who did it. `API Service` is the API and `Scheduler Service` is the scheduler; neither is a member, so neither has an `email`. A member who has since been removed reads as `Unknown User`.
`description`	`string`	What happened, as a sentence — for example `Completed task 'Check the invoice details'`.
`taskKey`	`string` (GUID)	The task the entry is about. Absent when it is about the checklist as a whole.
`taskName`	`string`	That task's current name. Absent when the task has been deleted.
`fieldKey`	`string` (GUID)	The field the entry is about. Absent when it is not about a field.
`fieldName`	`string`	That field's current label. Absent when the field has been deleted.
`dateTimeValue`	`string` (date-time)	The value a Date & Time field was set to, for entries that record one. Absent otherwise, including when a date was cleared.

{
  "occurredAt": "2026-09-15T09:41:03.870Z",
  "actor": { "name": "James Okafor", "email": "james.okafor@acme.example" },
  "description": "Updated short text 'Invoice Number' value to 'INV-2041'",
  "taskKey": "1f8b3d6e-9a2c-4f7b-b0e5-3c7a9d1e4f62",
  "taskName": "Check the invoice details",
  "fieldKey": "a3d6f9b2-7e1c-4b5a-9f08-2c4e6d8b1a73",
  "fieldName": "Invoice Number"
}

Names in description, taskName and fieldName are resolved when the feed is read, not when the entry was written, so a renamed task reads under its current name throughout its history. Where the task or field has been deleted, the sentence says (deleted) and the entry is still returned.

In description, a Date & Time value is written as yyyy-MM-dd for a date-only field, HH:mm for a time-only field and a full UTC instant otherwise; dateTimeValue always carries the full instant. Some descriptions, such as those for uploaded files, contain HTML markup around the file name.

User Reference

Field	Type	Description
`name`	`string`	The person's full name.
`email`	`string`	Their email address. Absent for the API and the scheduler.

The Attached Task Object

A standalone task attached to a checklist, as the checklist sees it. It is addressed at /v3/tasks/{taskKey} on Standalone Tasks with the same key — attaching a task does not move it.

Field	Type	Description
`key`	`string` (GUID)	The task's key.
`name`	`string`	The task's name.
`status`	`string`	`Incomplete`, `Complete` or `NotApplicable`. A task that was ruled out reads as `NotApplicable`.
`dueDateTime`	`string` (date-time)	When the task is due. Absent when it has no due date.
`completedDateTime`	`string` (date-time)	When it was completed. Absent while it is not.
`completedBy`	user reference	Who completed it. Absent while it is not complete, and also when that person has since been removed from the workspace.
`notApplicableDateTime`	`string` (date-time)	When it was marked not applicable. Absent while it is not.
`notApplicableBy`	user reference	Who marked it not applicable, under the same terms as `completedBy`.
`createdDateTime`	`string` (date-time)	When the task was raised.
`createdBy`	user reference	Who raised it, under the same terms as `completedBy`.
`assignees`	`array` of assignee	Everybody the task is assigned to, groups before members, then by name. Each is `{ "id", "type", "name" }` with `type` `TeamMember` or `Group`. Empty when it is assigned to nobody.
`isAssignedExclusively`	`boolean`	When `true`, only the people in `assignees` may open or complete the task. Reported, not applied: this route returns every attached task whoever asks.
`url`	`string`	Where to open the task in the app — the checklist's page, at the task.

The attached task does not carry its description, comments or tags. Read the task at /v3/tasks/{taskKey} for those.

A checklist's public link and the conditions on it. All three share routes return it.

Field	Type	Description
`isShared`	`boolean`	Whether the checklist has a public link.
`sharedKey`	`string` (GUID)	The key that identifies the link, already inside `sharedUrl`. Absent when the checklist is not shared.
`sharedUrl`	`string`	The link to give out. Anybody holding it can open the checklist without signing in. Absent when the checklist is not shared.
`isPasswordProtected`	`boolean`	Whether visitors must enter a password. The password itself is never returned.
`expiresAt`	`string` (date-time)	When the link stops working. Absent for never.
`isExpired`	`boolean`	Whether `expiresAt` has already passed. Nothing removes an expired share: the key and the URL stay, and the link simply stops opening.
`expireOnceComplete`	`boolean`	Whether the link stops working once the checklist is complete. This is checked against the checklist's tasks when the link is opened, not against the completion stamp.
`isReadOnly`	`boolean`	Whether visitors may only read the checklist, not work through it. It affects the link only; signed-in members are unaffected.

{
  "isShared": true,
  "sharedKey": "c8e1f4a7-3b9d-4d62-a0f5-7e2b9c4d1a86",
  "sharedUrl": "https://app.checkflow.io/Checklist/Shared?teamId=4821&sharedKey=c8e1f4a7-3b9d-4d62-a0f5-7e2b9c4d1a86",
  "isPasswordProtected": true,
  "expiresAt": "2026-12-31T17:00:00Z",
  "isExpired": false,
  "expireOnceComplete": true,
  "isReadOnly": false
}

List Checklists

Returns a page of the workspace's checklists, newest first by default. Use it to page through checklists by template or status; to find checklists by what has been filled in on them, use Search Checklists by Field Value.

GET /v3/checklists

Parameters

Name	In	Type	Required	Description
`templateKey`	query	`string` (GUID)	No	Only checklists run from this template, whatever their version.
`status`	query	`string`	No	`All` (default), `Scheduled`, `InProgress`, `RecentlyComplete` or `Complete`. Case is ignored. See below.
`sort`	query	`string`	No	`name`, `scheduledDate`, `startDate` or `endDate`, optionally followed by `:asc` or `:desc`. Default `startDate:desc`. A field with no direction sorts descending.
`pageSize`	query	`integer`	No	1–100, default 50. A value outside the range, or one that is not a number, is replaced by 50 rather than refused.
`after`	query	`string`	No	The `nextCursor` from the previous page.
`includeArchived`	query	`boolean`	No	`true` to include archived checklists. Default `false`. Any value other than `true` or `false` is refused.

The status values:

Value	Returns
`All`	Every checklist.
`Scheduled`	Checklists whose start date has not arrived.
`InProgress`	Checklists that have started and are not marked complete.
`RecentlyComplete`	Checklists marked complete in the last 24 hours.
`Complete`	Every checklist marked complete.

The first three are also the values a checklist's own status reads back as, so a status read off a row can be sent straight back as a filter. All and RecentlyComplete are ways of asking; no checklist reads back as either.

Checklists run from an archived template are never listed, even with includeArchived=true.

This is a cursor-paginated list; see Pagination. A cursor is tied to the templateKey, status, sort, pageSize and includeArchived it was issued under, and to the member the key acts as — page with the same key and the same query.

Example

GET https://api.checkflow.io/v3/checklists?templateKey=3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14&status=InProgress&pageSize=2
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

{
  "items": [
    {
      "key": "9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
      "name": "Invoice Review — INV-2041",
      "url": "https://app.checkflow.io/Checklist/Index?checklistKey=9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
      "status": "InProgress",
      "startDateTime": "2026-09-14T08:12:40.513Z",
      "createdDateTime": "2026-09-14T08:12:40.513Z",
      "isShared": false,
      "isArchived": false,
      "template": {
        "key": "3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
        "name": "Invoice Review",
        "url": "https://app.checkflow.io/Template/Index?templateKey=3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
        "version": 3
      }
    },
    {
      "key": "4b7f1e9c-8d2a-4c3e-9a61-0f5d7b3e2c94",
      "name": "Invoice Review — INV-2038",
      "url": "https://app.checkflow.io/Checklist/Index?checklistKey=4b7f1e9c-8d2a-4c3e-9a61-0f5d7b3e2c94",
      "status": "InProgress",
      "startDateTime": "2026-09-11T14:30:02.107Z",
      "createdDateTime": "2026-09-11T14:30:02.107Z",
      "isShared": true,
      "sharedUrl": "https://app.checkflow.io/Checklist/Shared?teamId=4821&sharedKey=c8e1f4a7-3b9d-4d62-a0f5-7e2b9c4d1a86",
      "isArchived": false,
      "template": {
        "key": "3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
        "name": "Invoice Review",
        "url": "https://app.checkflow.io/Template/Index?templateKey=3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
        "version": 3
      }
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoic3RhcnREYXRlOmRlc2MiLCJvIjoyfQ",
  "hasMore": true,
  "total": 7
}

Responses

Status	Code	When
`200`	—	A page of Checklist objects.
`400`	`VALIDATION_ERROR`	`field` is `templateKey` (not a GUID), `status` (not one of the five values), `sort` (an unknown field or direction), `includeArchived` (not `true` or `false`) or `after` (unreadable, or issued for a different query or a different member).

Notes

The list is narrowed to what the acting member may see. A member with View Assigned To But Not Run or Run and View Assigned To on a template sees only the checklists of it they are assigned to, and a template the member has no permission on does not appear at all. An empty page can therefore mean "nothing matched" or "nothing you may see".
A page can be shorter than pageSize when checklists were added while you were paging. Use hasMore, not the page length, to decide whether to continue.

Create a Checklist

Starts a new checklist from a template, optionally giving values to the template's parameters. The checklist's tasks and fields are copied from the template's current version, and the checklist stays on that version until it is upgraded.

POST /v3/checklists

Parameters

This endpoint takes no parameters.

Request Body

{
  "templateKey": "3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
  "name": "Invoice Review — INV-2041",
  "parameters": [
    { "name": "Supplier", "value": "Northwind Supplies" },
    { "name": "Payment Date", "value": "2026-10-15T00:00:00Z" },
    { "key": "e0a94f3c-2d6b-47e1-9c58-1b7f3a2e8d06", "value": "[{\"assignableType\":1,\"id\":1042}]" }
  ]
}

Field	Type	Required	Description
`templateKey`	`string` (GUID)	Yes	The template to run.
`name`	`string`	Yes	The checklist's name. Must not be blank.
`parameters`	`array`	No	Values for the template's parameters. Each entry names a parameter by `key` or by `name` and gives a `value`. See Parameter Values.
`parameters[].key`	`string` (GUID)	One of `key` or `name`	The parameter's key, in the lower-case form a template read returns it in.
`parameters[].name`	`string`	One of `key` or `name`	The parameter's name, matched case-insensitively.
`parameters[].value`	`string`	No	The value, as text in the format the parameter's type needs.
`referenceId`	`string`	No	Accepted but not currently stored or returned.

Parameter Values

A parameter's type decides what its value has to be. A template's parameters, with their names and types, are in its template document; a checklist read returns each parameter's key, name and type.

`type`	`value` format	Example
`string`	Plain text. Bound to a Dropdown, Multi-Choice or Sub-Tasks control, it also accepts the list syntax described in Template Parameters: a comma-delimited list selects or ticks items, and a list in square brackets creates them.	`"Northwind Supplies"`, `"[Hardware, Software] Hardware"`
`datetime`	An ISO 8601 date-time.	`"2026-10-15T00:00:00Z"`
`member_or_group`	A JSON array, sent as a string, of `assignableType` and `id` pairs. `assignableType` is `1` for a member and `2` for a group; `id` is the member's or group's id from `GET /v3/workspace`.	`"[{\"assignableType\":1,\"id\":1042},{\"assignableType\":2,\"id\":12}]"`

Values are not validated when the checklist is created. A value in the wrong format for its type is stored, and the binding it feeds is not applied.

Example

POST https://api.checkflow.io/v3/checklists
X-API-KEY: your-api-key-here
Content-Type: application/json

{
  "templateKey": "3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
  "name": "Invoice Review — INV-2041",
  "parameters": [
    { "name": "Supplier", "value": "Northwind Supplies" }
  ]
}

HTTP/1.1 201 Created

The body is a Checklist Detail object:

{
  "allTasksComplete": false,
  "tags": [],
  "parameters": [
    {
      "key": "b71c5e0d-4a2f-4c9b-8e13-6f2d9a0c7e55",
      "name": "Supplier",
      "type": "string",
      "value": "Northwind Supplies"
    }
  ],
  "tasks": [
    {
      "assignees": [],
      "fields": [
        {
          "key": "a3d6f9b2-7e1c-4b5a-9f08-2c4e6d8b1a73",
          "name": "Invoice Number",
          "type": "ShortText",
          "isRequired": true,
          "value": ""
        }
      ],
      "comments": [],
      "key": "1f8b3d6e-9a2c-4f7b-b0e5-3c7a9d1e4f62",
      "name": "Check the invoice details",
      "order": 1,
      "isHeading": false,
      "status": "Incomplete",
      "isComplete": false,
      "isNotApplicable": false,
      "isCurrentlyHalted": false,
      "isCurrentlyHidden": false,
      "isAssignedExclusively": false
    }
  ],
  "key": "9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "name": "Invoice Review — INV-2041",
  "url": "https://app.checkflow.io/Checklist/Index?checklistKey=9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "status": "InProgress",
  "startDateTime": "2026-09-14T08:12:40.513Z",
  "createdDateTime": "2026-09-14T08:12:40.513Z",
  "isShared": false,
  "isArchived": false,
  "template": {
    "key": "3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
    "name": "Invoice Review",
    "url": "https://app.checkflow.io/Template/Index?templateKey=3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
    "description": "Check, approve and schedule payment of a supplier invoice.",
    "version": 3
  }
}

Responses

Status	Code	When
`201`	—	The checklist was created. The body is the full Checklist Detail object, including the key of every task.
`400`	`VALIDATION_ERROR`	`field` is `templateKey` (missing or not a GUID) or `name` (missing or blank), or the body is not valid JSON.
`403`	`FORBIDDEN`	The key acts as a member without Checklist.Creator, or whose checklist permission on the template is neither Run and View nor Run and View Assigned To.
`404`	`TEMPLATE_NOT_FOUND`	No template with that key exists in the workspace.
`409`	`CONFLICT`	The template is archived. Unarchive it first — see Templates.

Notes

The checklist is created by the member the key acts as. They are recorded as its creator, so a task the template assigns to the checklist's creator is assigned to them. A key that acts as the workspace creates the checklist as the workspace's creator — the member who created the workspace.
A parameter you do not name keeps the template's default value. A parameter entry that matches no parameter on the template is ignored, not refused — check parameters in the response to confirm each value landed.
A parameter entry with no value, or value set to null, replaces the template's default with nothing, so the binding is not applied.
The checklist starts immediately: startDateTime is the time of the request. There is no due date in the request; set one afterwards with Update a Checklist, or let the template's due date rules set them.
Creating a checklist fires the new-checklist webhook event and runs any automatic Linked Checklist creation the template has.

Search Checklists by Field Value

Finds the checklists of one template by what has been filled in on them — "the Invoice Review whose Invoice Number is INV-2041". Use List Checklists instead when you are not filtering on a field.

POST /v3/checklists/search

Parameters

This endpoint takes no parameters.

Request Body

{
  "templateKey": "3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
  "fields": [
    { "field": "Invoice Number", "value": "INV-2041" },
    { "field": "a3d6f9b2-7e1c-4b5a-9f08-2c4e6d8b1a73", "value": "northwind", "match": "contains" }
  ],
  "status": "InProgress",
  "sort": "startDate:desc",
  "pageSize": 25,
  "includeArchived": false
}

Field	Type	Required	Description
`templateKey`	`string` (GUID)	Yes	The template whose checklists to search. Checklists run from every version of it are searched.
`fields`	`array`	Yes	The conditions, 1 to 10. A checklist must meet all of them.
`fields[].field`	`string`	Yes	The field's key, or its label on the template.
`fields[].value`	`string`	Yes	The text to match. Must not be empty.
`fields[].match`	`string`	No	`equals` (default) or `contains`. Case is ignored.
`status`	`string`	No	As on List Checklists: `All` (default), `Scheduled`, `InProgress`, `RecentlyComplete` or `Complete`.
`sort`	`string`	No	As on List Checklists: `name`, `scheduledDate`, `startDate` or `endDate`, optionally with `:asc` or `:desc`. Default `startDate:desc`.
`pageSize`	`integer`	No	1–100, default 50. A value outside the range is replaced by 50.
`includeArchived`	`boolean`	No	`true` to include archived checklists. Default `false`.
`after`	`string`	No	The `nextCursor` from the previous page.

Matching Rules

Every condition must hold. Conditions narrow the result; they never widen it. Two conditions on the same field are allowed and both have to be met.
Naming a field. A field is named by its key or by its label, matched case-insensitively. A label is looked up on the template's current version; a key is accepted even when the current version no longer has that field, so checklists run from older versions stay reachable. A label that names more than one field is refused, and the error message lists the keys to choose between.
Comparing values. Values are compared as text, ignoring case. equals matches the whole stored value; contains matches anywhere within it. Wildcard characters in value (%, _, [) are matched literally.
How values are stored. A Date & Time value is stored as text such as 2026-03-01T00:00:00; a Dropdown as the chosen option's label; a Multi-Choice or Sub-Tasks value as its chosen labels joined with , . Use contains to find one entry of such a list.
Searchable fields. Only field types that appear in reporting can be searched: Short Text, Long Text, E-Mail, Website, Date & Time, File Upload, Dropdown, Multi-Choice, Sub-Tasks and Members. A condition on any other type is refused rather than silently matching nothing.
No empty values. You cannot search for "not filled in": a field nobody has touched is absent from the searched values, not stored as blank.
Delay. Searched values are copied into a search index by a background job when they change, so a value written a few seconds ago may not be found yet. To confirm a write you have just made, read the checklist.

Results are narrowed by the acting member's checklist permissions exactly as the list is; a key that acts as the workspace searches every checklist of the template. Checklists run from an archived template are never returned.

To page, send the whole body again with after set. The cursor is tied to every condition — in the order sent — and to status, sort, pageSize, includeArchived and the acting member.

Example

POST https://api.checkflow.io/v3/checklists/search
X-API-KEY: your-api-key-here
Content-Type: application/json

{
  "templateKey": "3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
  "fields": [
    { "field": "Invoice Number", "value": "INV-2041" }
  ]
}

HTTP/1.1 200 OK

{
  "items": [
    {
      "key": "9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
      "name": "Invoice Review — INV-2041",
      "url": "https://app.checkflow.io/Checklist/Index?checklistKey=9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
      "status": "InProgress",
      "startDateTime": "2026-09-14T08:12:40.513Z",
      "createdDateTime": "2026-09-14T08:12:40.513Z",
      "isShared": false,
      "isArchived": false,
      "template": {
        "key": "3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
        "name": "Invoice Review",
        "url": "https://app.checkflow.io/Template/Index?templateKey=3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
        "version": 3
      }
    }
  ],
  "hasMore": false,
  "total": 1
}

Responses

Status	Code	When
`200`	—	A page of Checklist objects.
`400`	`VALIDATION_ERROR`	`field` is `templateKey` (missing or not a GUID); `fields` (empty, or more than 10 conditions); `fields[n].field` (missing, not on the template, naming more than one field, or a type that cannot be searched); `fields[n].value` (empty); `fields[n].match` (not `equals` or `contains`); `status`; `sort`; or `after` (unreadable, or issued for a different search). An unreadable body has no `field`.
`404`	`TEMPLATE_NOT_FOUND`	No template with that key exists in the workspace.

Get a Checklist

Returns one checklist in full: its tasks with their fields, assignees and comments, its parameters and its tags. Unlike the list, it reports dueDate and allTasksComplete, because it reads the tasks.

GET /v3/checklists/{key}

Parameters

Name	In	Type	Required	Description
`key`	path	`string` (GUID)	Yes	The checklist's key.

Example

GET https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

The body is a Checklist Detail object, as in the example there.

Responses

Status	Code	When
`200`	—	The Checklist Detail object.
`400`	`VALIDATION_ERROR`	`field` is `key`: the key is not a GUID.
`403`	`FORBIDDEN`	The acting member may not see this checklist: their checklist permission on the template does not let them view it, and nothing in it is assigned to them.
`404`	`CHECKLIST_NOT_FOUND`	No checklist with that key exists in the workspace.

Notes

Archived checklists can still be read by key.
Standalone tasks attached to the checklist are not in tasks; see List Attached Tasks. To read the tasks without their fields, assignees and comments, use the lighter task list on Checklist Tasks.

Update a Checklist

Renames a checklist, sets or clears the due date of its outstanding work, or marks it complete or in progress — any combination in one call.

PATCH /v3/checklists/{key}

Parameters

Name	In	Type	Required	Description
`key`	path	`string` (GUID)	Yes	The checklist's key.

Request Body

A partial update: a field you leave out is left alone, and dueDate sent as null is cleared. The body must name at least one of the three fields.

{
  "name": "Invoice Review — INV-2041 (resubmitted)",
  "dueDate": "2026-09-30T17:00:00Z"
}

Field	Type	Required	Description
`name`	`string`	No	The new name. Trimmed; must not be blank and must be at most 100 characters. `null` is refused.
`status`	`string`	No	`Complete` or `InProgress`, case ignored. `Complete` marks the checklist complete and `InProgress` reopens it, exactly as Mark a Checklist Complete and Reopen a Checklist do. `Scheduled` and `RecentlyComplete` cannot be set, and `null` is refused.
`dueDate`	`string` (date-time) or `null`	No	The due date for the outstanding work, or `null` to remove it.

Example

PATCH https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18
X-API-KEY: your-api-key-here
Content-Type: application/json

{
  "dueDate": "2026-09-30T17:00:00Z",
  "status": "Complete"
}

HTTP/1.1 200 OK

The body is the updated Checklist Detail object. Abridged:

{
  "dueDate": "2026-09-30T17:00:00Z",
  "allTasksComplete": false,
  "tags": [],
  "parameters": [],
  "tasks": [],
  "key": "9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "name": "Invoice Review — INV-2041",
  "url": "https://app.checkflow.io/Checklist/Index?checklistKey=9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "status": "Complete",
  "startDateTime": "2026-09-14T08:12:40.513Z",
  "endDateTime": "2026-09-22T10:04:17.220Z",
  "createdDateTime": "2026-09-14T08:12:40.513Z",
  "isShared": false,
  "isArchived": false,
  "template": {
    "key": "3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
    "name": "Invoice Review",
    "url": "https://app.checkflow.io/Template/Index?templateKey=3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
    "description": "Check, approve and schedule payment of a supplier invoice.",
    "version": 3
  }
}

Responses

Status	Code	When
`200`	—	The updated Checklist Detail object.
`400`	`VALIDATION_ERROR`	The body names none of `name`, `status` and `dueDate`, or is not a JSON object; or `field` is `key` (not a GUID), `name` (blank, `null` or over 100 characters), `status` (not `Complete` or `InProgress`) or `dueDate` (not a real date).
`403`	`FORBIDDEN`	The acting member may not run this checklist.
`404`	`CHECKLIST_NOT_FOUND`	No checklist with that key exists in the workspace.

Notes

How the due date is applied. A checklist has no due date of its own. dueDate is written onto every visible task that is not a heading and is not yet finished; tasks whose due date the template computes from a due date rule are left to the rule. The dueDate in the response is read back from the tasks, so it can be earlier than the date you sent when a rule-governed task is due sooner, and absent when nothing is outstanding. Each task whose date changes has its reminders rescheduled.
Order. The fields are applied in the order name, dueDate, status, so a call that sets a due date and completes the checklist dates the work and then closes it. A refusal on a later field does not undo an earlier one: a body with a valid name and an invalid status renames the checklist and then answers 400.
Repeats. Asking for the name, status or due date the checklist already has writes nothing and sends no notification.
Completing or reopening through status sends the same notifications, and fires the same webhook, as the dedicated routes.
The MCP tool update_checklist cannot send null, so it takes clearDueDate: true to remove the due date instead.

Delete a Checklist

Permanently deletes a checklist, its tasks and the comments, field values, files and tags they hold. To hide a checklist while keeping it, archive it instead.

DELETE /v3/checklists/{key}

danger

Deleting a checklist cannot be undone. There is no recycle bin and no restore route.

Parameters

Name	In	Type	Required	Description
`key`	path	`string` (GUID)	Yes	The checklist's key.

Example

DELETE https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18
X-API-KEY: your-api-key-here

HTTP/1.1 204 No Content

The response has no body.

Responses

Status	Code	When
`204`	—	The checklist was deleted.
`400`	`VALIDATION_ERROR`	`field` is `key`: the key is not a GUID.
`403`	`FORBIDDEN`	The acting member may not run this checklist.
`404`	`CHECKLIST_NOT_FOUND`	No checklist with that key exists in the workspace — including one you have already deleted.

Notes

Any Linked Checklist field in another checklist that points at this one is unlinked first.
Standalone tasks attached to the checklist are not deleted; they become unattached standalone tasks.
The whole workspace, except the acting member, is notified that the checklist was deleted.

Get Checklist Activity

Returns what has happened on a checklist — who did what, and when — as a paginated feed, most recent first by default.

GET /v3/checklists/{key}/activity

Parameters

Name	In	Type	Required	Description
`key`	path	`string` (GUID)	Yes	The checklist's key.
`sort`	query	`string`	No	`occurredAt`, `occurredAt:asc` or `occurredAt:desc`. Default `occurredAt:desc`. `occurredAt` alone sorts descending.
`pageSize`	query	`integer`	No	1–100, default 50. A value outside the range is replaced by 50.
`after`	query	`string`	No	The `nextCursor` from the previous page.

Unlike the checklist list, the cursor resumes from an entry rather than a row number, so you may change pageSize between pages. You may not change sort, and a cursor from another checklist's feed is refused.

Example

GET https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18/activity?pageSize=3
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

{
  "items": [
    {
      "occurredAt": "2026-09-16T11:02:55.310Z",
      "actor": { "name": "Priya Patel", "email": "priya.patel@acme.example" },
      "description": "Updated date/time picker 'Payment Date' value to '2026-10-15'",
      "taskKey": "7e3a9c1d-5b2f-4e8a-9d06-1c4f8b2e7a59",
      "taskName": "Schedule the payment",
      "fieldKey": "d2f7b4e9-1a6c-4c3d-8e25-9b0a3f6c1d74",
      "fieldName": "Payment Date",
      "dateTimeValue": "2026-10-15T00:00:00Z"
    },
    {
      "occurredAt": "2026-09-15T09:44:12.004Z",
      "actor": { "name": "James Okafor", "email": "james.okafor@acme.example" },
      "description": "Completed task 'Check the invoice details'",
      "taskKey": "1f8b3d6e-9a2c-4f7b-b0e5-3c7a9d1e4f62",
      "taskName": "Check the invoice details"
    },
    {
      "occurredAt": "2026-09-15T09:41:03.870Z",
      "actor": { "name": "James Okafor", "email": "james.okafor@acme.example" },
      "description": "Updated short text 'Invoice Number' value to 'INV-2041'",
      "taskKey": "1f8b3d6e-9a2c-4f7b-b0e5-3c7a9d1e4f62",
      "taskName": "Check the invoice details",
      "fieldKey": "a3d6f9b2-7e1c-4b5a-9f08-2c4e6d8b1a73",
      "fieldName": "Invoice Number"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoib2NjdXJyZWRBdDpkZXNjIiwibHYiOiI4ODQxMiJ9",
  "hasMore": true,
  "total": 14
}

Responses

Status	Code	When
`200`	—	A page of Activity Entry objects. `total` counts the whole feed, not the page.
`400`	`VALIDATION_ERROR`	`field` is `key` (not a GUID), `sort` (anything other than `occurredAt` with an optional direction) or `after` (unreadable, from another feed, or issued under the other order).
`403`	`FORBIDDEN`	The acting member may not see this checklist: their checklist permission on the template does not let them view it, and nothing in it is assigned to them.
`404`	`CHECKLIST_NOT_FOUND`	No checklist with that key exists in the workspace.

Notes

Most entries are written a second or two after the event they describe, so the feed is not the way to confirm a write you have just made — the response to the write is. occurredAt is the time of the event, so the feed stays in order.
To read the activity of one task, use the task's own feed on Checklist Tasks.

Archive a Checklist

Hides a checklist without deleting anything. An archived checklist is left out of List Checklists and search unless includeArchived is true, and out of the Tasks grid, the analytics and its template's listings. Its tasks, comments and field values are kept, it can still be read by key, and unarchiving brings it back.

POST /v3/checklists/{key}/archive

Parameters

Name	In	Type	Required	Description
`key`	path	`string` (GUID)	Yes	The checklist's key.

Request Body

This endpoint takes no request body.

Example

POST https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18/archive
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

The body is the Checklist object — the list shape, without tasks:

{
  "key": "9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "name": "Invoice Review — INV-2041",
  "url": "https://app.checkflow.io/Checklist/Index?checklistKey=9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "status": "Complete",
  "startDateTime": "2026-09-14T08:12:40.513Z",
  "endDateTime": "2026-09-22T10:04:17.220Z",
  "createdDateTime": "2026-09-14T08:12:40.513Z",
  "isShared": false,
  "isArchived": true,
  "template": {
    "key": "3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
    "name": "Invoice Review",
    "url": "https://app.checkflow.io/Template/Index?templateKey=3f2b8c1e-7a4d-4e5b-9c61-2d8f0a7b6e14",
    "version": 3
  }
}

Responses

Status	Code	When
`200`	—	The checklist, now archived.
`400`	`VALIDATION_ERROR`	`field` is `key`: the key is not a GUID.
`403`	`FORBIDDEN`	The acting member is not an Administrator. A key that acts as the workspace is always refused.
`404`	`CHECKLIST_NOT_FOUND`	No checklist with that key exists in the workspace.

Notes

Archiving a checklist that is already archived succeeds and changes nothing.
When the checklist changes state, the whole workspace, except the acting member, is notified.

Unarchive a Checklist

Takes a checklist back out of the archive, so it appears in the list, the Tasks grid and the analytics again.

DELETE /v3/checklists/{key}/archive

Parameters

Name	In	Type	Required	Description
`key`	path	`string` (GUID)	Yes	The checklist's key.

Example

DELETE https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18/archive
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

The body is the Checklist object, as for Archive a Checklist, with isArchived: false.

Responses

Status	Code	When
`200`	—	The checklist, no longer archived.
`400`	`VALIDATION_ERROR`	`field` is `key`: the key is not a GUID.
`403`	`FORBIDDEN`	The acting member is not an Administrator.
`404`	`CHECKLIST_NOT_FOUND`	No checklist with that key exists in the workspace.

Notes

Unarchiving a checklist that is not archived succeeds and changes nothing. A real change notifies the whole workspace, as archiving does.

Mark a Checklist Complete

Stamps a checklist finished and notifies the people involved. It does not complete the checklist's tasks — a checklist can be closed with work still outstanding — so the response reports isComplete and allTasksComplete separately. To complete individual tasks, see Checklist Tasks.

POST /v3/checklists/{key}/complete

Parameters

Name	In	Type	Required	Description
`key`	path	`string` (GUID)	Yes	The checklist's key.

Request Body

This endpoint takes no request body.

Example

POST https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18/complete
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

{
  "key": "9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "name": "Invoice Review — INV-2041",
  "url": "https://app.checkflow.io/Checklist/Index?checklistKey=9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "isComplete": true,
  "endDateTime": "2026-09-22T10:04:17.220Z",
  "allTasksComplete": false
}

Responses

Status	Code	When
`200`	—	A Completion object.
`400`	`VALIDATION_ERROR`	`field` is `key`: the key is not a GUID.
`403`	`FORBIDDEN`	The acting member may not run this checklist.
`404`	`CHECKLIST_NOT_FOUND`	No checklist with that key exists in the workspace.

Notes

Administrators and everybody assigned to the checklist, except the acting member, are notified, and the checklist-completed webhook event fires.
Completing a checklist that is already complete succeeds, writes nothing, keeps the original endDateTime and notifies nobody.

Reopen a Checklist

Takes the completion stamp off a checklist and puts it back in progress. Tasks that were completed stay completed, so a reopened checklist can come back with allTasksComplete: true.

DELETE /v3/checklists/{key}/complete

Parameters

Name	In	Type	Required	Description
`key`	path	`string` (GUID)	Yes	The checklist's key.

Example

DELETE https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18/complete
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

{
  "key": "9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "name": "Invoice Review — INV-2041",
  "url": "https://app.checkflow.io/Checklist/Index?checklistKey=9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18",
  "isComplete": false,
  "allTasksComplete": false
}

Responses

Status	Code	When
`200`	—	A Completion object.
`400`	`VALIDATION_ERROR`	`field` is `key`: the key is not a GUID.
`403`	`FORBIDDEN`	The acting member may not run this checklist.
`404`	`CHECKLIST_NOT_FOUND`	No checklist with that key exists in the workspace.

Notes

Administrators and everybody assigned to the checklist, except the acting member, are notified that it was reopened. Reopening a checklist that is not complete succeeds, writes nothing and notifies nobody.

List Attached Tasks

Returns the standalone tasks attached to a checklist — tasks somebody raised against it, rather than the steps its template wrote down — oldest first. These are the one part of a checklist that Get a Checklist does not report.

GET /v3/checklists/{key}/attached-tasks

Parameters

Name	In	Type	Required	Description
`key`	path	`string` (GUID)	Yes	The checklist's key.

The list takes no filters and is not paginated: it is the checklist's complete list, the same whoever asks. Query parameters are ignored. To ask which attached tasks are yours, overdue or still open, use GET /v3/my-work?checklist={key}&includeStandalone=true on Tasks Grid, which is per-member and paginated.

Example

GET https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18/attached-tasks
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

{
  "tasks": [
    {
      "key": "6a2d8f4b-3e1c-4b7a-a9d5-0c8e2f6b4d13",
      "name": "Chase Northwind for the missing purchase order",
      "status": "Complete",
      "dueDateTime": "2026-09-18T17:00:00Z",
      "completedDateTime": "2026-09-17T15:22:48.091Z",
      "completedBy": { "name": "Priya Patel", "email": "priya.patel@acme.example" },
      "createdDateTime": "2026-09-15T10:05:31.644Z",
      "createdBy": { "name": "Sarah Chen", "email": "sarah.chen@acme.example" },
      "assignees": [
        { "id": 12, "type": "Group", "name": "Finance Team" },
        { "id": 1044, "type": "TeamMember", "name": "Priya Patel" }
      ],
      "isAssignedExclusively": false,
      "url": "https://app.checkflow.io/Checklist/Index?checklistKey=9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18&checklistTaskId=58213"
    }
  ]
}

Responses

Status	Code	When
`200`	—	An object whose `tasks` array holds Attached Task objects. Empty when nothing is attached.
`400`	`VALIDATION_ERROR`	`field` is `key`: the key is not a GUID.
`403`	`FORBIDDEN`	The acting member may not see this checklist: their checklist permission on the template does not let them view it, and nothing in it is assigned to them.
`404`	`CHECKLIST_NOT_FOUND`	No checklist with that key exists in the workspace.

Notes

A checklist whose template has Tasks Can Be Attached switched off still returns whatever is already attached to it.
There is no route for one attached task under this one. Read and change each task at /v3/tasks/{taskKey} on Standalone Tasks.

Returns whether a checklist has a public link and the conditions on it. See Share a Checklist for how shared checklists behave for visitors.

GET /v3/checklists/{key}/share

Parameters

Name	In	Type	Required	Description
`key`	path	`string` (GUID)	Yes	The checklist's key.

Example

GET https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18/share
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

A checklist that has never been shared:

{
  "isShared": false,
  "isPasswordProtected": false,
  "isExpired": false,
  "expireOnceComplete": false,
  "isReadOnly": false
}

Responses

Status	Code	When
`200`	—	A Share object.
`400`	`VALIDATION_ERROR`	`field` is `key`: the key is not a GUID.
`403`	`FORBIDDEN`	The acting member may not see this checklist: their checklist permission on the template does not let them view it, and nothing in it is assigned to them.
`404`	`CHECKLIST_NOT_FOUND`	No checklist with that key exists in the workspace.

Gives a checklist a public link, or changes the conditions on the link it already has. Anybody holding the returned sharedUrl can open the checklist without signing in, subject only to the password and expiry you set here.

PUT /v3/checklists/{key}/share

Parameters

Name	In	Type	Required	Description
`key`	path	`string` (GUID)	Yes	The checklist's key.

Request Body

The body is the whole shared state, not a change to it: a field you leave out is set to its default. {} shares the checklist with no password, no expiry and no restrictions. A body is required, even if it is {}.

{
  "password": "Invoices2026",
  "expiresAt": "2026-12-31T17:00:00Z",
  "expireOnceComplete": true,
  "isReadOnly": false
}

Field	Type	Required	Description
`password`	`string`	No	The password visitors must enter. At least 8 characters, with a number, a lower-case letter and an upper-case letter. Not trimmed — spaces are part of the password. Omit or send `null` for no password.
`expiresAt`	`string` (date-time)	No	When the link stops working, in UTC, recorded to the second. Must be on or after 1 January 1753. A date in the past is accepted and reported as `isExpired: true`. Omit for no expiry.
`expireOnceComplete`	`boolean`	No	`true` to close the link once all the checklist's tasks are done. Default `false`.
`isReadOnly`	`boolean`	No	`true` to let visitors read the checklist but not work through it. Default `false`.

warning

Because the password is stored as a hash, there is no way to say "keep the current password". A PUT without password removes it. To change one setting, read the share first, send every setting back and include the password again. Check isPasswordProtected in the response.

Example

PUT https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18/share
X-API-KEY: your-api-key-here
Content-Type: application/json

{
  "password": "Invoices2026",
  "expiresAt": "2026-12-31T17:00:00Z",
  "expireOnceComplete": true
}

HTTP/1.1 200 OK

{
  "isShared": true,
  "sharedKey": "c8e1f4a7-3b9d-4d62-a0f5-7e2b9c4d1a86",
  "sharedUrl": "https://app.checkflow.io/Checklist/Shared?teamId=4821&sharedKey=c8e1f4a7-3b9d-4d62-a0f5-7e2b9c4d1a86",
  "isPasswordProtected": true,
  "expiresAt": "2026-12-31T17:00:00Z",
  "isExpired": false,
  "expireOnceComplete": true,
  "isReadOnly": false
}

Responses

Status	Code	When
`200`	—	The Share object as it now stands.
`400`	`VALIDATION_ERROR`	The body is missing or not valid JSON; or `field` is `key` (not a GUID), `password` (does not meet the rule) or `expiresAt` (before 1753).
`403`	`FORBIDDEN`	The acting member may not run this checklist.
`404`	`CHECKLIST_NOT_FOUND`	No checklist with that key exists in the workspace.
`409`	`CONFLICT`	Sharing is turned off for the checklist's template.

Notes

The sharedKey, and so the link, stays the same through every settings change. The only way to invalidate a link already handed out is to stop sharing and share again, which issues a new key.
Sending the same settings again writes nothing.
When a checklist starts being shared, Administrators and everybody assigned to it, except the acting member, are notified. Changing the settings of a live share notifies nobody.

Takes a checklist's public link down. The link stops working immediately, and the password, expiry and both flags are removed with it — sharing the checklist again starts from the defaults with a new key.

DELETE /v3/checklists/{key}/share

Parameters

Name	In	Type	Required	Description
`key`	path	`string` (GUID)	Yes	The checklist's key.

Example

DELETE https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18/share
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

{
  "isShared": false,
  "isPasswordProtected": false,
  "isExpired": false,
  "expireOnceComplete": false,
  "isReadOnly": false
}

Responses

Status	Code	When
`200`	—	The Share object, now unshared.
`400`	`VALIDATION_ERROR`	`field` is `key`: the key is not a GUID.
`403`	`FORBIDDEN`	The acting member may not run this checklist.
`404`	`CHECKLIST_NOT_FOUND`	No checklist with that key exists in the workspace.

Notes

Stopping the share of a checklist that is not shared succeeds and writes nothing.
This works even when sharing is turned off for the template, so turning that setting off never leaves a live link you cannot take down.
When a live share is removed, Administrators and everybody assigned to the checklist, except the acting member, are notified.

List Checklist Tags

Returns the checklist's own tags, by name, ordered by name. Tags on its tasks belong to those tasks and are read from the task on Checklist Tasks. To see every tag in the workspace, use Tags.

GET /v3/checklists/{key}/tags

Parameters

Name	In	Type	Required	Description
`key`	path	`string` (GUID)	Yes	The checklist's key.

Example

GET https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18/tags
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

{
  "tags": ["q3-audit", "urgent"]
}

Responses

Status	Code	When
`200`	—	An object whose `tags` array lists the tag names. The list is not paginated.
`400`	`VALIDATION_ERROR`	`field` is `key`: the key is not a GUID.
`403`	`FORBIDDEN`	The acting member may not see this checklist: their checklist permission on the template does not let them view it, and nothing in it is assigned to them.
`404`	`CHECKLIST_NOT_FOUND`	No checklist with that key exists in the workspace.

Tag a Checklist

Puts one or more tags on a checklist, by name. Tags are always named, never keyed, in v3. See Applying Tags for tags in the app.

POST /v3/checklists/{key}/tags

Parameters

Name	In	Type	Required	Description
`key`	path	`string` (GUID)	Yes	The checklist's key.

Request Body

{
  "tags": ["urgent", "supplier-review"]
}

Field	Type	Required	Description
`tags`	`array` of `string`	Yes	The tag names. Each is trimmed and must be at most 100 characters; blank names are dropped. At least one name, and at most 25 once duplicates are removed.

warning

A name the workspace has not used before creates a new tag — there is no separate create step. A misspelling does not fail; it adds a tag. The response's created array lists the names this call created, so check it, or read the existing names from GET /v3/workspace first.

Example

POST https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18/tags
X-API-KEY: your-api-key-here
Content-Type: application/json

{
  "tags": ["urgent", "supplier-review"]
}

HTTP/1.1 200 OK

{
  "created": ["supplier-review"],
  "tags": ["q3-audit", "supplier-review", "urgent"]
}

Responses

Status	Code	When
`200`	—	`tags` lists every tag now on the checklist, ordered by name; `created` lists the names this call added to the workspace, and is empty when every name already existed.
`400`	`VALIDATION_ERROR`	`field` is `key` (not a GUID) or `tags` (missing, empty, only blank names, more than 25 names, or a name over 100 characters).
`404`	`CHECKLIST_NOT_FOUND`	No checklist with that key exists in the workspace.

Notes

Names are matched case-insensitively: Urgent and urgent are one tag, and sending both assigns it once.
Naming a tag the checklist already carries succeeds and writes nothing.

Untag a Checklist

Takes one tag off a checklist, by name. The name goes in the query string because a tag name may contain a slash, which a path segment cannot carry.

DELETE /v3/checklists/{key}/tags?name={name}

Parameters

Name	In	Type	Required	Description
`key`	path	`string` (GUID)	Yes	The checklist's key.
`name`	query	`string`	Yes	The tag name, URL-encoded. Matched case-insensitively; at most 100 characters after trimming.

Example

DELETE https://api.checkflow.io/v3/checklists/9d4e2b7a-1c3f-4a8e-b5d6-7e0f2a9c3b18/tags?name=supplier-review
X-API-KEY: your-api-key-here

HTTP/1.1 200 OK

{
  "tagDeleted": true,
  "tags": ["q3-audit", "urgent"]
}

Responses

Status	Code	When
`200`	—	`tags` lists the tags left on the checklist; `tagDeleted` is `true` when this was the tag's last use anywhere and the workspace no longer has it.
`400`	`VALIDATION_ERROR`	`field` is `key` (not a GUID) or `name` (missing, blank or over 100 characters).
`404`	`CHECKLIST_NOT_FOUND`	No checklist with that key exists in the workspace.

Notes

Tags are created by being used and removed when nothing uses them any more. Removing a tag from the last thing that carries it deletes it from the workspace, and tagDeleted tells you so. See Managing Tags.
Removing a tag the checklist does not carry succeeds, writes nothing and reports tagDeleted: false.

Checklist Tasks — completing, assigning, dating and filling in the tasks inside a checklist.
Templates — the templates checklists are started from, their parameters, and upgrading running checklists to a newer version.
Pagination — how cursors work across the list, search and activity routes.
Checklist Tools — the same operations as MCP tools for an AI assistant.

Endpoints​

The Checklist Object​

Template Reference​

Checklist Status​

The Checklist Detail Object​

Parameter​

The Completion Object​

The Activity Entry Object​

User Reference​

The Attached Task Object​

The Share Object​

List Checklists​

Parameters​

Example​

Responses​

Notes​

Create a Checklist​

Parameters​

Request Body​

Parameter Values​

Example​

Responses​

Notes​

Search Checklists by Field Value​

Parameters​

Request Body​

Matching Rules​

Example​

Responses​

Get a Checklist​

Parameters​

Example​

Responses​

Notes​

Update a Checklist​

Parameters​

Request Body​

Example​

Responses​

Notes​

Delete a Checklist​

Parameters​

Example​

Responses​

Notes​

Get Checklist Activity​

Parameters​

Example​

Responses​

Notes​

Archive a Checklist​

Parameters​

Request Body​

Example​

Responses​

Notes​

Unarchive a Checklist​

Parameters​

Example​

Responses​

Notes​

Mark a Checklist Complete​

Parameters​

Request Body​

Example​

Responses​

Notes​

Reopen a Checklist​

Parameters​

Example​

Responses​

Notes​

List Attached Tasks​

Parameters​

Example​

Responses​

Notes​

Get Share Settings​

Parameters​

Example​

Endpoints

The Checklist Object

Template Reference

Checklist Status

The Checklist Detail Object

Parameter

The Completion Object

The Activity Entry Object

User Reference

The Attached Task Object

The Share Object

List Checklists

Parameters

Example

Responses

Notes

Create a Checklist

Parameters

Request Body

Parameter Values

Example

Responses

Notes

Search Checklists by Field Value

Parameters

Request Body

Matching Rules

Example

Responses

Get a Checklist

Parameters

Example

Responses

Notes

Update a Checklist

Parameters

Request Body

Example

Responses

Notes

Delete a Checklist

Parameters

Example

Responses

Notes

Get Checklist Activity

Parameters

Example

Responses

Notes

Archive a Checklist

Parameters

Request Body

Example

Responses

Notes

Unarchive a Checklist

Parameters

Example

Responses

Notes

Mark a Checklist Complete

Parameters

Request Body

Example

Responses

Notes

Reopen a Checklist

Parameters

Example

Responses

Notes

List Attached Tasks

Parameters

Example

Responses

Notes

Get Share Settings

Parameters

Example