Make your first call

Developer·4 minutes to read

Verified against docs/superpowers/specs/2026-09-15-p4-a-typed-http-api-openapi-webhooks.md §1.1, §4.2, §4.3; re-verified against the code at close-out.

What this does for you

You go from no credential to one authenticated request and the answer it returns.

Before you start

An organisation where you are an owner or an admin. A member cannot hold a key (Authentication and keys).
The Developer page in the app, reached from the organisation nav on a team and from Settings → General on every edition. It is where a key is created.
The origin your install answers on. The samples below read it from BOTSEON_API_ORIGIN and the key from BOTSEON_API_KEY; a page never prints the value of either.
A terminal, or Node with @botseon/sdk installed (The TypeScript SDK and headless mode).

Steps

These steps are followed at a terminal and on the Developer page; the API itself has no screen of its own, so no screenshot is shown here.

Open the Developer page and find the API keys card.
Give the key a name of 1 to 60 characters, choose a scope, and choose how long it lasts. The scope is Read, Write or Admin, and Read is the default; the expiry is 30 days, 90 days or 1 year, and 90 days is the default.
Press Create key. The full key is shown once, in a panel that says it is not shown again. Copy it now.
Put the key in your shell's environment under BOTSEON_API_KEY, and the origin under BOTSEON_API_ORIGIN. Do not pass a key on a command line: a command line is visible to every process and every log.
Send one read request. The answer is a JSON body with data and nextCursor, and the response carries an x-request-id header you can quote in a support request.
When you are finished with the key, revoke it from the same card. A revoked key is refused on the next request.

A worked example

List the bots your key's person can see:

curl -sS "$BOTSEON_API_ORIGIN/api/v1/bots?limit=5" \
  -H "authorization: Bearer $BOTSEON_API_KEY" \
  -H "accept: application/json"

The same call from Node, reading the two variables from the environment:

const res = await fetch(`${process.env.BOTSEON_API_ORIGIN}/api/v1/bots?limit=5`, {
  headers: {
    authorization: `Bearer ${process.env.BOTSEON_API_KEY}`,
    accept: 'application/json',
  },
});
if (!res.ok) throw new Error(`bots: ${res.status}`);
const page = (await res.json()) as { data: Array<{ id: string; name: string }>; nextCursor: string | null };
for (const bot of page.data) console.log(bot.id, bot.name);

What can go wrong

The first cell is the code the error envelope carries; the sentence beside it in error.message is fixed and nothing interpolates into it.

What you see	Why	What to do
`unauthenticated`	No key, a malformed bearer, an unknown, revoked or expired key, a key used on a route its class does not reach, a scope too narrow for the route, or a key whose creator is no longer an admin.	Check the header spelling, then the key's row on the Developer page. A scope mismatch answers the same way as no credential on purpose, so a probe learns nothing.
`not_found`	The row is not there, or it is there and your key's person may not read it.	Read the id from a list call rather than guessing it. A bot another member owns and has not shared reads the same way here as in the app.
`invalid_request`	The body failed the schema, or a required header is missing.	Read `details`, which carries the failing paths and their messages. It never carries a value you sent.
`payment_required`	The organisation needs a trial or a payment before this write.	Settle the account in the app, then retry.
`rate_limited`	A bucket is full.	Wait the number of seconds in `Retry-After` and retry.