Migrating from v1 and v2

The legacy v1 and v2 API keeps working, so there is no deadline to migrate. When you do, most of the work is mechanical: a new base URL, a new error format and paging with cursors instead of page numbers. This page lists what changes and the v3 equivalent of every legacy endpoint.

What Changes

	Legacy v1 and v2	v3
Base URL	https://app.checkflow.io/api/...	https://api.checkflow.io/v3/... (US) or https://api-eu.checkflow.io/v3/... (EU). See Base URLs.
Version	X-API-VERSION header	In the path. No version header.
API key	X-API-KEY	X-API-KEY — the same keys work. In v3, the key's Acts as setting decides whose permissions and name a request uses. See Authentication.
Identifiers	A mixture of GUID keys and integer ids	GUID keys for templates, checklists, tasks, fields and Data Sets; integer ids for members, groups and schedules. See Identifiers.
Dates	Varied	Always UTC ISO 8601, ending in Z. See Dates and Times.
Errors	Status code, varying bodies	One error body with a stable code. See Errors.
Lists	pageSize (max 10) and pageNumber	Cursor paging with pageSize (max 100), after and sort. See Pagination.
Retries	No protection against duplicates	Idempotency-Key on any write. See Idempotency.
Rate limits	Not published	Published budgets and X-RateLimit-* headers. See Rate Limits.
Webhooks	Subscribe by query string; unsigned deliveries	The same subscriptions and payloads, plus signed deliveries, three more events, a delivery log and replay. See Webhooks.
Documentation	Swagger at https://app.checkflow.io/swagger	Swagger UI and OpenAPI 3 at https://api.checkflow.io/swagger/ui.

Endpoint Map

Authentication

Legacy	v3
GET /api/authentication/validate	GET /v3/auth/test — also reports the region, plan and who the key acts as.

Checklists

Legacy	v3
GET /api/checklist/find	GET /v3/checklists filtered by templateKey and status, or POST /v3/checklists/search to find checklists by the values in their fields. See Checklists. There is no createIfNotExists: search, then create with an Idempotency-Key.
GET /api/checklist/details	GET /v3/checklists/{key}, then GET /v3/checklists/{key}/tasks and each task's /fields. See Checklist Tasks and Task Fields and Files.
GET /api/checklist/tasks	No direct equivalent. List the template's checklists with GET /v3/checklists?templateKey=… and read the task on each, or use the Tasks grid for tasks assigned to a person.
GET /api/checklist/uploaded-files	GET /v3/checklists/{checklistKey}/tasks/{taskKey}/fields/{fieldKey}/files. See Task Fields and Files.
POST /api/checklist	POST /v3/checklists.
POST /api/checklist/create-with-parameters	POST /v3/checklists with parameters.
POST /api/checklist/create-many	POST /v3/checklists once per checklist, each with its own Idempotency-Key.
POST /api/checklist/share	PUT /v3/checklists/{key}/share; GET reads the share settings and DELETE stops sharing.
DELETE /api/checklist	DELETE /v3/checklists/{key}. v3 also offers POST /v3/checklists/{key}/archive for a reversible alternative.
DELETE /api/checklist/delete-many	DELETE /v3/checklists/{key} once per checklist.

Tasks

Legacy	v3
GET /api/task/details	GET /v3/checklists/{checklistKey}/tasks/{taskKey}. See Checklist Tasks.
PUT /api/task/status	POST or DELETE on .../tasks/{taskKey}/complete to complete or reopen a task, and on .../not-applicable to mark it not applicable or clear that.
GET /api/task/assignments	GET .../tasks/{taskKey}/assignees.
PUT /api/task/assignments	PUT .../tasks/{taskKey}/assignees.
POST /api/task/assign-by-name	PUT .../tasks/{taskKey}/assignees — v3 accepts members and groups by name as well as by id.
DELETE /api/task/assignments	DELETE .../tasks/{taskKey}/assignees.
POST /api/task/comment	POST .../tasks/{taskKey}/comments.
PUT /api/task/update-task-content	PUT .../tasks/{taskKey}/fields to set several fields at once, or PUT .../fields/{fieldKey} for one. See Task Fields and Files for the value format of each control.

v3 adds due dates, snoozes, tags, activity, file uploads and table rows on checklist tasks, and a whole API for standalone tasks.

Templates

Legacy	v3
GET /api/template/templates	GET /v3/templates. See Templates.
GET /api/template/tasks	GET /v3/templates/{key}, or GET /v3/templates/{key}/document for the whole template as a template document.
GET /api/template/task-content	GET /v3/templates/{key}/document — every task's controls with their settings.

v3 can also create templates, publish new versions, copy, archive, set permissions and upgrade running checklists. See Templates and Template Drafts.

Team

Legacy	v3
GET /api/team/members-and-groups	GET /v3/workspace returns members and groups together, with tags and templates.
GET /api/team/members	GET /v3/members. See Members and Groups.
GET /api/team/groups	GET /v3/groups.

Tags

Legacy	v3
GET /api/tag/tags	GET /v3/tags, which also reports how often each tag is used. See Tags.
POST /api/tag	No create step. A tag is created the first time you apply it.
DELETE /api/tag	No direct equivalent. A tag is removed when it is taken off the last thing that carries it.
POST /api/tag/assignment	POST /v3/checklists/{key}/tags, POST /v3/checklists/{checklistKey}/tasks/{taskKey}/tags or POST /v3/tasks/{taskKey}/tags.
DELETE /api/tag/assignment	DELETE on the same routes, naming the tag.

Data Sets

The Data Set routes carry over almost one for one. Data Sets, fields, records and views are addressed by key instead of id, and updates use PATCH instead of PUT.

Legacy	v3
/api/data-sets and /api/data-sets/{dataSetId}	/v3/data-sets and /v3/data-sets/{dataSetKey}.
.../fields, .../records, .../records/bulk, .../views	The same paths under /v3/data-sets/{dataSetKey}/.
PUT on a Data Set, field, record or view	PATCH.
POST /api/data-sets/import	POST /v3/data-sets/import.
GET /api/data-sets/{dataSetId}/export	GET /v3/data-sets/{dataSetKey}/export.

v3 adds POST /v3/data-sets/{dataSetKey}/import to replace a Data Set's records from CSV, and GET .../connections to see which templates use it. See Data Sets.

Analytics

Legacy	v3
GET /api/analytics/all	No v3 equivalent yet. Keep using the legacy endpoint.

Webhooks

Legacy	v3
GET /api/web-hook/subscriptions	GET /v3/webhooks.
POST /api/web-hook/subscribe	POST /v3/webhooks.
DELETE /api/web-hook/unsubscribe	DELETE /v3/webhooks/{id}.

Both APIs manage the same subscriptions, and a v2 and a v3 subscription to the same event receive the same payload, so your receiving code does not change. v3 adds three events (checklist_completed, comment_created and task_assigned), checks scope keys and target URLs, signs every delivery with a secret you can rotate, and keeps a delivery log you can replay from. See Differences from the v2 Webhooks API.

Zapier

The CheckFlow Zapier app uses the legacy API and is unaffected. You do not need to change your Zaps.

A Migration Checklist

1. Store the base URL for your workspace's region in configuration, and check it with GET /v3/auth/test.
2. Decide who each key should act as, and create a key per integration on the Team page.
3. Replace page-number loops with cursor loops. See Pagination.
4. Replace status-code handling with handling of the error code. See Errors.
5. Add an Idempotency-Key to every create.
6. Move webhook subscriptions to v3 and verify signatures. See Webhooks.
7. Remove the X-API-VERSION header.

Related Pages

• CheckFlow API v3 — the conventions every v3 endpoint shares.
• Getting Started — a first v3 integration, step by step.
• Legacy API Reference — the endpoints on the left of these tables.
• Webhooks — the part of a migration with the most behaviour to change.