Skip to main content
The endpoint reference under this section is generated from the API’s own description. The authored Pages API guide covers the REST-only Pages endpoints alongside those generated tool endpoints.

​
What every call has in common

  • One address per tool action, under https://app.goosybear.ai/api/v1/tools/.
  • POST with a JSON object of arguments — send {} when a tool takes none. REST-only endpoints can use a different path and method; see the Pages API guide.
  • A bearer key in the Authorization header, on every request.
  • For tool actions, ok in the body says whether the action succeeded. A tool call that reaches the service answers 200; an action that declines still answers 200 with "ok": false and a reason. The Pages API guide documents its Result envelopes and HTTP statuses.

​
Tool 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 tool actions over MCP

Each tool action is also an MCP tool with the same name, arguments and answers. The Pages preview-link endpoints are REST-only and have no MCP equivalent. 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.

​
Tool-call refusals

Tool-call refusals carry a machine-readable code and a plain-language message. The ones you will meet most: