Getting Started

Go from zero to your first agent check-in in under 5 minutes.

Prerequisites

• A Waitroom account at waitroom.io
• Node.js 18+ (for the TypeScript SDK) or Python 3.8+ (for REST examples)
• An AI agent or CLI tool you want to coordinate

1. Create Your Account

Sign up at waitroom.io. When you create an account, Waitroom automatically provisions:

• An organization scoping all your data
• A default room ready for check-ins
• Your user profile with owner role

2. Register an Agent

Agents authenticate with API keys. There are two ways to register:

Option A: Human-registered (from dashboard or API)

A human registers the agent and receives the API key directly:

$ curl -X POST https://api.waitroom.io/v1/agents/register \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "description": "My first agent"}'

{
  "data": {
    "agent": {
      "id": "a1b2c3d4",
      "name": "my-agent",
      "is_active": true
    },
    "api_key": "wr_abc123...",
    "key_prefix": "wr_abc123..."
  }
}

Option B: Self-registration (agent-initiated)

An agent registers itself without any human auth. It receives an API key and a claim_token that a human must use to claim it into their organization:

$ curl -X POST https://api.waitroom.io/v1/agents/self-register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "description": "My first agent"}'

{
  "data": {
    "agent": { "id": "a1b2c3d4", "name": "my-agent" },
    "api_key": "wr_abc123...",
    "claim_token": "wr_claim_x7y8z9...",
    "status": "pending_claim"
  }
}

The agent shares its claim_token with a human, who claims it from the dashboard (Agents → Claim agent) or via the API:

$ curl -X POST https://api.waitroom.io/v1/agents/claim \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"claim_token": "wr_claim_x7y8z9..."}'

3. Connect Your Agent

Choose how to connect. Three options, pick whichever fits your stack:

Option A: MCP Server (Claude Code, Cursor)

$ claude mcp add waitroom \
  --transport sse \
  --url https://mcp.waitroom.io/sse \
  -e WAITROOM_API_KEY=wr_your_key_here

Option B: TypeScript SDK

$ npm install @waitroom-io/sdk

// In your agent code
import { WaitroomClient } from '@waitroom-io/sdk'

const client = new WaitroomClient({
  apiKey: 'wr_your_key_here'
})

Option C: REST API (curl / any language)

Pass your API key as a Bearer token with every request:

Authorization: Bearer wr_your_key_here

4. Submit Your First Check-in

A check-in tells humans what your agent wants to do and waits for a decision. Here is a minimal example:

$ curl -X POST https://api.waitroom.io/v1/rooms/default/check-in \
  -H "Authorization: Bearer wr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "Send welcome email to new user",
    "risk_level": "low",
    "urgency": "normal",
    "context": { "user_email": "jane@example.com" }
  }'

The response includes a check-in ID with status pending (unless a policy auto-approves or forbids it). Your agent can poll GET /v1/check-ins/:id/status to wait for a human decision.

5. Approve from the Dashboard

Open the Waitroom dashboard. Your check-in appears in the room feed with the action, risk level, and context visible. You can:

• Approve — the agent proceeds as proposed
• Reject — the agent stops, with your reason
• Modify — approve with changes the agent can read and act on

Once you decide, the agent's polling call returns the decision immediately.

Next Steps