Quickstart

Create a key and make your first call to your Goosy Bear account.

This guide takes you from an empty settings page to a working call, in about five minutes. You need permission to use the API — see Who can use the API if you are not sure whether you have it.

1. Create a key

   Open Settings → API & MCP and create a key. Give it a name that says where you will use it, so it is obvious later which key to revoke.

   The key is shown once, at the moment you create it. Copy it straight into your password manager or your project’s secret store. If you lose it, revoke it and create another one — there is no way to see it again.

   Keys never expire unless you say so. If this one is only for a trial, pick an expiry in the same dialog.

2. Store it as an environment variable

   Keep the key out of your code and out of version control.

   export GOOSY_API_KEY="paste-your-key-here"
   
3. Make a call

   Send the key as a bearer token on every request. Each action is its own address under https://app.goosybear.ai/api/v1/tools/, and takes a POST with a JSON body of arguments — an empty object when the action needs none.

   curl --request POST \
     --url "https://app.goosybear.ai/api/v1/tools/credits.balance" \
     --header "Authorization: Bearer $GOOSY_API_KEY" \
     --header "Content-Type: application/json" \
     --data '{}'
   

   A successful call answers with "ok": true and the action’s result:

   { "ok": true, "balance": 1250 }
   

   Every action, its arguments and its answers are in the API reference.

4. Or connect an AI assistant

   Assistants such as Claude Code, Codex and Cursor can talk to your account directly, using the same key. Pick your assistant and follow its page: Claude Code · Claude Desktop · Codex · Cursor and VS Code · any other client.

   Once connected, the assistant lists the actions your permissions allow and can run them on your behalf.

Reading the answer

A call that reaches the service answers 200, and the ok field says whether the action itself succeeded. An action that declines still answers 200 with "ok": false and a reason, so branch on ok rather than on the status code.

If a call is refused

• 401 — the key is missing, mistyped, revoked, or expired. Check the key on the API & MCP page and create a new one if you need to.
• 403 — the key is fine, but something is switched off or your permissions do not cover it. The response names which — see Who can use the API.
• 404 — no such action at that address. Check the spelling against the API reference.
• 429 — you have sent more calls than the account allows in a short window. Wait for the number of seconds in the Retry-After header, then retry.

Next

Read Authentication for how keys relate to your own permissions, when to use a service account, and how to rotate a key safely.