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

# Workspace agent mapping APIs

> Map workspace-side agent identifiers to Clawb agent IDs and query inventory metadata.

Use these APIs to maintain durable workspace inventory metadata.

## POST `/v1/workspace/agents/upsert`

Idempotently maps a workspace-side key to a Clawb `agent_id` inside the workspace.

### Auth

Workspace API key required.

<CodeGroup>
  ```http HTTP theme={null}
  X-Clawb-Api-Key: ck_live_...
  ```
</CodeGroup>

<CodeGroup>
  ```bash curl theme={null}
  curl -sS -X POST "https://api.clawb.ai/api/v1/workspace/agents/upsert" \
    -H "Content-Type: application/json" \
    -H "X-Clawb-Api-Key: ck_live_..." \
    -d '{
      "external_agent_key": "internal:payments-bot",
      "agent_id": "agt_01jv2fsk4mv9mtr9j3m7h6qk6y",
      "display_name": "Payments assistant",
      "labels": ["prod", "payments"],
      "environment": "prod",
      "source": "workspace_api",
      "status": "active"
    }'
  ```

  ```python Python SDK theme={null}
  from clawb_agent_sdk import ClawbClient, WorkspaceControlPlane

  client = ClawbClient(base_url="https://api.clawb.ai/api")
  control_plane = WorkspaceControlPlane(client=client, api_key="ck_live_replace_me")

  out = control_plane.workspace_agents_upsert(
      external_agent_key="internal:payments-bot",
      agent_id="agt_01jv2fsk4mv9mtr9j3m7h6qk6y",
      display_name="Payments assistant",
      labels=["prod", "payments"],
      environment="prod",
      source="workspace_api",
      status="active",
  )
  print(out)
  ```
</CodeGroup>

### Example response

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "item": {
      "external_agent_key": "internal:payments-bot",
      "agent_id": "agt_01jv2fsk4mv9mtr9j3m7h6qk6y",
      "display_name": "Payments assistant",
      "labels": ["prod", "payments"],
      "environment": "prod",
      "source": "workspace_api",
      "status": "active",
      "updated_at": "2026-02-28T00:00:00Z"
    }
  }
  ```
</CodeGroup>

## GET `/v1/workspace/agents`

Lists mappings in the workspace.

### Query params

* `environment`
* `status`
* `label`

<CodeGroup>
  ```bash curl theme={null}
  curl -sS "https://api.clawb.ai/api/v1/workspace/agents?environment=prod&status=active&label=payments" \
    -H "X-Clawb-Api-Key: ck_live_replace_me"
  ```

  ```python Python SDK theme={null}
  items = control_plane.workspace_agents_list(
      environment="prod",
      status="active",
      label="payments",
  )
  print(items)
  ```
</CodeGroup>

### Example response

<CodeGroup>
  ```json JSON theme={null}
  {
    "ok": true,
    "count": 2,
    "items": [
      {
        "external_agent_key": "internal:payments-bot",
        "agent_id": "agt_01jv2fsk4mv9mtr9j3m7h6qk6y",
        "display_name": "Payments assistant",
        "labels": ["prod", "payments"],
        "environment": "prod",
        "status": "active"
      },
      {
        "external_agent_key": "internal:refund-bot",
        "agent_id": "agt_01jv2fsk4mv9mtr9j3m7h6qk7a",
        "display_name": "Refund assistant",
        "labels": ["prod", "payments"],
        "environment": "prod",
        "status": "active"
      }
    ],
    "next_cursor": null
  }
  ```
</CodeGroup>