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, 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 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 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.
404	No action by that name.
429	Over the per-minute cap for this key. Wait for Retry-After seconds.