Migrate one bounded integration at a time. Keep its v0 token active until the equivalent v1 reads and writes have been verified, then revoke the old token.
The machine-readable v0-to-v1 migration map classifies every one of the 87 frozen v0 runtime routes as equivalent, adaptation-required, or retained-v0 and records request, response, and semantic changes. Use it as an inventory gate; the guidance below explains the platform-wide changes.
Use the filterable route migration matrix for a human-readable view of all 87 routes, their exact v1 replacement, and every route-specific change.
| Concern | API v0 | API v1 |
|---|---|---|
| Authentication | Broad team token | Reveal-once scoped service credential |
| Endpoint | Global v0 host | Credential-derived regional /v1 host |
| Pagination | Page and limit | Opaque cursor and limit |
| Create retries | Generally unsafe | Required idempotency key |
| Concurrent project/task/template writes | No uniform public precondition | Strong resource ETags and required If-Match |
| Task descriptions | Literal plain text | Explicit plain-text or opt-in markdown-v1 |
| Errors | Historical response formats | Versioned error envelope with request id |
| Webhooks | Legacy unsigned delivery | HMAC-signed delivery v2 |
| Audit | General operational logging | Credential and mutation audit events |
Suggested migration sequence
- Inventory the v0 resources, filters, writes, and webhook events used by the integration.
- Create a separate v1 credential with only the required read scopes.
- Compare read results without changing production data.
- Add write scopes and idempotency keys only when the read comparison passes; add read-before-write ETag handling for endpoints whose v1 contract explicitly requires it.
- Create a v2 webhook and verify its exact raw-body signature.
- Switch the integration to the regional endpoint.
- Observe errors, latency, and audit events.
- Revoke the v0 token and remove it from every secret store.
Resource availability
API v1 currently creates and updates projects, tasks, time entries, and contacts, and manages signed webhook registrations. Projects can be completed, reopened, archived, and restored through durable asynchronous lifecycle operations. Tasks use explicit complete, reopen, archive, restore, and timer commands; time entries can be archived and restored. Task timers require both tasks:write and time-entries:write.
Lists, services, and tags now have create, get, update, archive, and restore operations in addition to
cursor-paginated reads. Grant their dedicated lists:read/write, services:read/write, and
tags:read/write scopes only where needed. Public list creation supports project and task lists;
existing personal lists remain readable but cannot be created through API v1. Service responses can
contain billing rates and should be treated accordingly.
API v1 also covers call-note lifecycle, contact-group lifecycle, custom-field definitions and values, project templates, planned work, product and product-group catalog management, project statements, and credential-owned webhook delivery history. Product acquisition cost and project-statement budget data require explicit finance scope overlays. Value writes and planned-work replacement use strong compare-and-set revisions; do not translate v0 writes mechanically.
Project, task, and project-template writers must read the latest developer revision and send its
strong ETag through If-Match. Project lifecycle and template instantiation remain asynchronous
and should also use stable idempotency keys. Other protected domains, including custom-field values
and planned work, retain their resource-specific preconditions. See
resource concurrency.
The current v1 contract also covers personal-access credentials, native service accounts and resource grants, project sharing, conflict-safe task bulk changes, time-entry billing, bounded audit exports, and the durable change feed. The remaining planned public workflows are delegated OAuth, telephony, file sharing, commerce orders, report jobs, and imports. Keep only those bounded parts on v0 until an explicit v1 domain operation exists; do not emulate missing behavior through audit data, unrelated resources, or generic database mutations.
API v0 task-description writes always remain plain-text, including text containing Markdown-like
characters. Migrating to v1 does not reinterpret historical content. A v1 reader receives the
normalized descriptionFormat; opt in to markdown-v1 only when the integration intentionally
creates formatted content and sends the description and marker together.
Legacy reference differences
The migration audit found eight historical ReadMe pages whose advertised method and path do not exist in the frozen v0 runtime route inventory: contact and project DELETE-by-id, plus service and tag create, update, and delete operations.
The new reference follows the runtime contract. Old links to those eight pages land here until the historical documentation and production behavior have been reconciled. Do not implement a new dependency on those advertised paths.