diff --git a/docs/architecture/api-first.md b/docs/architecture/api-first.md
index 16d1167..58d5b22 100644
--- a/docs/architecture/api-first.md
+++ b/docs/architecture/api-first.md
@@ -31,42 +31,7 @@ Webhooks are the primary mechanism for outbound integrations — ERPs, middlewar
 
 ## API Versioning & Compatibility
 
-epilot maintains strong backwards compatibility commitments for all public APIs. This ensures integrations remain stable and predictable over time.
-
-### Compatibility Guarantees
-
-- **No breaking changes to existing operations** — existing API endpoints, request/response schemas, and webhook/event payloads remain backwards compatible
-- **Additive changes only** — new fields, parameters, and endpoints may be added at any time; consumers should ignore unknown fields
-- **Minimum two years support** — any published API route is supported for at least two years from its release
-
-### Deprecation Policy
-
-When an API operation needs to be retired:
-
-1. **12-month notice period** — breaking changes are announced at least 12 months in advance
-2. **Deprecation in OpenAPI spec** — deprecated operations are marked in the [OpenAPI definitions](/api), which propagates to generated SDKs and documentation
-3. **Changelog announcement** — all deprecations are published in the [API Changelog](/api/changelog), available via RSS feed or email notifications
-
-:::note Exceptions
-Security vulnerabilities or regulatory/legal requirements may necessitate changes on shorter notice. In such cases, as much advance notice as feasible will be communicated.
-:::
-
-### What Constitutes a Breaking Change
-
-- Removing an API endpoint (sunsetting)
-- Removing or renaming a required request parameter
-- Removing or renaming a response field
-- Changing the type or format of an existing field
-- Changing error codes or response status codes for existing scenarios
-- Tightening validation on existing parameters
-
-### Staying Informed
-
-Subscribe to API changes through:
-
-- **[API Changelog](/api/changelog)** — detailed changelog with RSS feed support
-- **OpenAPI specs** — deprecation notices embedded in API definitions
-- **Release notes** — major platform updates announced via email to registered developers
+epilot maintains strong backwards compatibility commitments for all public APIs. See the [API Versioning](/api#versioning) section for details on compatibility guarantees, deprecation policies, and what constitutes a breaking change.
 
 ## Accessing APIs with MCP
 
diff --git a/src/pages/api.tsx b/src/pages/api.tsx
index 0c44831..0a0ce72 100644
--- a/src/pages/api.tsx
+++ b/src/pages/api.tsx
@@ -19,6 +19,7 @@ const toc = [
   { value: 'SDK', id: 'sdk', children: [], level: 2 },
   { value: 'Entities', id: 'entities', children: [], level: 2 },
   { value: 'Webhooks', id: 'webhooks', children: [], level: 2 },
+  { value: 'Versioning', id: 'versioning', children: [], level: 2 },
   { value: 'Changelog', id: 'changelog', children: [], level: 2 },
   { value: 'API Reference', id: 'api-reference', children: [], level: 2 },
 ];
@@ -113,6 +114,54 @@ yarn add @epilot/entity-client`}</code>
                     and signature verification.
                   </p>
 
+                  <h2 id="versioning">Versioning</h2>
+                  <p>
+                    epilot maintains strong backwards compatibility commitments for all public APIs.
+                  </p>
+                  <h3>Compatibility Guarantees</h3>
+                  <ul>
+                    <li>
+                      <strong>No breaking changes</strong> — existing API endpoints, request/response schemas, and
+                      webhook payloads remain backwards compatible
+                    </li>
+                    <li>
+                      <strong>Additive changes only</strong> — new fields, parameters, and endpoints may be added;
+                      consumers should ignore unknown fields
+                    </li>
+                    <li>
+                      <strong>Minimum two years support</strong> — any published API route is supported for at least two
+                      years
+                    </li>
+                  </ul>
+                  <h3>Deprecation Policy</h3>
+                  <ul>
+                    <li>
+                      <strong>12-month notice</strong> — breaking changes are announced at least 12 months in advance
+                    </li>
+                    <li>
+                      <strong>OpenAPI marking</strong> — deprecated operations are marked in API definitions
+                    </li>
+                    <li>
+                      <strong>Changelog</strong> — all deprecations are published in the{' '}
+                      <Link to="/api/changelog">API Changelog</Link>
+                    </li>
+                  </ul>
+                  <p>
+                    <em>
+                      Exceptions: Security vulnerabilities or regulatory requirements may necessitate changes on shorter
+                      notice.
+                    </em>
+                  </p>
+                  <h3>Breaking Changes</h3>
+                  <p>The following are considered breaking changes:</p>
+                  <ul>
+                    <li>Removing an API endpoint (sunsetting)</li>
+                    <li>Removing or renaming request parameters or response fields</li>
+                    <li>Changing field types or formats</li>
+                    <li>Changing error codes for existing scenarios</li>
+                    <li>Tightening validation on existing parameters</li>
+                  </ul>
+
                   <h2 id="changelog">Changelog</h2>
                   <p>
                     Breaking changes, new endpoints, and updates are published in the{' '}