---
name: humanrail
description: The agent-to-human last mile. One API call delivers a message to a real human over production Telegram/SMS rails and streams their typed reply back to the agent. Every delivery and reply is Ed25519-signed so any downstream agent can verify a real human answered. Use when an autonomous agent needs a human decision, confirmation, or answer and must prove it got one.
---

# HumanRail

Agents can call APIs, but they cannot reach a person. HumanRail is the missing
last mile: an HTTP service that delivers an agent's message to a real human's
phone (Telegram first, SMS escalation), waits for the human's actual typed
reply, and returns it with a signed receipt. If no human replies within 120
seconds, an auto-responder answers instead and the receipt honestly says
`"responder_type": "bot_fallback"` — a cold agent always completes.

**Base URL:** `https://humanrail.calyirex.com` *(going live during the edit
window — endpoints and examples below are the binding contract)*

## Endpoints

| Method | Path | Purpose |
|---|---|---|
| POST | `/reach` | Deliver a message to a human. **Start here.** |
| GET | `/status/{id}` | Delivery state + signed delivery receipt. |
| GET | `/reply/{id}` | Long-poll (25s) for the human's reply + signed reply receipt. |
| GET | `/pubkey` | Ed25519 public key + canonicalization spec. |
| POST | `/verify` | Verify any receipt this service signed. |
| GET | `/health` | Liveness. |
| GET | `/skill.md` | This document. |

## POST /reach

```json
{ "message": "Customer asks for a refund outside policy. Approve?", "options": ["approve", "deny"], "urgency": "normal" }
```

Returns `{"id": "...", "status": "queued", "poll": "/reply/{id}"}`. No API key
for the demo pool; rate-limited per IP.

## GET /reply/{id}

Long-polls up to 25s. Terminal response:

```json
{ "id": "...", "status": "answered", "reply": "approve",
  "responder_type": "verified_human", "answered_at": "...",
  "receipt": { "payload": { ... }, "payload_sha256_hex": "...", "signature_base64": "..." } }
```

`responder_type` is `"verified_human"` or `"bot_fallback"` (after 120s of
human silence) — the signature covers the field, so nobody can dress a bot up
as a human.

## Verify a receipt

Canonicalization: recursively key-sorted JSON, no whitespace, UTF-8. SHA-256
the canonical bytes of `payload`, Ed25519-verify `signature_base64` against
`GET /pubkey`. Or just `POST /verify` with the receipt.

## Guarantees

- The agent-side flow is fully autonomous: POST, poll, verify — no human helps the agent.
- The human is inside the service, answering on a real phone over production rails.
- Read-only demo pool, hard rate limits, no PII accepted in demo messages.