> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Versioning & Edge Function Lifecycle — Integration

> Status: 📝 Planned Spec: specs/pf/specs/PF-89-api-versioning-edge-function-lifecycle.md Plan: specs/pf/plans/PF-89-api-versioning-edge-function-lifecycle-PLAN.…

**Status:** 📝 Planned\
**Spec:** `specs/pf/specs/PF-89-api-versioning-edge-function-lifecycle.md`\
**Plan:** `specs/pf/plans/PF-89-api-versioning-edge-function-lifecycle-PLAN.md`\
**Last updated:** 2026-03-24

***

## Purpose

Document how Edge Functions expose **application-level** API versions (header negotiation), how **contracts** are stored and validated in CI, and how **deprecation** signals integrate with observability (PF-48) and system health UI (PF-36).

***

## Scope

* **In scope:** `X-API-Version`, `withVersioning` middleware pattern, `supabase/functions/_shared/contracts/`, deprecation headers (`Deprecation`, `Sunset`, `Link`), CI contract-diff behavior.
* **Out of scope:** Supabase infrastructure path `/functions/v1/` (platform-managed); GraphQL; auto-generated OpenAPI in Phase 1–4 (spec deferred).

***

## Related platform documents

| Document                                                     | Relationship                                                                                      |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| [API\_CONTRACTS.md](./API_CONTRACTS.md)                      | REST path versioning narrative; must stay consistent with Edge header versioning once implemented |
| [CROSS\_CORE\_INTEGRATIONS.md](./CROSS_CORE_INTEGRATIONS.md) | All cores consume Edge Functions — versioning affects integration testing and rollout             |
| [EVENT\_CONTRACTS.md](./EVENT_CONTRACTS.md)                  | PF-48 may consume deprecated-usage events — payloads must be identifier-only (no PHI)             |

***

## Consumer obligations (all cores)

1. For **new or migrated** versioned functions: send `X-API-Version` or accept documented default (latest stable).
2. Handle **400** responses with migration guidance when version unsupported.
3. Respect **Sunset** by migrating before removal date; monitor PF-36 / Sentry warnings when enabled.

***

## Auth and tenant isolation

* Version negotiation is **orthogonal** to JWT and `verifyOrgAccess()` / `verifyOrgRole()` — no tenant data in version headers.
* Contract files are **server-side** only; never expose raw internal types to clients.

***

## Checklist (implementation)

* [ ] Pilot functions wrapped with `withVersioning` (opt-in).
* [ ] `docs/development/api-versioning-guide.md` published.
* [ ] `API_CONTRACTS.md` updated to cross-reference Edge header versioning.
* [ ] GitHub Actions contract validation runs on PRs touching `*.contract.ts` or pilot functions.