> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truedy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

> Manage multiple Truedy workspaces with an account-scoped master API key.

Workspace management requires an account-scoped master API key. Existing workspace-scoped keys continue to work for the single workspace they belong to.

## Select a workspace

For resource requests made with a master key, send the target workspace in the `X-Truedy-Workspace-Id` header. The key must have an explicit grant for that workspace.

```bash theme={null}
curl https://api.truedy.ai/api/public/v1/agents \
  -H "Authorization: Bearer YOUR_MASTER_API_KEY" \
  -H "X-Truedy-Workspace-Id: org_workspace_id"
```

## List granted workspaces

```bash theme={null}
curl https://api.truedy.ai/api/public/v1/workspaces \
  -H "Authorization: Bearer YOUR_MASTER_API_KEY"
```

## Create a workspace

Workspace creation creates the Clerk Organization and initializes the matching Truedy workspace record. Use an idempotency key so retries cannot create duplicates.

```bash theme={null}
curl -X POST https://api.truedy.ai/api/public/v1/workspaces \
  -H "Authorization: Bearer YOUR_MASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: create-workspace-unique-request-id" \
  -d '{
    "name": "Acme Support",
    "slug": "acme-support"
  }'
```

## Grant an existing workspace

The master-key owner must be an administrator of the Clerk Organization.

```bash theme={null}
curl -X POST https://api.truedy.ai/api/public/v1/workspaces/org_workspace_id/access \
  -H "Authorization: Bearer YOUR_MASTER_API_KEY"
```

## Update a workspace

```bash theme={null}
curl -X PATCH https://api.truedy.ai/api/public/v1/workspaces/org_workspace_id \
  -H "Authorization: Bearer YOUR_MASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Support Europe"}'
```

Workspace deletion is intentionally not exposed by this first version. Deleting a Clerk Organization and its Truedy data requires an explicit retention and recovery policy.