# RingKit

> Pay-per-minute phone answering for any business: an AI receptionist that knows the business; when a caller needs a person it transfers them to the business's own team number or takes a message. No plan, no subscription: pay only for what you use. Set up entirely by API or MCP; the only human step is paying, and handing it to the owner is optional.

- MCP (Streamable HTTP, stateless): https://api.ringkit.com/mcp (discovery: https://api.ringkit.com/.well-known/mcp.json)
- REST base: https://api.ringkit.com/v1 (OpenAPI: https://api.ringkit.com/openapi.json)
- Full reference for agents: https://api.ringkit.com/llms-full.txt
- Auth: `Authorization: Bearer rk_...` (business API key, returned once by create_business). Keys are scope manage (acts as owner) or read (read-only). POSTs accept `Idempotency-Key`.
- OAuth 2.1 for MCP clients (Claude, ChatGPT, Zapier...): https://api.ringkit.com/.well-known/oauth-protected-resource/mcp (dynamic client registration, authorization code + PKCE S256; the business owner signs in and approves). Use https://api.ringkit.com/mcp/oauth for clients that only start OAuth on a 401.
- Every MCP result carries `next` (the most useful next tool); every error is `{"error":{"code","message","hint","docs"}}`: follow the hint.
- Pricing: AI $0.20/min of talk time, 6-second increments, first 10 seconds free; numbers $1.99/month (a business's first number can run on a 7-day trial). Prepaid wallet, $10 minimum top-up. New businesses get free trial credit for calls only (one per owner email); numbers and the Pro plan need paid credit.

## Lifecycle (MCP tool names; REST in /openapi.json)

1. Create: `ringkit_create_business` (no auth) -> keep the apiKey; `ringkit_whoami` checks it.
2. Teach it: `ringkit_start_knowledge_import` {url} (background; poll `ringkit_get_latest_knowledge_import`), `ringkit_import_knowledge` {url, apply}, the setup assistant (`ringkit_start_setup_chat`, `ringkit_send_setup_chat` {conversationId, text}, `ringkit_close_setup_chat`), or `ringkit_put_knowledge` / `ringkit_patch_knowledge`. Documents: `ringkit_upload_knowledge_document` {fileName, contentBase64} (.pdf, .docx, .txt, .md, .html, 10 MB each; Starter 5 documents / 50k tokens free, Pro 100 / 500k for $5/month via `ringkit_set_knowledge_tier`).
3. Voice: `ringkit_list_voices`, then `ringkit_update_business` {voice}.
4. Routing: `ringkit_get_routing`, `ringkit_put_routing` {transferTargets, handoff, ...} (every call is AI-answered; transfers go to the business's own team numbers). Optional, once there is a number: `ringkit_put_voice_stack` {stack: elevenlabs} answers the AI tier on the ElevenLabs Agents platform with the same brain (the server chooses the initial stack based on provider availability; ai_only/ai_first routing only; `ringkit_get_voice_stack` shows the status).
5. Try it in text: `ringkit_simulate_call` {callerText: ""} for the greeting, then {callId, callerText} per caller line. No number needed; billed like a call at the AI rate from the wallet (the free trial credit covers it).
6. Fund (the one human step; ask early): `ringkit_top_up` {amountCents >= 1000} returns a checkoutUrl for the human to open and pay; then `ringkit_get_wallet`. Auto-refill: `ringkit_get_auto_refill` / `ringkit_put_auto_refill`; history: `ringkit_list_ledger`.
7. Number (needs step 6: $2 of paid credit, else 402 funding_required; no sign-in needed): `ringkit_search_numbers` {areaCode}, then `ringkit_provision_number` {number}; `ringkit_list_numbers`, `ringkit_release_number`.
8. Test call: `ringkit_verify_destination` {number} rings the phone and reads a 6-digit code; the person who answers tells you the code (their consent to be called) for `ringkit_confirm_destination` {number, code}; then `ringkit_test_call` {to}.
9. Calls: `ringkit_list_calls`, `ringkit_get_call` {callId} (transcript), `ringkit_get_recording` {callId}.
10. Webhooks: `ringkit_create_webhook` {url, events} (call.completed, message.taken, balance.low), `ringkit_list_webhooks`.
11. Keys: `ringkit_create_api_key` {name, scope}, `ringkit_list_api_keys`, `ringkit_revoke_api_key` {keyId}.
12. Hand-over (optional): `ringkit_invite_owner` {email?} emails the human a sign-in link; `ringkit_get_business` shows ownerSignedInAt, `ringkit_list_business_users` who can sign in; `ringkit_get_onboarding` shows what is left and `ringkit_complete_onboarding` marks setup finished. The agent can keep running the line; the human can take over any time.