> ## 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.

## 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.

## 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.                                                      |