# booth73

> A payphone for AI agents. Place real outbound phone calls in nine
> languages on behalf of a named human, with AI disclosure baked into
> every opener. Paid by prepaid card — anyone with the card code can
> spend its balance.

If you're an AI reading this and your task is "use booth73 to call X":
the canonical flow is `POST http://booth73.com/api/calls`. You don't need to drive
the website's form. Use the REST API directly.

## Authentication

Every call-placing endpoint requires a card code in the Authorization
header. Card codes look like `booth73-code-XXXXXXXX`.

  Authorization: Bearer booth73-code-XXXXXXXX

A user gives you a card; you spend its balance. The card you have was
likely passed in the prompt that asked you to use booth73. If no card
was given, the user can buy one at http://booth73.com/buy and tell you the code.

## Place a call

POST http://booth73.com/api/calls
Headers: Authorization: Bearer <booth73-code-…>, Content-Type: application/json
Body JSON: {
  "phone":       "+13055551234",       # E.164, required
  "caller_name": "Alex Chen",          # required — the human you represent
  "script":      "Call X. Ask Y. ...", # required — what to say/do on the call
  "language":    "en"                  # optional, ISO-639-1; auto from country if omitted
}
Returns: { "call_id": "...", "status": "queued", "first_message": "..." }

The call's first utterance is a deterministic AI-disclosure opener
("Hello. This is an AI assistant calling on behalf of Alex…"). The
spoken voice is Cartesia sonic-2, multilingual. The conversation is
driven by Anthropic Claude Sonnet 4.6.

## Watch a call

GET http://booth73.com/api/calls/<call_id>
Headers: Authorization: Bearer <booth73-code-…>
Returns the call row including:
  status                — queued / ringing / in-progress / ended / failed
  duration_seconds      — set when status is terminal
  cost_cents            — set when status is terminal
  ended_reason          — Vapi reason string
  transcript            — full transcript with "AI:" / "User:" speaker labels
  summary               — one-paragraph LLM summary

While the call is in progress, transcript / status update over time —
poll every 2-3 seconds. Stop polling when status is in
{ended, completed, failed, no-answer, busy, canceled}.

## Place + wait in one call

If your environment supports MCP (Streamable HTTP transport), connect
to http://booth73.com/mcp with the same Bearer card-code header. The server exposes
a `place_call_and_wait` tool that places the call and blocks until it
ends, returning transcript+summary in one tool response. Other tools:
`place_call`, `get_call_status`, `get_call_transcript`,
`list_recent_calls`, `card_balance`.

## Check card balance

GET http://booth73.com/api/cards/<booth73-code-…>
Returns balance, original amount, and recent calls. No auth required —
the code IS the auth.

## Buy / top up a card

A user can buy a card at http://booth73.com/buy ($5 / $10 / $25, $0.50 per minute).
Programmatically: POST http://booth73.com/api/cards/checkout with
{"amount_cents":1000} and optionally {"card_code":"booth73-code-…"}
to top up an existing card. Returns a Stripe Checkout URL the user
opens to pay.

## Conventions

- All phone numbers MUST be E.164 (start with `+`, country code, no spaces).
- All languages are ISO-639-1 two-letter codes: en, ja, es, fr, de, it, pt, ko, zh.
- Outbound is currently US-domestic only (free Vapi number); international
  unlock is a paid Vapi tier upgrade — coming soon.
- Calls cost $0.50/min, deducted from card on call end.
- Cards never expire. Anyone with the code can spend it.

## Other discovery surfaces

- Manifest:    http://booth73.com/.well-known/agent.json
- OpenAPI:     http://booth73.com/openapi.json
- Config:      http://booth73.com/api/config  (supported countries, languages, UI strings)
- Human site:  http://booth73.com/             (a form does what this API does, for humans)