> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goosybear.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> How to read the reference, what every call has in common, and what the beta designation means.

Every page under this section is generated from the API's own description, so
it always matches what the service does. Nothing here is written by hand.

## What every call has in common

* **One address per action**, under `https://app.goosybear.ai/api/v1/tools/`.
* **`POST` with a JSON object** of arguments — send `{}` when an action takes
  none.
* **A bearer key** in the `Authorization` header, on every request.
* **`ok` in the body** says whether the action succeeded. A call that reaches
  the service answers `200`; an action that declines still answers `200` with
  `"ok": false` and a reason, so branch on `ok`, not on the status code.

## Actions that spend credits take two calls

An action that SPENDS CREDITS will not run in a single call, by design. The
first call answers `"status": "confirmation_required"` with a one-sentence
summary of what it would do and a `confirmation_id`, and charges nothing. Send
that id back on a second call to actually run it — there is no way around it.
Each such action says so on its own reference page; the rest run on one call.

## Actions that change things follow your permissions

Reading is bounded by your key and by the workspaces you can see. An action
that CHANGES something is bounded by a **capability** as well — a named
permission your role carries, the same one that decides what you can do with
your own hands in the app. Holding a key never widens that: if you may not do
a thing in Goosy Bear, your key may not do it either.

When your role does not carry the capability an action needs, the call answers
`"ok": false` and says so plainly. Those answers are deliberate about one
thing: they tell you when the decline is **not** about your credential, because
minting a new key would not change it. What changes it is a permission, granted
by an owner or admin — see [Who can use the API](/permissions), which lists
every decline a caller can meet and who can clear each one.

## The same actions over MCP

Each action is also an MCP tool with the same name, the same arguments and the
same answers. If you are connecting an assistant rather than writing code,
start at [Connect an assistant](/connect/claude-code) instead.

## Beta

The API is in beta. Addresses, request shapes and response shapes can still
change, and every response carries an `x-goosy-api: beta` header for as long as
that is true. Pin the version of the description you generated code against,
and re-generate when it changes — the [changelog](/changelog) is where changes
are recorded, dated.

## Refusals

Refusals carry a machine-readable `code` and a plain-language `message`. The
ones you will meet most:

| Status | What happened                                                                                                              |
| ------ | -------------------------------------------------------------------------------------------------------------------------- |
| `401`  | The key is missing, mistyped, revoked, or expired — all four answer identically on purpose.                                |
| `403`  | The key is valid, but access is switched off or your permissions do not cover it. See [Who can use the API](/permissions). |
| `404`  | No action by that name.                                                                                                    |
| `429`  | Over the per-minute cap for this key. Wait for `Retry-After` seconds.                                                      |


## Related topics

- [Goosy Bear documentation](/index.md)
- [Connect any other client](/connect/any-client.md)
- [Recipes](/api/recipes.md)