Deprecation policy

When a published /v1 route is retired, it follows this lifecycle. The rules here stay stable. Individual retirements are listed in the API changelog and marked on the API Reference.

published → deprecated (at least 90 days) → gone (410, kept indefinitely)

Deprecated

The route still works. It stays in the API Reference (struck through) and names its replacement.

Every response from that route — including errors — includes:

Header	Meaning
Deprecation	Announcement date (RFC 9745, @ + Unix timestamp)
Sunset	Removal instant (RFC 8594, HTTP-date, end of day GMT)
Link	Migration doc, only when a real URL exists

Minimum notice is 90 days from announcement to sunset. Sunset is set when we mark the route; there is no undated deprecation.

Watch the headers in your client. Do not wait for a human email.

Gone (410)

After sunset — or earlier when caller logging shows no live callers — the route answers 410 with error.code gone and a pointer to the replacement. It is not a 404. Keep calling the old path and you will keep getting 410 — that is intentional, so stale integrations can diagnose.

Example: POST /v1/projects/submit was removed; the successor is POST /v1/projects.

The six aliases announced on 2026-08-07 (agent-selection, deliverables zip/download, resume, human-review/resume) are now in this state. What to call instead is on Migrating to current v1 shapes.

Withdrawn from the reference

A route can also be withdrawn: taken out of this reference while it is still deprecated and answering with Deprecation / Sunset headers. Withdrawal is not a quiet removal — the route keeps working until it is gone, and its replacement is listed on Migrating to current v1 shapes. What changes is only that a new integrator can no longer pick it up by mistake.

We do this when a route is on its way out and showing it alongside its replacement would present two ways to do one thing.

What we will not do

• Withdraw a route without publishing its replacement first
• Remove a published route with less than 90 days notice, unless logging shows zero live callers
• Rename error.code strings without a major version bump