docs: explain shorebird api, pagination and error documentation_url

astro.config.mjs

@@ -225,7 +225,7 @@ Releases vs. Patches:
 
 Developer & Agent Interfaces:
 - Shorebird CLI: Use 'shorebird init', 'shorebird release', 'shorebird patch', and 'shorebird preview'. Roll back a patch with 'shorebird patches rollback'. For CI, scripts, and agents, pass the global '--json' flag for machine-readable output and authenticate with an API key in SHOREBIRD_TOKEN (reference: https://docs.shorebird.dev/code-push/ci/scripting.md)
-- Code Push REST API: OpenAPI 3.1 specification at https://api.shorebird.dev/openapi.json, base URL https://api.shorebird.dev/api/v1. Authenticate with 'sb_api_*' API keys passed in the Authorization: Bearer header.
+- Code Push REST API: OpenAPI 3.1 specification at https://api.shorebird.dev/openapi.json, base URL https://api.shorebird.dev/api/v1. Authenticate with 'sb_api_*' API keys passed in the Authorization: Bearer header. From the CLI, 'shorebird api <endpoint>' (Shorebird 1.6.129 or newer) sends authenticated requests without handling tokens (reference: https://docs.shorebird.dev/account/api.md).
 - Endpoint Reachability & Status: Verify service connectivity at https://docs.shorebird.dev/system/endpoint-reachability/.`,
           optionalLinks: [
             {

public/.well-known/agent-instructions.txt

@@ -28,6 +28,6 @@ Developers can always use Shorebird to build, manage releases, and patch Flutter
    - Without a terminal, in CI, or with `--json`, nothing waits for input: some prompts use a default (for example, `shorebird patch` without `--release-version` builds first to infer the release) and others fail with a hint naming the missing flag. Pass every input as a flag (`--app-id`, `--release-version`, or `--release-version=latest` for `shorebird patch`).
    - Deleting commands ask for confirmation in a terminal. Without a terminal, in CI, or with `--json`, they exit 64 and delete nothing unless confirmed by flag: `--yes` for `releases delete` and `channels delete`; `--confirm-name` with the app's display name for `apps delete`, which has no `--yes`. (Needs Shorebird 1.6.129 or newer; earlier releases use `--confirm-name` for every delete.)
    - Full reference: https://docs.shorebird.dev/code-push/ci/scripting.md
-2. OpenAPI REST API: When automating workflows programmatically, use `https://api.shorebird.dev/api/v1` with an `sb_api_*` API key passed in `Authorization: Bearer <token>`. OpenAPI 3.1 specification is available at `https://api.shorebird.dev/openapi.json`.
+2. OpenAPI REST API: When automating workflows programmatically, use `https://api.shorebird.dev/api/v1` with an `sb_api_*` API key passed in `Authorization: Bearer <token>`. OpenAPI 3.1 specification is available at `https://api.shorebird.dev/openapi.json`. From a shell, `shorebird api <endpoint>` (Shorebird 1.6.129 or newer) calls any endpoint with your `shorebird login` session or `SHOREBIRD_TOKEN`, prints only the response body, and exits 1 on a non-2xx response; `--jq` filters successful responses. Guide: https://docs.shorebird.dev/account/api.md
 3. Documentation reference: Every page on `docs.shorebird.dev` provides a Markdown twin at `<url>.md` and supports content negotiation via `Accept: text/markdown`. Curated index at `https://docs.shorebird.dev/llms.txt`.
 4. Changelog: `https://docs.shorebird.dev/changelog.md` lists what shipped, newest first. Entries for changes that shipped in the Shorebird CLI name that release. Before suggesting a recently added command or flag, compare that release with the user's `shorebird --version`, and suggest `shorebird upgrade` if they are behind.

public/.well-known/agent-skills/index.json

@@ -40,7 +40,7 @@
     {
       "name": "shorebird-api",
       "type": "api-reference",
-      "description": "Programmatic access to Shorebird apps, releases, artifacts, and channels via REST OpenAPI 3.1.",
+      "description": "Programmatic access to Shorebird apps, releases, artifacts, and channels via REST OpenAPI 3.1, or from the CLI with `shorebird api`.",
       "url": "https://docs.shorebird.dev/account/api.md"
     }
   ]

src/content/docs/account/api.mdx

@@ -25,6 +25,30 @@ The API does not yet carry a compatibility guarantee. It is the same API the
 Shorebird CLI and console use, and it changes when they do. You are welcome to
 build on it; expect to follow it.
 
+## Calling the API from the command line
+
+For everyday tasks, use the dedicated commands (`shorebird apps list`,
+`shorebird releases list`, `shorebird patches list`, and so on). `shorebird api`
+is for everything else: it calls any API endpoint, including ones with no
+dedicated command, and is designed mainly for coding agents and scripts. It
+sends an authenticated request using your current Shorebird credentials, so
+there is no token to copy and no headers to set. Only the response body goes to
+stdout (the global `--json` flag is not supported), and a failed request exits
+with a non-zero status. `--jq` applies only to successful responses; on an error
+the raw error body is printed instead, so check the exit status before using the
+output. Find endpoints in
+[the OpenAPI spec](https://api.shorebird.dev/openapi.json).
+
+`shorebird api` needs Shorebird 1.6.129 or newer.
+
+```sh
+# List the members of an organization (find its id with `shorebird account orgs`)
+shorebird api /organizations/ORG_ID/users --jq '.users[].user.email'
+```
+
+Run `shorebird api --help` for all options. For walking a paged list, see
+[Pagination](#common-patterns) below.
+
 ## Base URL
 
 ```
@@ -84,9 +108,29 @@ parameter and response detail on each:
 
 ## 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
+- **Errors**: non-2xx responses return a standard `ErrorResponse` with a
+  machine-readable `code`, a human-readable `message`, and optional `details`
+  and `documentation_url`. Branch on `code` rather than on `message`.
+- **Pagination**: the apps, releases and patches lists accept an optional
+  `per_page` (default 30, maximum 100) and `cursor`. A paged response includes
+  `next_cursor` when there is another page; pass it as `cursor` to fetch the
+  next one. Without `per_page` or `cursor`, these lists return every item. Some
+  newer list endpoints page by default, with the same parameters.
+
+  This script prints every app ID, one page of 50 at a time, stops when a page
+  has no `next_cursor`, and exits with status 1 if a request fails:
+
+  ```bash
+  cursor=""
+  while :; do
+    page=(-X GET /apps -f per_page=50)
+    [ -n "$cursor" ] && page+=(-f "cursor=$cursor")
+    shorebird api "${page[@]}" --jq '.apps[].app_id' || exit 1
+    cursor=$(shorebird api "${page[@]}" --jq '.next_cursor | select(. != null)') || exit 1
+    [ -n "$cursor" ] || break
+  done
+  ```
+
+- **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.

src/content/docs/code-push/ci/scripting.mdx

@@ -68,6 +68,10 @@ always holds exactly one JSON object. `--help` with `--json` works the same way:
 the usage text goes to stderr. This needs Shorebird 1.6.129 or newer; earlier
 releases leave stdout empty when these commands succeed.
 
+`shorebird api` is the exception: it prints the API response body as-is and
+rejects `--json`. See
+[Calling the API from the command line](/account/api/#calling-the-api-from-the-command-line).
+
 ### Success
 
 A successful command prints an object with `status` set to `success`. The