Versioning
Choose an API version, find out which one served a response, and plan for deprecations.
Versions
The REST API is served under /api/v1. Behavior changes ship as dated versions. The supported versions are 2026-05-26 and 2026-10-14. A request that does not name a version is served 2026-05-26, so existing integrations keep working without changes.
Choose a version
Send X-Project-Feed-Api-Version with one of the supported dates to opt in to that version.
X-Project-Feed-Api-Version: 2026-10-14Any other value returns 400 with the code unsupported_api_version. The error lists supportedVersions.
{
"type": "https://projectfeed.app/docs/api/errors#unsupported_api_version",
"title": "Bad Request",
"status": 400,
"detail": "Unsupported API version '2020-01-01'. Supported versions: 2026-05-26, 2026-10-14.",
"code": "unsupported_api_version",
"field": "X-Project-Feed-Api-Version",
"supportedVersions": ["2026-05-26", "2026-10-14"]
}Routes that are not part of the JSON API, such as SCIM and provider callbacks, ignore the header.
Response header
Every response under /api/v1, including errors and responses without a body such as 204 and 304, carries the version it was served under. SCIM responses and CORS preflight responses do not include this header.
HTTP/1.1 200 OK
X-Project-Feed-Api-Version: 2026-05-26Log this value with your request telemetry so a failed call can be tied to the version that served it.
Changes in 2026-10-14
These behaviors apply only to requests that send 2026-10-14.
- Write routes for tasks, subtasks, checklist items, projects, tags, webhooks, docs, and posts return 400 with an unknown_field issue for a body field they do not accept. Before: The field was ignored and the request succeeded.
- Every 429 uses the code rate_limit_exceeded, with a reason member that names the limit. Before: Per-user operation limits, such as creating comments, used the code rate_limited.
- A 429 uses the registered quota-exceeded problem type, https://iana.org/assignments/http-problem-types#quota-exceeded, as its type. Before: The type was https://projectfeed.app/docs/api/errors#rate_limit_exceeded, or #rate_limited for per-user operation limits. The violated-policies member is sent on every version.
- A resource in a private project the caller cannot open returns 404. Before: The request returned 403.
- A limit or offset that is not a whole number in range returns 400 with field set to limit or offset. Before: The value was clamped to the nearest valid one.
- A true or false query parameter, such as includeArchived or unread, returns 400 for any other value, and an invalid since returns 400. Before: Any other value counted as false, and an invalid since was ignored.
- The task list no longer returns total with offset paging, and the subtask, checklist item, and webhook lists no longer return total, because those counts were not exact for a page. Before: The task list total held the number of rows scanned. The other lists returned the size of the returned page.
Read the version from the API
GET /api/v1/limits and GET /api/v1/auth/check both return these fields. Neither needs a scope. pf auth check shows the same values.
{
"apiVersion": "v1",
"defaultDateVersion": "2026-05-26",
"supportedVersions": ["2026-05-26", "2026-10-14"]
}GET /api/version is a health check for the API service. It does not return version details.
Native app versions
GET /api/native/app-version on the app host is a public update check for the native apps. It accepts platform and channel once each: Android uses play or direct; iOS uses appstore or testflight. It needs no credential, does not read or set cookies, and is outside the dated integration API. CLI and MCP clients do not use it.
GET https://projectfeed.app/api/native/app-version?platform=android&channel=play{
"latestVersion": "1.0.0",
"latestBuild": 101,
"minSupportedBuild": 1,
"releaseNotes": "An update is available."
}Compare integer build numbers, not version labels. iOS CI builds use run.attempt; normalize those as run * 100 + attempt, so 12.2 is 1202. Plain integer builds keep their value. The minimum can be zero and cannot exceed the latest build. Release notes are plain text. Direct Android downloads also require apkUrl, sha256, size in bytes, and signingCertSha256. Digests are 64 lowercase hex characters without colons. The URL uses the app host's versioned media proxy; clients verify the APK bytes and the installed app's trusted certificate before installation. Store channels omit APK fields.
Invalid or incompatible query values return 400 with invalid_query. Unpublished channels return 503 with release_unavailable and Retry-After: 300. Other methods return 405 with Allow: GET. Successful checks cache for 300 seconds; errors are not cached. Keep any cached minimum-build policy when a check fails. No channel advertises a release before publication.
Deprecations
A deprecated behavior keeps working for at least 24 months after it is announced. Responses that use a deprecated behavior carry three headers: Deprecation with the announcement time as a Unix timestamp prefixed by @, Sunset with the date the behavior can be removed, and a Link header with rel="deprecation" that points to the migration notes.
- Offset paging on the task list and on task comments. Deprecated from
2026-10-14and removable afterSat, 14 Oct 2028 00:00:00 GMT. Page withcursorinstead. The headers are sent only on requests that passoffset.
Deprecation: @1791936000
Sunset: Sat, 14 Oct 2028 00:00:00 GMT
Link: <https://projectfeed.app/docs/api/conventions#pagination>; rel="deprecation"; type="text/html"Write clients that tolerate change
- Ignore response fields you do not recognize. New fields can appear on any response.
- Handle enum values you do not recognize instead of failing on them.
- Branch on the machine-readable error
codeinstead of the message text. See API errors. - Check
supportedVersionsat startup if your integration depends on a specific date version.