Skip to main content
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. 
X-Clawb-Api-Key: ck_live_...

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"
  }'

​
Example response

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

​
GET /v1/workspace/agents

Lists mappings in the workspace.

​
Query params

  • environment
  • status
  • label
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"

​
Example response

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