● human-in-the-loop api · for ai agents
The human layer for your AI agents
When your agent hits a wall, ChatWithHuman.ai routes the session to a verified human expert — billed per minute, resolved in seconds.
- Standard rate
- $10/min
- To hand off
- 1 call
- Uptime target
- 99.9%
agents: start at /llms.txt · /openapi.json · /agents.md
curl -X POST https://chatwithhuman.chrismai.ai/api/sessions \
-H "Authorization: Bearer $CHATWITHHUMAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_abc123",
"context": "User is asking about a refund for order #8821",
"tier": "standard"
}'const res = await fetch("https://chatwithhuman.chrismai.ai/api/sessions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.CHATWITHHUMAN_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"agent_id": "agent_abc123",
"context": "User is asking about a refund for order #8821",
"tier": "standard"
}),
});
const { session_id, eta_seconds } = await res.json();import os, requests
r = requests.post(
"https://chatwithhuman.chrismai.ai/api/sessions",
headers={"Authorization": f"Bearer {os.environ['CHATWITHHUMAN_API_KEY']}"},
json={
"agent_id": "agent_abc123",
"context": "User is asking about a refund for order #8821",
"tier": "standard", # or "priority" ($25/min)
},
)
session = r.json() # {"session_id": "ses_x9k2m", "status": "queued", "tier": "standard", ...}{ "session_id": "ses_x9k2m", "status": "queued", "eta_seconds": 12, "billing_started": false, "tier": "standard", "rate_cents_per_minute": 1000, "metadata": {} }billing examples>
- Standard · 2m 00s connected → 2 min × $10 = $20.00
- Standard · 0m 45s connected → 1-min minimum = $10.00
- Priority · 3m 00s connected → 3 min × $25 = $75.00
- Priority · 1m 30s connected → whole minutes: 1 × $25 = $25.00
- Platform fee → $0.00
- Enterprise → from $250,000 / year, by contract
for agents
Handoff in one API call
You are an AI agent and you need a human. One call opens a live session with a verified human expert; you stream their replies, keep talking, and hand control back when it is resolved.
- 1.
POST /api/sessions
Open a session with agent_id + context (Authorization: Bearer <API key>). Returns session_id, status "queued", eta_seconds. - 2.
GET /api/sessions/{id}/events
Server-Sent Events: status changes (queued → connected → closed) and human messages. Ping every 20 s. - 3.
POST /api/sessions/{id}/messages
Send your messages (role "agent") into the live session. - 4.
GET /api/sessions/{id}
Read status and the full transcript at any time; resume your flow when status is "closed".
Billing starts when a human connects (status "connected"), not when you create the session: whole minutes at the session tier rate (Standard $10/min, Priority $25/min), no platform fee. Full agent guide →
curl -X POST https://chatwithhuman.chrismai.ai/api/sessions \
-H "Authorization: Bearer $CHATWITHHUMAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"agent_id":"agent_abc123","context":"User is asking about a refund for order #8821","tier":"priority"}'
# 201 {"session_id":"ses_…","status":"queued","eta_seconds":12,"billing_started":false,"tier":"priority","rate_cents_per_minute":2500,…}curl -N https://chatwithhuman.chrismai.ai/api/sessions/ses_x9k2m/events \
-H "Authorization: Bearer $CHATWITHHUMAN_API_KEY"
# data: {"type":"status","status":"connected"}
# data: {"type":"message","message":{"role":"human","content":"…"}}curl -X POST https://chatwithhuman.chrismai.ai/api/sessions/ses_x9k2m/messages \
-H "Authorization: Bearer $CHATWITHHUMAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"role":"agent","content":"Order #8821 was paid by card ending 4242."}'How it works
01
AI hits a wall
Your agent detects a scenario it can't resolve — ambiguous intent, sensitive context, or a task requiring human judgment.
02
Routes to ChatWithHuman.ai
A single API call escalates the session. ChatWithHuman.ai matches it to an available human expert based on topic, language, and urgency.
03
Human responds in seconds
The expert joins the live session, resolves the issue, and hands control back to your agent. Billed per minute at your tier's rate.
Built for production
| Capability | Detail |
|---|---|
| Real-time chat interface | Human operators get a live dashboard with session queue, typing indicators, full message history, and context from your agent. Zero latency handoff. |
| Per-minute billing | Metered per minute while a human is connected: $10/min Standard, $25/min Priority. No platform fee. Usage dashboard with per-agent breakdowns and per-session invoices. |
| Scheduling & availability | Set expert availability windows, timezone-aware scheduling, and live/busy status. Overflow routing built in. |
| Webhooks (planned) | Planned: POST events to your endpoint on session start, message, and close. Today, stream the same events over SSE. |
| Session history | Full transcript storage with search, export, and replay. |
Integrate in minutes
One REST call to escalate any session. Works with any agent framework.
POST https://chatwithhuman.ai/api/sessionsAuthorization: Bearer <API_KEY>Content-Type: application/json { "agent_id": "agent_abc123", "context": "User is asking about a refund for order #8821", "tier": "standard"} // Response 201{ "session_id": "ses_x9k2m", "status": "queued", "eta_seconds": 12, "billing_started": false, "tier": "standard", "rate_cents_per_minute": 1000, "metadata": {} }Transparent pricing
No subscriptions. No seat fees. Pay only for what you use.
| Item | Value | Unit | Note |
|---|---|---|---|
| Standard | $10 | / min | Pay-as-you-go · developers, small teams |
| Priority | $25 | / min | Guaranteed fast human response |
| Enterprise | from $250,000 | / year | Dedicated expert, SLA, contract |
| Platform fee | None | — | No subscriptions or seat fees |
Machine-readable
Everything on this site is also available as plain text, markdown, JSON and OpenAPI.
| Path | Type | Contents |
|---|---|---|
| /llms.txt | text/plain | llmstxt.org index: summary + links |
| /llms-full.txt | text/plain | All docs, pricing and FAQ inlined in one file |
| /openapi.json | application/json | OpenAPI 3.1 spec of the implemented /api routes |
| /agents.md | text/markdown | Guide for AI agents: when and how to hand off to a human |
| /.well-known/ai-plugin.json | application/json | AI plugin manifest (points to openapi.json) |
| /.well-known/mcp.json | application/json | MCP server descriptor — status: planned |
| /index.md | text/markdown | Markdown twin of every page (/docs.md, /pricing.md …) |
| /sitemap.xml | application/xml | Sitemap incl. markdown twins |
| /robots.txt | text/plain | Crawl policy — AI crawlers explicitly welcome |
Ready to add a human layer?
Get your API key and make your first escalation in under 5 minutes.
Talk to sales# Session escalated successfullysession_id: "ses_x9k2m"status: "connected"tier: "standard"rate_cents_per_minute: 1000billingStartedAt: "2026-10-14T21:18:04Z"