diff --git a/.vale.ini b/.vale.ini
index a34bd24b..a1221d79 100644
--- a/.vale.ini
+++ b/.vale.ini
@@ -22,7 +22,8 @@ Vale.Repetition = NO
 #   two different ways, both GitHub issue shorthand forms used in the docs
 #   (with and without the "shorebirdtech/" org prefix), a file path
 #   placeholder, and the lowercase "shorebird" inside a FAQ anchor slug (URL
-#   fragments must stay lowercase, so it can't be capitalized in prose).
+#   fragments must stay lowercase, so it can't be capitalized in prose),
+#   and the api.shorebird.dev domain used in API reference links.
 # - Shorebird.Exclamation: the `existence` extension type doesn't support
 #   an exceptions list the way `capitalization` does (verified). Covers a
 #   table row documenting the literal "[!]" symbol from real `flutter
@@ -48,7 +49,7 @@ Vale.Repetition = NO
 #     direct privacy pledge reads better as "we never know" than as a
 #     passive "it never knows" (see PR #585 review discussion)
 TokenIgnores = (contact@shorebird\.dev), (console\.shorebird\.dev), \
-  (docs\.shorebird\.dev), (download\.flutter\.dev), (shorebird\.yaml), \
+  (docs\.shorebird\.dev), (api\.shorebird\.dev), (download\.flutter\.dev), (shorebird\.yaml), \
   (#can-you-use-shorebird-in-your-country), \
   (shorebird yaml), (shorebirdtech/shorebird#\d+), (shorebird#\d+), \
   (/path/to/flutter), \
diff --git a/src/content/docs/account/api.mdx b/src/content/docs/account/api.mdx
new file mode 100644
index 00000000..581f2ab4
--- /dev/null
+++ b/src/content/docs/account/api.mdx
@@ -0,0 +1,85 @@
+---
+title: API Reference
+description: Interact programmatically with the Code Push API
+sidebar:
+  order: 3
+---
+
+# API specification
+
+Interact programmatically with your Shorebird account. You can manage apps,
+releases, and over-the-air patches with the Shorebird Code Push API. It offers
+everything the `Shorebird` CLI does under the hood.
+
+The full, always-up-to-date reference is published as an OpenAPI 3 document:
+
+[**https://api.shorebird.dev/openapi.json**](https://api.shorebird.dev/openapi.json)
+
+Load that URL into any OpenAPI-compatible viewer to browse every endpoint,
+parameter, and schema interactively.
+
+## Base URL
+
+```
+https://api.shorebird.dev/api/v1
+```
+
+## Authentication
+
+Every request (other than the patch-check endpoint, see below) needs a bearer
+token:
+
+```
+Authorization: Bearer <token>
+```
+
+There are two kinds of tokens, and which one you use depends on context:
+
+- **API keys** (`sb_api_*`): long-lived,
+  [generated from the Shorebird console](https://docs.shorebird.dev/account/api-keys/).
+  Use these for CI pipelines, scripts, and any non-interactive automation.
+  Default expiration is 1 year, with options for 30 days and 90 days. Treat
+  these like any other long-lived secret.
+- **OAuth JWTs**: short-lived (15 minutes), issued by the interactive login flow
+  and refreshed automatically by the CLI. Use these for interactive/local
+  tooling. Given the fast expiration these should not be hardcoded anywhere.
+
+## Resource model
+
+The core objects and how they relate:
+
+- **Organization** → has **Users** as members, with a **Role** (owner, admin,
+  appManager, developer, viewer) each.
+- **App** → belongs to an organization, has **Collaborators** and **Channels**
+  (e.g. stable, beta).
+- **Release** → belongs to an app, has a platform (`android`, `ios`, `linux`,
+  `macos`, `windows`) and status (`draft`, `active`), and one or more **Release
+  Artifacts** (the platform/arch-specific binaries).
+- **Patch** → an OTA update tied to a release, with its own **Patch Artifacts**;
+  patches get promoted to a channel to go live for devices.
+
+## Endpoint groups
+
+The spec organizes endpoints under these tags. See the linked reference for full
+parameter and response detail on each:
+
+- **Users**: the authenticated user's account
+- **Apps**: create/list/delete apps, fetch app icons
+- **Collaborators**: manage who has access to an app
+- **Channels**: release channels for distributing patches
+- **Releases**: create and manage releases and their artifacts
+- **Patches**: create patches, register artifacts, promote to a channel, and
+  check for available patches from a device
+- **Metrics**: version distribution, device growth, patch
+  adoption/installs/downloads, active-hours and activity-heatmap analytics
+- **Organizations**: list memberships, org apps, and org users
+- **Diagnostics**: GCP upload/download speed-test URLs
+
+## Common patterns
+
+- **Errors** — non-2xx responses return a standard `ErrorResponse` shape with a
+  `code`, a human-readable `message`, and optional `details`. Check the spec for
+  the schema.
+- **Unauthenticated endpoint** — `POST /patches/check` is the one exception to
+  the auth rule above: it's what a device calls to check for an available patch,
+  and it doesn't require a bearer token.