From ecf10442ed8d0cc3bec339721e65a8e8dfedf8b5 Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Thu, 15 Oct 2026 18:42:27 -0700 Subject: [PATCH 1/7] docs: explain shorebird api, pagination and error documentation_url --- src/content/docs/account/api.mdx | 75 ++++++++++++++++++++++++++++++-- 1 file changed, 72 insertions(+), 3 deletions(-) diff --git a/src/content/docs/account/api.mdx b/src/content/docs/account/api.mdx index c9b65cae..afccef9c 100644 --- a/src/content/docs/account/api.mdx +++ b/src/content/docs/account/api.mdx @@ -25,6 +25,64 @@ 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 + +The quickest way to call the API is `shorebird api`. It sends an authenticated +request using your current Shorebird credentials and prints the response, so +there is no token to copy and no headers to set. It is designed mainly for +coding agents and scripts: only the response body goes to stdout, and a failed +request exits with a non-zero status. It is modeled on +[`gh api`](https://cli.github.com/manual/gh_api), so its common flags work the +same way. + +`shorebird api` is available in Shorebird CLI releases after 1.6.128. + +```sh +# List the apps you have access to +shorebird api /apps + +# List the release versions of the app in the current project +shorebird api /apps/{appId}/releases --jq '.releases[].version' + +# Create a channel +shorebird api /apps/{appId}/channels -f channel=beta + +# Add query parameters to a GET request +shorebird api -X GET /apps/{appId}/metrics/patch-installs -f granularity=day +``` + +How it works: + +- **Endpoint**: a path relative to the base URL below, such as `/apps`. A full + URL under `https://api.shorebird.dev/api/v1` also works. URLs on any other + host are rejected, so your credentials are only sent to the Shorebird API. +- **`{appId}`**: replaced with the app ID from the current project's + `shorebird.yaml`, in the endpoint and in `-F` values. Pass `--flavor` to use a + flavor's app ID. +- **Authentication**: your `shorebird login` session, or the API key in the + `SHOREBIRD_TOKEN` environment variable. +- **`-X`, `--method`**: the HTTP method. The default is `GET`, or `POST` when + fields or `--input` are given. +- **`-f`, `--raw-field key=value`**: adds a string parameter. **`-F`, + `--field key=value`** adds a typed one: `true`, `false`, `null` and integers + become JSON values, and `@path` reads the value from a file (`@-` from + standard input). For `GET` requests, fields go in the query string; for other + methods they are sent as a JSON object body. +- **`--input file`**: sends a JSON file as the request body (`-` reads standard + input). Use it for nested JSON. Fields then go in the query string. +- **`--jq expression`**: prints the results of a jq query over the response. + Strings print without quotes, other values as JSON. A common subset of jq is + supported: paths (`.a.b`, `.[]`, `.[0]`, `?`), pipes, `,`, comparisons, + `and`/`or`/`not`, object and array construction, string interpolation, and + `length`, `keys`, `map`, `select`, `empty`, `first`, `last`, `sort_by`, + `unique`, `unique_by`, `join`, `to_entries`, `from_entries` and + `with_entries`. +- **Output and errors**: the response body is printed as-is. On a non-2xx + response the body is still printed, a one-line error goes to stderr, and the + command exits with status 1. +- **Retries**: `GET` requests are retried on transient failures. Other methods + are sent at most once. + ## Base URL ``` @@ -84,9 +142,20 @@ 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. +- **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. + + ```sh + cursor=$(shorebird api '/apps?per_page=50' --jq '.next_cursor') + shorebird api -X GET /apps -f per_page=50 -f cursor="$cursor" + ``` + - **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. From 1de9ef9a272a5809def8f64a7fc2c73828a7eb66 Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Thu, 15 Oct 2026 18:53:00 -0700 Subject: [PATCH 2/7] docs: fix the pagination loop and note --jq skips error bodies --- src/content/docs/account/api.mdx | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/src/content/docs/account/api.mdx b/src/content/docs/account/api.mdx index afccef9c..1801fed7 100644 --- a/src/content/docs/account/api.mdx +++ b/src/content/docs/account/api.mdx @@ -79,7 +79,9 @@ How it works: `with_entries`. - **Output and errors**: the response body is printed as-is. On a non-2xx response the body is still printed, a one-line error goes to stderr, and the - command exits with status 1. + command exits with status 1. `--jq` applies only to successful responses: on + an error, the raw error body goes to stdout instead, so scripts should check + the exit status before using the output. - **Retries**: `GET` requests are retried on transient failures. Other methods are sent at most once. @@ -151,9 +153,18 @@ parameter and response detail on each: next one. Without `per_page` or `cursor`, these lists return every item. Some newer list endpoints page by default, with the same parameters. - ```sh - cursor=$(shorebird api '/apps?per_page=50' --jq '.next_cursor') - shorebird api -X GET /apps -f per_page=50 -f cursor="$cursor" + This loop prints every app ID, one page of 50 at a time, and stops when a page + has no `next_cursor`: + + ```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 From 17c597f3bbfe9053d8989778294708c38120dd88 Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Thu, 15 Oct 2026 19:12:07 -0700 Subject: [PATCH 3/7] docs: trim shorebird api section; point to --help for options --- src/content/docs/account/api.mdx | 48 ++++---------------------------- 1 file changed, 6 insertions(+), 42 deletions(-) diff --git a/src/content/docs/account/api.mdx b/src/content/docs/account/api.mdx index 1801fed7..37a416e1 100644 --- a/src/content/docs/account/api.mdx +++ b/src/content/docs/account/api.mdx @@ -31,9 +31,10 @@ The quickest way to call the API is `shorebird api`. It sends an authenticated request using your current Shorebird credentials and prints the response, so there is no token to copy and no headers to set. It is designed mainly for coding agents and scripts: only the response body goes to stdout, and a failed -request exits with a non-zero status. It is modeled on -[`gh api`](https://cli.github.com/manual/gh_api), so its common flags work the -same way. +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` is available in Shorebird CLI releases after 1.6.128. @@ -43,47 +44,10 @@ shorebird api /apps # List the release versions of the app in the current project shorebird api /apps/{appId}/releases --jq '.releases[].version' - -# Create a channel -shorebird api /apps/{appId}/channels -f channel=beta - -# Add query parameters to a GET request -shorebird api -X GET /apps/{appId}/metrics/patch-installs -f granularity=day ``` -How it works: - -- **Endpoint**: a path relative to the base URL below, such as `/apps`. A full - URL under `https://api.shorebird.dev/api/v1` also works. URLs on any other - host are rejected, so your credentials are only sent to the Shorebird API. -- **`{appId}`**: replaced with the app ID from the current project's - `shorebird.yaml`, in the endpoint and in `-F` values. Pass `--flavor` to use a - flavor's app ID. -- **Authentication**: your `shorebird login` session, or the API key in the - `SHOREBIRD_TOKEN` environment variable. -- **`-X`, `--method`**: the HTTP method. The default is `GET`, or `POST` when - fields or `--input` are given. -- **`-f`, `--raw-field key=value`**: adds a string parameter. **`-F`, - `--field key=value`** adds a typed one: `true`, `false`, `null` and integers - become JSON values, and `@path` reads the value from a file (`@-` from - standard input). For `GET` requests, fields go in the query string; for other - methods they are sent as a JSON object body. -- **`--input file`**: sends a JSON file as the request body (`-` reads standard - input). Use it for nested JSON. Fields then go in the query string. -- **`--jq expression`**: prints the results of a jq query over the response. - Strings print without quotes, other values as JSON. A common subset of jq is - supported: paths (`.a.b`, `.[]`, `.[0]`, `?`), pipes, `,`, comparisons, - `and`/`or`/`not`, object and array construction, string interpolation, and - `length`, `keys`, `map`, `select`, `empty`, `first`, `last`, `sort_by`, - `unique`, `unique_by`, `join`, `to_entries`, `from_entries` and - `with_entries`. -- **Output and errors**: the response body is printed as-is. On a non-2xx - response the body is still printed, a one-line error goes to stderr, and the - command exits with status 1. `--jq` applies only to successful responses: on - an error, the raw error body goes to stdout instead, so scripts should check - the exit status before using the output. -- **Retries**: `GET` requests are retried on transient failures. Other methods - are sent at most once. +Run `shorebird api --help` for all options. For walking a paged list, see +[Pagination](#common-patterns) below. ## Base URL From ff9526e04bd560be3fa677315267dbd6fa9f8a52 Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Thu, 15 Oct 2026 20:02:03 -0700 Subject: [PATCH 4/7] docs: point to dedicated commands first; use an endpoint with no command as the example --- src/content/docs/account/api.mdx | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/src/content/docs/account/api.mdx b/src/content/docs/account/api.mdx index 37a416e1..9e0d4ace 100644 --- a/src/content/docs/account/api.mdx +++ b/src/content/docs/account/api.mdx @@ -27,11 +27,13 @@ build on it; expect to follow it. ## Calling the API from the command line -The quickest way to call the API is `shorebird api`. It sends an authenticated -request using your current Shorebird credentials and prints the response, so -there is no token to copy and no headers to set. It is designed mainly for -coding agents and scripts: only the response body goes to stdout, and a failed -request exits with a non-zero status. `--jq` applies only to successful +For everyday tasks, use the dedicated commands (`shorebird apps list`, +`shorebird releases list`, `shorebird metrics`, 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, 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). @@ -39,11 +41,8 @@ status before using the output. Find endpoints in `shorebird api` is available in Shorebird CLI releases after 1.6.128. ```sh -# List the apps you have access to -shorebird api /apps - -# List the release versions of the app in the current project -shorebird api /apps/{appId}/releases --jq '.releases[].version' +# 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 From b4244e0c89b446eba291c0871a1d37eae4ba46e6 Mon Sep 17 00:00:00 2001 From: Abhishek Doshi Date: Fri, 16 Oct 2026 17:41:50 +0530 Subject: [PATCH 5/7] docs: note shorebird api rejects --json and list it in agent entry points --- astro.config.mjs | 2 +- public/.well-known/agent-instructions.txt | 2 +- public/.well-known/agent-skills/index.json | 2 +- src/content/docs/account/api.mdx | 15 ++++++++------- src/content/docs/code-push/ci/scripting.mdx | 4 ++++ 5 files changed, 15 insertions(+), 10 deletions(-) diff --git a/astro.config.mjs b/astro.config.mjs index d70b787b..c8c68f9b 100644 --- a/astro.config.mjs +++ b/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 ' (releases after 1.6.128) 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: [ { diff --git a/public/.well-known/agent-instructions.txt b/public/.well-known/agent-instructions.txt index 3b7c8b08..703e3880 100644 --- a/public/.well-known/agent-instructions.txt +++ b/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 never prompt; they require `--confirm-name` set to the exact name being deleted. - 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 `. 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 `. OpenAPI 3.1 specification is available at `https://api.shorebird.dev/openapi.json`. From a shell, `shorebird api ` (Shorebird CLI releases after 1.6.128) 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 `.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. diff --git a/public/.well-known/agent-skills/index.json b/public/.well-known/agent-skills/index.json index de4dd0f8..1a9f981c 100644 --- a/public/.well-known/agent-skills/index.json +++ b/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" } ] diff --git a/src/content/docs/account/api.mdx b/src/content/docs/account/api.mdx index 9e0d4ace..3da927ec 100644 --- a/src/content/docs/account/api.mdx +++ b/src/content/docs/account/api.mdx @@ -32,10 +32,11 @@ For everyday tasks, use the dedicated commands (`shorebird apps list`, 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, 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 +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` is available in Shorebird CLI releases after 1.6.128. @@ -116,8 +117,8 @@ parameter and response detail on each: next one. Without `per_page` or `cursor`, these lists return every item. Some newer list endpoints page by default, with the same parameters. - This loop prints every app ID, one page of 50 at a time, and stops when a page - has no `next_cursor`: + 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="" @@ -130,6 +131,6 @@ parameter and response detail on each: done ``` -- **Unauthenticated endpoint** — `POST /patches/check` is the one exception to +- **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. diff --git a/src/content/docs/code-push/ci/scripting.mdx b/src/content/docs/code-push/ci/scripting.mdx index 45f22623..109e7330 100644 --- a/src/content/docs/code-push/ci/scripting.mdx +++ b/src/content/docs/code-push/ci/scripting.mdx @@ -64,6 +64,10 @@ Other commands, such as `shorebird release` and `shorebird patch`, accept `--json` and run non-interactively, but still print human-readable logs. Check their exit code rather than parsing their output. +`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 From df27327500eda3d6f7e846bcffd89dcf6c6cd343 Mon Sep 17 00:00:00 2001 From: Abhishek Doshi Date: Fri, 16 Oct 2026 17:46:16 +0530 Subject: [PATCH 6/7] docs: point everyday tasks at commands in the current CLI release --- src/content/docs/account/api.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/content/docs/account/api.mdx b/src/content/docs/account/api.mdx index 3da927ec..2c24e62b 100644 --- a/src/content/docs/account/api.mdx +++ b/src/content/docs/account/api.mdx @@ -28,14 +28,14 @@ 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 metrics`, 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 +`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). From 2abecc0e225a96c262305a0cbc19b606754033ed Mon Sep 17 00:00:00 2001 From: Eric Seidel Date: Fri, 16 Oct 2026 07:48:05 -0700 Subject: [PATCH 7/7] docs: shorebird api needs Shorebird 1.6.129 or newer --- astro.config.mjs | 2 +- public/.well-known/agent-instructions.txt | 2 +- src/content/docs/account/api.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/astro.config.mjs b/astro.config.mjs index c8c68f9b..5633ffe1 100644 --- a/astro.config.mjs +++ b/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. From the CLI, 'shorebird api ' (releases after 1.6.128) sends authenticated requests without handling tokens (reference: https://docs.shorebird.dev/account/api.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. From the CLI, 'shorebird api ' (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: [ { diff --git a/public/.well-known/agent-instructions.txt b/public/.well-known/agent-instructions.txt index 703e3880..ede612e2 100644 --- a/public/.well-known/agent-instructions.txt +++ b/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 never prompt; they require `--confirm-name` set to the exact name being deleted. - 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 `. OpenAPI 3.1 specification is available at `https://api.shorebird.dev/openapi.json`. From a shell, `shorebird api ` (Shorebird CLI releases after 1.6.128) 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 +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 `. OpenAPI 3.1 specification is available at `https://api.shorebird.dev/openapi.json`. From a shell, `shorebird api ` (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 `.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. diff --git a/src/content/docs/account/api.mdx b/src/content/docs/account/api.mdx index 2c24e62b..5fd89a63 100644 --- a/src/content/docs/account/api.mdx +++ b/src/content/docs/account/api.mdx @@ -39,7 +39,7 @@ 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` is available in Shorebird CLI releases after 1.6.128. +`shorebird api` needs Shorebird 1.6.129 or newer. ```sh # List the members of an organization (find its id with `shorebird account orgs`)