From eddb270d981a5fb24e8071c05e39ae4904c40f74 Mon Sep 17 00:00:00 2001 From: dawn-ducky Date: Tue, 1 Sep 2026 09:56:49 -0500 Subject: [PATCH] Documentation for Code Push API To make our docs more AI/agent friendly added documentation for Shorebird Code Push API, including authentication methods, resource model, endpoint groups, and common patterns. Includes a direct link to the specification and built with inspiration from: https://vercel.com/docs/rest-api --- src/content/docs/account/api.mdx | 65 ++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 src/content/docs/account/api.mdx diff --git a/src/content/docs/account/api.mdx b/src/content/docs/account/api.mdx new file mode 100644 index 00000000..e101abf8 --- /dev/null +++ b/src/content/docs/account/api.mdx @@ -0,0 +1,65 @@ +--- +title: API Keys +description: Interact programatically 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 +``` + +There are two kinds of tokens, and which one you use depends on context: + +- **API keys** (`sb_api_*`): long-lived, [https://docs.shorebird.dev/account/api-keys/](generated from the Shorebird console). Use these for CI pipelines, scripts, and any non-interactive automation. They don't expire and aren't refreshed automatically, so treat them 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. + +