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

# 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](/permissions) if you are not sure whether you have it.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Store it as an environment variable">
    Keep the key out of your code and out of version control.

    ```bash theme={null}
    export GOOSY_API_KEY="paste-your-key-here"
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    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:

    ```json theme={null}
    { "ok": true, "balance": 1250 }
    ```

    Every action, its arguments and its answers are in the
    [API reference](/api-reference/overview).
  </Step>

  <Step title="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](/connect/claude-code) · [Claude Desktop](/connect/claude-desktop) ·
    [Codex](/connect/codex) · [Cursor and VS Code](/connect/cursor-vscode) ·
    [any other client](/connect/any-client).

    Once connected, the assistant lists the actions your permissions allow and
    can run them on your behalf.
  </Step>
</Steps>

## 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](/permissions).
* **`404`** — no such action at that address. Check the spelling against the
  [API reference](/api-reference/overview).
* **`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](/authentication) for how keys relate to your own
permissions, when to use a [service account](/api/service-accounts), and how to
rotate a key safely.


## Related topics

- [Connect any other client](/connect/any-client.md)
- [FAQ](/help/faq.md)
- [Your first week](/start/your-first-week.md)