Versioning and upgrades

Request and resolved version

Public REST paths use /v1/. The canonical date-version request header is X-AppForges-Api-Version; inspect X-AppForges-Resolved-Api-Version for the resolved value.

curl --fail-with-body "${APPFORGES_API_BASE_URL}/v1/users/me" \
  -H "Authorization: Bearer ${APPFORGES_ACCESS_TOKEN}" \
  -H "X-AppForges-Api-Version: 2026-04-01"

The server currently accepts legacy API-Version, but new integrations should use the canonical name. Without an explicit value, the server resolves a default; application creation does not guarantee an isolated historical schema. Check the actual resolved header. Invalid or unknown versions may return 400 with API_VERSION_INVALID / API_VERSION_UNKNOWN.

SDK and date versions

SDK package 0.59.4 follows the protos/spec tag; it is separate from the API date. Read package CHANGELOG and release notes before upgrading and run your contract tests.

Release workflows compare the shared API contract. Breaking 0.x changes require a MINOR increment; compatible PATCH releases still require source review. Added enum values can break exhaustive consumers and are not universally compatible.

Deprecation and migration

The gateway can emit standard Deprecation for deprecated endpoints and Warning for beta endpoints. It does not promise automatic Sunset dates, universal 410 after a deadline, or a fixed six-month migration window. Header resolution does not imply arbitrary historical schema conversion.

Review API Reference and Changelog, test authorized calls in staging, record request IDs and resolved versions, then deploy the client. Keep a tested version for rollback. An application default-version setting does not replace endpoint compatibility tests.

See quickstart and errors and retries.