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:

{
  "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

More than one workspace and nothing chose one

{
  "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.

The workspace you named is not one this key reaches

{
  "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.

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.

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 explains the two layers.

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.