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

# Choosing a workspace

> How a call decides which workspace it runs in, why an unclear call is refused rather than guessed at, and how every answer tells you where it ran.

Your key is tied to one account and cannot reach another. **Which workspace it
works in is a separate choice**, and you make it — Goosy never picks a workspace
for you.

## How a call decides

Four things settle it, in this order. The first one that applies wins.

1. **The call named one.** Pass `workspace` with the workspace's handle. This
   applies to that call only.
2. **The key is narrowed to one.** A key created for a single workspace always
   works there, and cannot be sent anywhere else.
3. **You have a default.** Set it under **Settings → API & MCP**, in the
   **Working in** panel. It is used whenever a call does not name one.
4. **There is only one workspace to reach.** Nothing to choose between.

If none of those settles it, the call is **refused** and told which workspaces
it could have chosen. That is deliberate: a call that quietly ran in the
wrong workspace is worse than a call that did not run.

## Every answer says where it ran

Successful calls carry the workspace they used and a short note saying why:

```json theme={null}
{
  "ok": true,
  "balance": 0,
  "workspace": "acme-main",
  "working_in": {
    "label": "working in: Acme Main",
    "note": "your default",
    "workspace": "acme-main",
    "source": "stored-default"
  }
}
```

The note is one of **this call only** (you named it), **this key is pinned
here** (the key is narrowed), **your default**, or **the only workspace this key
reaches**. Assistants read it out loud, so you can see which workspace an answer
is about before you act on it.

## When a call is refused

<AccordionGroup>
  <Accordion title="More than one workspace and nothing chose one">
    ```json theme={null}
    {
      "ok": false,
      "code": "workspace_ambiguous",
      "message": "This key reaches 3 workspaces in Acme Coffee, so library.search cannot pick one. Pass workspace on the call, or set a default workspace at Settings › API & MCP.",
      "workspaces": ["acme-main", "acme-events", "acme-wholesale"]
    }
    ```

    Every handle you could have used is listed, so a client can offer the choice
    and retry without asking us again. Set a default if you almost always mean
    the same one.
  </Accordion>

  <Accordion title="The workspace you named is not one this key reaches">
    ```json theme={null}
    {
      "ok": false,
      "code": "workspace_unreachable",
      "message": "\"acme-widgets\" is not a workspace this key reaches in Acme Coffee. Pass one of the workspaces listed below.",
      "workspaces": ["acme-main", "acme-events", "acme-wholesale"]
    }
    ```

    Either the handle is wrong, or the key's holder is not a member of that
    workspace. The same answer covers a **narrowed** key sent somewhere else —
    it says so, and lists the one workspace it may use.
  </Accordion>

  <Accordion title="You asked for a group of workspaces">
    Passing `workspace_set:` followed by a name is refused with
    `workspace_set_unsupported`. Working across several workspaces at once
    exists in the product; naming such a group from the API does not yet. Pass a
    single workspace instead.
  </Accordion>
</AccordionGroup>

<Note>
  A refused workspace still answers `200` with `"ok": false`. Nothing was
  rejected at the door — your key was fine and the action ran far enough to
  answer "name one of these". [Errors and
  refusals](/api/errors-and-refusals) explains the two layers.
</Note>

## Actions that take no workspace

A few things belong to the whole account rather than to one workspace — the
credit balance is the clearest example. Those actions take no `workspace`, and
asking for one would be a question with no answer.

## If you run several workspaces

* **Narrow a key per workspace.** Create one key for each workspace you automate.
  Nothing can then send that key to the wrong one, and revoking it affects only
  that workspace.
* **Set your default to the one you use most**, and pass `workspace` for the
  exceptions.
* **Read `working_in` in your own logs.** It is the cheapest way to catch an
  integration that has been writing to the wrong workspace.