Workspaces

A workspace is the isolation boundary for all DialogBrain data. Each API key belongs to exactly one workspace and can only access resources within that workspace.

Workspace Scoping

Every API key is tied to a single workspace. When you make a request:

1. The API identifies which workspace owns the key
2. The request executes only within that workspace
3. Resources from other workspaces are not accessible

Foreign Resources Return 404

If your key is from Workspace A and you try to access a resource from Workspace B:

curl https://api.dialogbrain.com/api/v1/agents/12 \
  -H "X-API-Key: db_live_key_from_workspace_a"

The API returns 404 Not Found:

{
  "detail": "Agent 12 not found"
}

This is intentional — the API does not distinguish between "resource doesn't exist in any workspace" and "resource exists but in a different workspace." This prevents leaking information about other workspaces.

Platform Templates

DialogBrain provides platform templates (pre-built agents) that can be used within a workspace, but they have special restrictions:

• Not listable via the API: Templates are not returned by GET /agents (even though agents created from templates are)
• Not deletable via the API: You cannot DELETE a platform template via the REST API
• Visible in the UI: You can view and manage templates in the DialogBrain dashboard

Access Control Errors vs Not Found Errors

In some cases, the API returns 403 Forbidden instead of 404 Not Found:

Scenario	Status Code
Resource doesn't exist	404
Resource exists but voice is disabled for your workspace	403
Resource exists but you don't have permission to access it	403

Example: if your workspace doesn't have voice calls enabled and you try to create a call:

curl -X POST https://api.dialogbrain.com/api/v1/calls \
  -H "X-API-Key: db_live_YOUR_KEY" \
  -d '{"agent_id": 42, "target": "+1 555 0100"}'

The API might return:

{
  "detail": "Voice calls are not enabled for this workspace"
}

With status code 403 Forbidden — not 404.

Multiple Workspaces

If you work across multiple workspaces:

1. Create separate API keys for each workspace (one key per workspace)
2. Store keys in environment variables by workspace name
3. Your application logic determines which key to use for each request

---

See also: Authentication, Idempotency