{"openapi":"3.1.0","info":{"title":"RingKit API","version":"0.0.1","description":"RingKit is a pay-per-minute AI phone receptionist for small businesses, set up entirely by REST or MCP: create a business (no auth, returns an API key once), teach it the business, pick a voice and routing, get a phone number, try it in text, fund the prepaid wallet, place a test call, then hand it to the human owner.\n\nLifecycle: 1. Create the business; 2. Teach it the business; 3. Pick a voice; 4. Decide who answers; 5. Try it in text; 6. Fund the wallet; 7. Get a phone number; 8. Place a test call; 9. Watch the calls; 10. Get told about calls; 11. Manage API keys; 12. Hand it to the owner.\n\nAgent guides: https://api.ringkit.com/llms.txt (short), https://api.ringkit.com/llms-full.txt (full walk-through with curl), MCP server card https://api.ringkit.com/.well-known/mcp.json, human docs https://ringkit.com/docs.html. Errors: https://ringkit.com/docs.html#errors.\n\nEvery POST accepts `Idempotency-Key` (24 h replay; replays carry `Idempotent-Replayed: true`). Errors are `{error: {code, message, hint?, docs, details?}}`; `hint` is the next step to take."},"servers":[{"url":"https://api.ringkit.com"}],"security":[{"apiKey":[]}],"tags":[{"name":"businesses"},{"name":"auth"},{"name":"onboarding"},{"name":"api-keys"},{"name":"knowledge"},{"name":"setup-chat"},{"name":"voices"},{"name":"routing"},{"name":"numbers"},{"name":"calls"},{"name":"destinations"},{"name":"agents"},{"name":"wallet"},{"name":"webhooks"},{"name":"feedback"}],"paths":{"/v1/businesses":{"post":{"operationId":"createBusiness","summary":"Create a business and its first API key (returned once); no auth needed, so this is how an agent starts.","description":"Create a business and its first API key (returned once); no auth needed, so this is how an agent starts.\n\nLifecycle step: Create the business.","tags":["businesses"],"security":[],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"timezone":{"type":"string","minLength":1},"vertical":{"type":"string","maxLength":60},"ownerEmail":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"ownerPhone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"website":{"type":"string","minLength":1,"maxLength":2000},"notify":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"sms"},"to":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"}},"required":["type","to"]},{"type":"object","properties":{"type":{"type":"string","const":"email"},"to":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["type","to"]},{"type":"object","properties":{"type":{"type":"string","const":"webhook"},"url":{"type":"string","format":"uri"},"secret":{"type":"string","minLength":16}},"required":["type","url"]}]}},"billing":{"type":"string","const":"test"},"billingKey":{"type":"string","maxLength":200}},"required":["name","timezone","ownerEmail"]},"example":{"name":"Harbor Wellness","timezone":"America/Los_Angeles","vertical":"wellness","website":"harborwellness.com","ownerEmail":"dana@harborwellness.com","ownerPhone":"+14155550142"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"business":{"$ref":"#/components/schemas/Business"},"apiKey":{"type":"string"}},"required":["business","apiKey"],"additionalProperties":false},"example":{"business":{"id":"biz_7k2m9q4x8w3n5p1r","name":"Harbor Wellness","timezone":"America/Los_Angeles","vertical":"wellness","website":"https://harborwellness.com","ownerEmail":"dana@harborwellness.com","ownerPhone":"+14155550142","notify":[],"status":"active","knowledgeTier":"starter","voice":"Ashley","createdVia":"api","voiceStack":"livekit","createdAt":"2026-10-27T16:02:11.000Z","updatedAt":"2026-10-27T16:02:11.000Z"},"apiKey":"rk_live_3f9a1c7e5b2d8f4a6c0e9b1d7f3a5c8e"}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`billing_test_unavailable`: Stripe test billing is not enabled on this server; sign up without billing=test. `billing_test_forbidden`: The billing test key is wrong; sign up without billing=test, or ask for the current key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: too many unauthenticated requests from this IP; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Create the business"}},"/v1/businesses/{id}":{"get":{"operationId":"getBusiness","summary":"Read the business: profile, voice, status, how it was created and whether a human owner has signed in.","description":"Read the business: profile, voice, status, how it was created and whether a human owner has signed in.\n\nLifecycle step: Hand it to the owner.","tags":["businesses"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Business"},"example":{"id":"biz_7k2m9q4x8w3n5p1r","name":"Harbor Wellness","timezone":"America/Los_Angeles","vertical":"wellness","website":"https://harborwellness.com","ownerEmail":"dana@harborwellness.com","ownerPhone":"+14155550142","notify":[{"type":"email","to":"dana@harborwellness.com"}],"status":"active","knowledgeTier":"starter","voice":"Ashley","createdVia":"api","voiceStack":"livekit","createdAt":"2026-10-27T16:02:11.000Z","updatedAt":"2026-10-27T16:02:11.000Z","ownerSignedInAt":"2026-10-27T19:12:44.000Z"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Hand it to the owner"},"patch":{"operationId":"updateBusiness","summary":"Patch the business (name, timezone, website, voice, notify targets, ...); owner identity, status and notify are owner-only.","description":"Patch the business (name, timezone, website, voice, notify targets, ...); owner identity, status and notify are owner-only.\n\nLifecycle step: Pick a voice.","tags":["businesses"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"timezone":{"type":"string","minLength":1},"vertical":{"type":"string","maxLength":60},"ownerEmail":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"ownerPhone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"website":{"type":"string","minLength":1,"maxLength":2000},"notify":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"sms"},"to":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"}},"required":["type","to"]},{"type":"object","properties":{"type":{"type":"string","const":"email"},"to":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["type","to"]},{"type":"object","properties":{"type":{"type":"string","const":"webhook"},"url":{"type":"string","format":"uri"},"secret":{"type":"string","minLength":16}},"required":["type","url"]}]}},"status":{"type":"string","enum":["active","paused","suspended"]},"voice":{"type":"string","enum":["Ashley","Olivia","Sarah","Elizabeth","Edward","Dennis","Mark","Theodore","el:hpp4J3VqNfWAUOO0d1Us","el:EXAVITQu4vr4xnSDxMaL","el:XrExE9yKIg1WjnnlVkGX","el:cgSgspJ2msm6clMCkdW9","el:Xb7hH8MSUJpSbSDYk0k2","el:pFZP5JQG7iQjIQuC4Bku","el:cjVigY5qzO86Huf0OWal","el:iP95p4xoKVk53GoZ742B","el:nPczCjzI2devNBz1zQrb","el:bIHbv24MWmeRgasZH58o","el:JBFqnCBsd6RMkjVDRZzb","el:onwK4e9ZLuTAKqWW03F9"]}}},"example":{"voice":"Sarah","notify":[{"type":"email","to":"dana@harborwellness.com"}]}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Business"},"example":{"id":"biz_7k2m9q4x8w3n5p1r","name":"Harbor Wellness","timezone":"America/Los_Angeles","vertical":"wellness","website":"https://harborwellness.com","ownerEmail":"dana@harborwellness.com","ownerPhone":"+14155550142","notify":[{"type":"email","to":"dana@harborwellness.com"}],"status":"active","knowledgeTier":"starter","voice":"Sarah","createdVia":"api","voiceStack":"livekit","createdAt":"2026-10-27T16:02:11.000Z","updatedAt":"2026-10-27T16:15:00.000Z"}}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`insufficient_scope`: read-scope keys may only GET; `forbidden`: the credential belongs to another business. `owner_required`: Use an owner's session or a manage API key (keys act as owner), or ask an owner to do this.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Pick a voice"}},"/v1/me":{"get":{"operationId":"whoami","summary":"The business behind the presented API key or session, with how the caller authenticated and the key's scope.","description":"The business behind the presented API key or session, with how the caller authenticated and the key's scope.\n\nLifecycle step: Create the business.","tags":["businesses"],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"name":{"type":"string","minLength":1,"maxLength":120},"timezone":{"type":"string","minLength":1},"vertical":{"type":"string","maxLength":60},"website":{"type":"string","format":"uri"},"ownerEmail":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"ownerPhone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"notify":{"default":[],"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"sms"},"to":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"}},"required":["type","to"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"email"},"to":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["type","to"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"webhook"},"url":{"type":"string","format":"uri"},"secret":{"type":"string","minLength":16}},"required":["type","url"],"additionalProperties":false}]}},"status":{"default":"active","type":"string","enum":["active","paused","suspended"]},"knowledgeTier":{"default":"starter","type":"string","enum":["starter","pro"]},"voice":{"default":"Ashley","type":"string","enum":["Ashley","Olivia","Sarah","Elizabeth","Edward","Dennis","Mark","Theodore","el:hpp4J3VqNfWAUOO0d1Us","el:EXAVITQu4vr4xnSDxMaL","el:XrExE9yKIg1WjnnlVkGX","el:cgSgspJ2msm6clMCkdW9","el:Xb7hH8MSUJpSbSDYk0k2","el:pFZP5JQG7iQjIQuC4Bku","el:cjVigY5qzO86Huf0OWal","el:iP95p4xoKVk53GoZ742B","el:nPczCjzI2devNBz1zQrb","el:bIHbv24MWmeRgasZH58o","el:JBFqnCBsd6RMkjVDRZzb","el:onwK4e9ZLuTAKqWW03F9"]},"voiceSource":{"default":"default","type":"string","enum":["default","auto","owner"]},"voiceReason":{"type":"string","maxLength":200},"onboardingCompletedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"createdVia":{"default":"api","type":"string","enum":["dashboard","api","mcp"]},"ownerSignedInAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"voiceStack":{"default":"livekit","type":"string","enum":["livekit","elevenlabs"]},"voiceStackState":{"type":"object","properties":{"applied":{"type":"string","enum":["livekit","elevenlabs"]},"brainMode":{"type":"string","enum":["elevenlabs","gateway"]},"elevenlabsAgentId":{"type":"string"},"elevenlabsKnowledgeDocId":{"type":"string"},"elevenlabsKnowledgeHash":{"type":"string"},"elevenlabsToolIds":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"elevenlabsAgentPromptHash":{"type":"string"},"elevenlabsPhoneNumberId":{"type":"string"},"carrierConnectionId":{"type":"string"},"steps":{"default":[],"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["tools","knowledge","agent","number_import","carrier_route","number_release"]},"status":{"type":"string","enum":["ok","skipped","failed"]},"detail":{"type":"string","maxLength":500}},"required":["name","status"],"additionalProperties":false}},"lastError":{"type":"string","maxLength":1000},"forcedByOperator":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["applied","steps","updatedAt"],"additionalProperties":false},"billingMode":{"default":"live","type":"string","enum":["live","test"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"authKind":{"type":"string","enum":["api_key","session","draft"]},"role":{"type":"string","enum":["owner","member"]},"keyScope":{"type":"string","enum":["manage","read"]}},"required":["id","name","timezone","ownerEmail","notify","status","knowledgeTier","voice","voiceSource","createdVia","voiceStack","billingMode","createdAt","updatedAt","authKind"],"additionalProperties":false},"example":{"id":"biz_7k2m9q4x8w3n5p1r","name":"Harbor Wellness","timezone":"America/Los_Angeles","vertical":"wellness","website":"https://harborwellness.com","ownerEmail":"dana@harborwellness.com","ownerPhone":"+14155550142","notify":[{"type":"email","to":"dana@harborwellness.com"}],"status":"active","knowledgeTier":"starter","voice":"Ashley","createdVia":"api","voiceStack":"livekit","createdAt":"2026-10-27T16:02:11.000Z","updatedAt":"2026-10-27T16:02:11.000Z","authKind":"api_key","role":"owner","keyScope":"manage"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Create the business"}},"/v1/auth/magic-link":{"post":{"operationId":"requestMagicLink","summary":"Email a sign-in link to a business user or enrolled agent; always answers ok.","description":"Email a sign-in link to a business user or enrolled agent; always answers ok.","tags":["auth"],"security":[],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"kind":{"default":"business","type":"string","enum":["business","agent"]},"next":{"type":"string","pattern":"^\\/(?!\\/)[A-Za-z0-9\\-._~/?=&]{0,200}$"}},"required":["email"]}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: too many unauthenticated requests from this IP; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"dashboard"}},"/v1/auth/magic-link/consume":{"post":{"operationId":"consumeMagicLink","summary":"Exchange a single-use sign-in token for a session cookie.","description":"Exchange a single-use sign-in token for a session cookie.","tags":["auth"],"security":[],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":16,"maxLength":200}},"required":["token"]}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["business","agent"]},"businessId":{"anyOf":[{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},{"type":"null"}]},"agentId":{"type":"string","pattern":"^agt_[0-9a-z]{8,32}$"}},"required":["kind","businessId"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: too many unauthenticated requests from this IP; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"dashboard"}},"/v1/auth/password":{"post":{"operationId":"passwordLogin","summary":"Sign in an operator-designated account (shared reviewer logins) with email and password; sets the same session cookie as a sign-in link.","description":"Sign in an operator-designated account (shared reviewer logins) with email and password; sets the same session cookie as a sign-in link.","tags":["auth"],"security":[],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"password":{"type":"string","minLength":1,"maxLength":200}},"required":["email","password"]}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"email":{"type":"string"}},"required":["ok","email"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`invalid_credentials`: Check the email and password; password sign-in exists only for operator-designated accounts, everyone else signs in with an emailed link (POST /v1/auth/magic-link).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: too many unauthenticated requests from this IP; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"dashboard"}},"/v1/auth/logout":{"post":{"operationId":"logout","summary":"End the browser session and clear its cookies.","description":"End the browser session and clear its cookies.","tags":["auth"],"security":[{"businessSession":[]},{"agentSession":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"dashboard"}},"/v1/auth/session":{"get":{"operationId":"authSession","summary":"Who the session cookie belongs to, which businesses they can open, and whether the email is verified (false until the emailed link is opened).","description":"Who the session cookie belongs to, which businesses they can open, and whether the email is verified (false until the emailed link is opened).","tags":["auth"],"security":[{"businessSession":[]},{"agentSession":[]}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["business","agent"]},"email":{"type":"string"},"businesses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"name":{"type":"string"},"role":{"type":"string","enum":["owner","member"]}},"required":["id","name","role"],"additionalProperties":false}},"agentId":{"type":"string","pattern":"^agt_[0-9a-z]{8,32}$"},"emailVerified":{"default":true,"type":"boolean"}},"required":["kind","email","businesses","emailVerified"],"additionalProperties":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"dashboard"}},"/v1/drafts":{"post":{"operationId":"createDraft","summary":"Start an anonymous signup draft from a website or name: a business with no owner yet, imported in the background; sets the rk_draft cookie.","description":"Start an anonymous signup draft from a website or name: a business with no owner yet, imported in the background; sets the rk_draft cookie.","tags":["onboarding"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"website":{"type":"string","minLength":1,"maxLength":2000},"name":{"type":"string","minLength":1,"maxLength":120},"timezone":{"type":"string","minLength":1},"billing":{"type":"string","const":"test"},"billingKey":{"type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"business":{"$ref":"#/components/schemas/Business"},"import":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeImport"},{"type":"null"}]},"importsUsed":{"type":"integer","minimum":0,"maximum":9007199254740991},"importsMax":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"preview":{"type":"object","properties":{"greeting":{"type":"string"},"qa":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"q":{"type":"string"},"a":{"type":"string"},"source":{"type":"string","enum":["hours","service","faq","policy","address","booking","phone","summary","generic"]}},"required":["q","a","source"],"additionalProperties":false}},"voice":{"type":"string","enum":["Ashley","Olivia","Sarah","Elizabeth","Edward","Dennis","Mark","Theodore","el:hpp4J3VqNfWAUOO0d1Us","el:EXAVITQu4vr4xnSDxMaL","el:XrExE9yKIg1WjnnlVkGX","el:cgSgspJ2msm6clMCkdW9","el:Xb7hH8MSUJpSbSDYk0k2","el:pFZP5JQG7iQjIQuC4Bku","el:cjVigY5qzO86Huf0OWal","el:iP95p4xoKVk53GoZ742B","el:nPczCjzI2devNBz1zQrb","el:bIHbv24MWmeRgasZH58o","el:JBFqnCBsd6RMkjVDRZzb","el:onwK4e9ZLuTAKqWW03F9"]},"grounded":{"type":"boolean"}},"required":["greeting","qa","voice","grounded"],"additionalProperties":false},"profile":{"$ref":"#/components/schemas/KnowledgeProfile"},"previewSeenAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["business","import","importsUsed","importsMax","preview","expiresAt"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`insufficient_scope`: read-scope keys may only GET; `forbidden`: the credential belongs to another business. `billing_test_unavailable`: Stripe test billing is not enabled on this server; sign up without billing=test. `billing_test_forbidden`: The billing test key is wrong; sign up without billing=test, or ask for the current key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"dashboard"}},"/v1/drafts/me":{"get":{"operationId":"getDraft","summary":"The draft behind the rk_draft cookie: business, newest website import and the receptionist preview (greeting, three Q&A, voice).","description":"The draft behind the rk_draft cookie: business, newest website import and the receptionist preview (greeting, three Q&A, voice).","tags":["onboarding"],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"business":{"$ref":"#/components/schemas/Business"},"import":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeImport"},{"type":"null"}]},"importsUsed":{"type":"integer","minimum":0,"maximum":9007199254740991},"importsMax":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"preview":{"type":"object","properties":{"greeting":{"type":"string"},"qa":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"q":{"type":"string"},"a":{"type":"string"},"source":{"type":"string","enum":["hours","service","faq","policy","address","booking","phone","summary","generic"]}},"required":["q","a","source"],"additionalProperties":false}},"voice":{"type":"string","enum":["Ashley","Olivia","Sarah","Elizabeth","Edward","Dennis","Mark","Theodore","el:hpp4J3VqNfWAUOO0d1Us","el:EXAVITQu4vr4xnSDxMaL","el:XrExE9yKIg1WjnnlVkGX","el:cgSgspJ2msm6clMCkdW9","el:Xb7hH8MSUJpSbSDYk0k2","el:pFZP5JQG7iQjIQuC4Bku","el:cjVigY5qzO86Huf0OWal","el:iP95p4xoKVk53GoZ742B","el:nPczCjzI2devNBz1zQrb","el:bIHbv24MWmeRgasZH58o","el:JBFqnCBsd6RMkjVDRZzb","el:onwK4e9ZLuTAKqWW03F9"]},"grounded":{"type":"boolean"}},"required":["greeting","qa","voice","grounded"],"additionalProperties":false},"profile":{"$ref":"#/components/schemas/KnowledgeProfile"},"previewSeenAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["business","import","importsUsed","importsMax","preview","expiresAt"],"additionalProperties":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"dashboard"}},"/v1/drafts/me/preview-seen":{"post":{"operationId":"markDraftPreviewSeen","summary":"Funnel: the visitor saw their receptionist preview.","description":"Funnel: the visitor saw their receptionist preview.","tags":["onboarding"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"business":{"$ref":"#/components/schemas/Business"},"import":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeImport"},{"type":"null"}]},"importsUsed":{"type":"integer","minimum":0,"maximum":9007199254740991},"importsMax":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"preview":{"type":"object","properties":{"greeting":{"type":"string"},"qa":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"q":{"type":"string"},"a":{"type":"string"},"source":{"type":"string","enum":["hours","service","faq","policy","address","booking","phone","summary","generic"]}},"required":["q","a","source"],"additionalProperties":false}},"voice":{"type":"string","enum":["Ashley","Olivia","Sarah","Elizabeth","Edward","Dennis","Mark","Theodore","el:hpp4J3VqNfWAUOO0d1Us","el:EXAVITQu4vr4xnSDxMaL","el:XrExE9yKIg1WjnnlVkGX","el:cgSgspJ2msm6clMCkdW9","el:Xb7hH8MSUJpSbSDYk0k2","el:pFZP5JQG7iQjIQuC4Bku","el:cjVigY5qzO86Huf0OWal","el:iP95p4xoKVk53GoZ742B","el:nPczCjzI2devNBz1zQrb","el:bIHbv24MWmeRgasZH58o","el:JBFqnCBsd6RMkjVDRZzb","el:onwK4e9ZLuTAKqWW03F9"]},"grounded":{"type":"boolean"}},"required":["greeting","qa","voice","grounded"],"additionalProperties":false},"profile":{"$ref":"#/components/schemas/KnowledgeProfile"},"previewSeenAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["business","import","importsUsed","importsMax","preview","expiresAt"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`insufficient_scope`: read-scope keys may only GET; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"dashboard"}},"/v1/drafts/me/claim":{"post":{"operationId":"claimDraft","summary":"Bind the draft to an email: the business gets its owner and trial credit, the browser an unverified session limited to it, and the sign-in link is emailed.","description":"Bind the draft to an email: the business gets its owner and trial credit, the browser an unverified session limited to it, and the sign-in link is emailed.","tags":["onboarding"],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["email"]}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"business":{"$ref":"#/components/schemas/Business"},"email":{"type":"string"},"emailVerified":{"type":"boolean","const":false},"magicLinkSent":{"type":"boolean"}},"required":["business","email","emailVerified","magicLinkSent"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`insufficient_scope`: read-scope keys may only GET; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"dashboard"}},"/v1/businesses/{id}/owners/invite":{"post":{"operationId":"inviteOwner","summary":"Optional hand-over: email the human owner a sign-in link bound to this business (default: ownerEmail).","description":"Optional hand-over: email the human owner a sign-in link bound to this business (default: ownerEmail).\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nLifecycle step: Hand it to the owner.","tags":["businesses"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}}},"example":{}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"email":{"type":"string"},"magicLinkSent":{"type":"boolean","const":true}},"required":["ok","email","magicLinkSent"],"additionalProperties":false},"example":{"ok":true,"email":"dana@harborwellness.com","magicLinkSent":true}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key. `conflict`: Read the resource again (GET) and retry against its current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Hand it to the owner"}},"/v1/businesses/{id}/users":{"get":{"operationId":"listBusinessUsers","summary":"List the people who can sign in to the business dashboard, with their roles and last sign-in.","description":"List the people who can sign in to the business dashboard, with their roles and last sign-in.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nLifecycle step: Hand it to the owner.","tags":["businesses"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^bu_[0-9a-z]{8,32}$"},"email":{"type":"string"},"name":{"type":"string"},"role":{"type":"string","enum":["owner","member"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"lastSignInAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","email","role","createdAt"],"additionalProperties":false}}},"required":["users"],"additionalProperties":false},"example":{"users":[{"id":"bu_t4v8x2z6b0d3f7h1","email":"dana@harborwellness.com","role":"owner","createdAt":"2026-10-27T16:02:11.000Z","lastSignInAt":"2026-10-27T19:12:44.000Z"}]}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Hand it to the owner"}},"/v1/businesses/{id}/api-keys":{"get":{"operationId":"listApiKeys","summary":"List the business's API keys (prefix, scope, last use, revoked or not); never the plaintext.","description":"List the business's API keys (prefix, scope, last use, revoked or not); never the plaintext.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nLifecycle step: Manage API keys.","tags":["api-keys"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyInfo"}}},"required":["keys"],"additionalProperties":false},"example":{"keys":[{"id":"key_m3p7r1t5v9x2z6b4","name":"Setup agent","scope":"manage","prefix":"rk_live_3f9a","createdAt":"2026-10-27T16:02:11.000Z","lastUsedAt":"2026-10-27T18:45:00.000Z"},{"id":"key_q8s2u6w0y4a7c1e5","name":"Reporting","scope":"read","prefix":"rk_live_9b2e","createdAt":"2026-10-27T18:50:00.000Z"}]}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Manage API keys"},"post":{"operationId":"createApiKey","summary":"Create an API key with scope manage (acts as owner) or read (GET only); the plaintext is returned once.","description":"Create an API key with scope manage (acts as owner) or read (GET only); the plaintext is returned once.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nLifecycle step: Manage API keys.","tags":["api-keys"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"default":"API key","type":"string","minLength":1,"maxLength":60},"scope":{"default":"manage","type":"string","enum":["manage","read"]}}},"example":{"name":"Reporting","scope":"read"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/ApiKeyInfo"},"apiKey":{"type":"string"}},"required":["key","apiKey"],"additionalProperties":false},"example":{"key":{"id":"key_q8s2u6w0y4a7c1e5","name":"Reporting","scope":"read","prefix":"rk_live_9b2e","createdAt":"2026-10-27T18:50:00.000Z"},"apiKey":"rk_live_9b2e7d4f1a8c5e3b6d0f2a9c4e7b1d5f"}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Manage API keys"}},"/v1/businesses/{id}/api-keys/{keyId}":{"delete":{"operationId":"revokeApiKey","summary":"Revoke an API key; it stops authenticating at once.","description":"Revoke an API key; it stops authenticating at once.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nLifecycle step: Manage API keys.","tags":["api-keys"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"keyId","in":"path","required":true,"description":"An API key id (`key_…`) from listApiKeys.","schema":{"type":"string","pattern":"^key_[0-9a-z]{8,32}$"},"example":"key_q8s2u6w0y4a7c1e5"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false},"example":{"ok":true}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Manage API keys"}},"/v1/businesses/{id}/knowledge":{"get":{"operationId":"getKnowledge","summary":"Read the knowledge profile the receptionist answers from (services, hours, FAQs, policies).","description":"Read the knowledge profile the receptionist answers from (services, hours, FAQs, policies).","tags":["knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeProfile"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent"},"put":{"operationId":"putKnowledge","summary":"Replace the whole knowledge profile.","description":"Replace the whole knowledge profile.\n\nLifecycle step: Teach it the business.","tags":["knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"businessName":{"type":"string","minLength":1,"maxLength":120},"tagline":{"type":"string","maxLength":200},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"serviceArea":{"type":"string","maxLength":1000},"credentials":{"type":"array","items":{"type":"string","maxLength":300}},"estimateUrl":{"type":"string","pattern":"^https?:\\/\\/"},"evidence":{"type":"object","propertyNames":{"type":"string","enum":["businessName","tagline","summary","hours","address","phone","email","serviceArea","credentials","estimateUrl","bookingUrl","services","staff","faqs","policies"]},"additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["found","inferred","owner"]},"sourceUrl":{"type":"string","pattern":"^https?:\\/\\/"},"quote":{"type":"string","maxLength":1200}},"required":["status"]}},"summary":{"default":"","type":"string","maxLength":1500},"hours":{"type":"object","properties":{"regular":{"default":{},"type":"object","propertyNames":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]},"additionalProperties":{"type":"array","items":{"type":"object","properties":{"open":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"close":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["open","close"]}}},"exceptions":{"default":[],"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"windows":{"type":"array","items":{"type":"object","properties":{"open":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"close":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["open","close"]}},"note":{"type":"string"}},"required":["date","windows"]}},"note":{"type":"string","maxLength":300}}},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postalCode":{"type":"string"},"country":{"default":"US","type":"string"},"directions":{"type":"string","maxLength":500},"parking":{"type":"string","maxLength":300}},"required":["line1","city","region","postalCode"]},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"bookingUrl":{"type":"string","format":"uri"},"services":{"default":[],"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","maxLength":500},"priceUsd":{"type":"number","minimum":0},"priceNote":{"type":"string","maxLength":120},"durationMin":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"bookingUrl":{"type":"string","format":"uri"}},"required":["name"]}},"staff":{"default":[],"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string"},"bio":{"type":"string","maxLength":500},"schedule":{"type":"string","maxLength":200}},"required":["name"]}},"faqs":{"default":[],"type":"array","items":{"type":"object","properties":{"q":{"type":"string"},"a":{"type":"string","maxLength":1000}},"required":["q","a"]}},"policies":{"default":[],"type":"array","items":{"type":"object","properties":{"topic":{"type":"string"},"text":{"type":"string","maxLength":1000}},"required":["topic","text"]}},"doNotSay":{"default":[],"type":"array","items":{"type":"string","maxLength":300}},"escalationContacts":{"default":[],"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"when":{"type":"string","maxLength":300}},"required":["label","when"]}},"documents":{"default":[],"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"text":{"type":"string","maxLength":50000},"sourceUrl":{"type":"string","format":"uri"},"source":{"type":"object","properties":{"kind":{"type":"string","const":"upload"},"documentId":{"type":"string","pattern":"^doc_[0-9a-z]{8,32}$"},"fileName":{"type":"string"},"label":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["kind","documentId","fileName","label","uploadedAt"]}},"required":["id","title","text"]}},"greeting":{"type":"string","maxLength":300},"voiceNotes":{"type":"string","maxLength":1000},"vibe":{"type":"object","properties":{"tones":{"minItems":1,"maxItems":2,"type":"array","items":{"type":"string","enum":["warm","professional","upbeat","calm","luxury","clinical","friendly","authoritative"]}},"formality":{"type":"string","enum":["casual","neutral","formal"]},"energy":{"type":"string","enum":["low","medium","high"]},"audience":{"type":"string","maxLength":60},"evidence":{"type":"string","maxLength":120}},"required":["tones","formality","energy","audience","evidence"]}}},"example":{"summary":"Harbor Wellness is a massage and bodywork studio in the Mission, San Francisco, with four licensed therapists.","hours":{"regular":{"mon":[],"tue":[{"open":"09:00","close":"19:00"}],"wed":[{"open":"09:00","close":"19:00"}],"thu":[{"open":"09:00","close":"19:00"}],"fri":[{"open":"09:00","close":"19:00"}],"sat":[{"open":"10:00","close":"16:00"}],"sun":[]},"note":"Last appointment starts one hour before close."},"phone":"+14155550100","bookingUrl":"https://harborwellness.com/book","services":[{"name":"Swedish massage","description":"Relaxing full-body massage.","priceUsd":95,"durationMin":60},{"name":"Deep tissue massage","description":"Focused work on chronic tension.","priceUsd":125,"durationMin":75}],"faqs":[{"q":"Do you take insurance?","a":"We don't bill insurance directly, but we give you a receipt you can submit for reimbursement."},{"q":"Is there parking?","a":"Street parking on Valencia, and a public garage on 21st Street two blocks away."}],"policies":[{"topic":"Cancellations","text":"Cancel at least 24 hours ahead; late cancellations and no-shows are charged 50% of the service."}]}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeProfile"},"example":{"summary":"Harbor Wellness is a massage and bodywork studio in the Mission, San Francisco, with four licensed therapists.","hours":{"regular":{"mon":[],"tue":[{"open":"09:00","close":"19:00"}],"wed":[{"open":"09:00","close":"19:00"}],"thu":[{"open":"09:00","close":"19:00"}],"fri":[{"open":"09:00","close":"19:00"}],"sat":[{"open":"10:00","close":"16:00"}],"sun":[]},"exceptions":[],"note":"Last appointment starts one hour before close."},"phone":"+14155550100","bookingUrl":"https://harborwellness.com/book","services":[{"name":"Swedish massage","description":"Relaxing full-body massage.","priceUsd":95,"durationMin":60},{"name":"Deep tissue massage","description":"Focused work on chronic tension.","priceUsd":125,"durationMin":75}],"staff":[],"faqs":[{"q":"Do you take insurance?","a":"We don't bill insurance directly, but we give you a receipt you can submit for reimbursement."},{"q":"Is there parking?","a":"Street parking on Valencia, and a public garage on 21st Street two blocks away."}],"policies":[{"topic":"Cancellations","text":"Cancel at least 24 hours ahead; late cancellations and no-shows are charged 50% of the service."}],"doNotSay":[],"escalationContacts":[],"documents":[]}}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`insufficient_scope`: read-scope keys may only GET; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Teach it the business"},"patch":{"operationId":"patchKnowledge","summary":"Change parts of the knowledge profile; omitted fields are kept.","description":"Change parts of the knowledge profile; omitted fields are kept.\n\nLifecycle step: Teach it the business.","tags":["knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"businessName":{"type":"string","minLength":1,"maxLength":120},"tagline":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"email":{"anyOf":[{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"serviceArea":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"credentials":{"anyOf":[{"type":"array","items":{"type":"string","maxLength":300}},{"type":"null"}]},"estimateUrl":{"anyOf":[{"type":"string","pattern":"^https?:\\/\\/"},{"type":"null"}]},"evidence":{"type":"object","propertyNames":{"type":"string","enum":["businessName","tagline","summary","hours","address","phone","email","serviceArea","credentials","estimateUrl","bookingUrl","services","staff","faqs","policies"]},"additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["found","inferred","owner"]},"sourceUrl":{"type":"string","pattern":"^https?:\\/\\/"},"quote":{"type":"string","maxLength":1200}},"required":["status"]}},"summary":{"type":"string","maxLength":1500},"hours":{"anyOf":[{"type":"object","properties":{"regular":{"default":{},"type":"object","propertyNames":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]},"additionalProperties":{"type":"array","items":{"type":"object","properties":{"open":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"close":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["open","close"]}}},"exceptions":{"default":[],"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"windows":{"type":"array","items":{"type":"object","properties":{"open":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"close":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["open","close"]}},"note":{"type":"string"}},"required":["date","windows"]}},"note":{"type":"string","maxLength":300}}},{"type":"null"}]},"address":{"anyOf":[{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postalCode":{"type":"string"},"country":{"default":"US","type":"string"},"directions":{"type":"string","maxLength":500},"parking":{"type":"string","maxLength":300}},"required":["line1","city","region","postalCode"]},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},{"type":"null"}]},"bookingUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"services":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","maxLength":500},"priceUsd":{"type":"number","minimum":0},"priceNote":{"type":"string","maxLength":120},"durationMin":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"bookingUrl":{"type":"string","format":"uri"}},"required":["name"]}},"staff":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string"},"bio":{"type":"string","maxLength":500},"schedule":{"type":"string","maxLength":200}},"required":["name"]}},"faqs":{"type":"array","items":{"type":"object","properties":{"q":{"type":"string"},"a":{"type":"string","maxLength":1000}},"required":["q","a"]}},"policies":{"type":"array","items":{"type":"object","properties":{"topic":{"type":"string"},"text":{"type":"string","maxLength":1000}},"required":["topic","text"]}},"doNotSay":{"type":"array","items":{"type":"string","maxLength":300}},"escalationContacts":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"when":{"type":"string","maxLength":300}},"required":["label","when"]}},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"text":{"type":"string","maxLength":50000},"sourceUrl":{"type":"string","format":"uri"},"source":{"type":"object","properties":{"kind":{"type":"string","const":"upload"},"documentId":{"type":"string","pattern":"^doc_[0-9a-z]{8,32}$"},"fileName":{"type":"string"},"label":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["kind","documentId","fileName","label","uploadedAt"]}},"required":["id","title","text"]}},"greeting":{"type":"string","maxLength":300},"voiceNotes":{"type":"string","maxLength":1000},"vibe":{"type":"object","properties":{"tones":{"minItems":1,"maxItems":2,"type":"array","items":{"type":"string","enum":["warm","professional","upbeat","calm","luxury","clinical","friendly","authoritative"]}},"formality":{"type":"string","enum":["casual","neutral","formal"]},"energy":{"type":"string","enum":["low","medium","high"]},"audience":{"type":"string","maxLength":60},"evidence":{"type":"string","maxLength":120}},"required":["tones","formality","energy","audience","evidence"]}}},"example":{"greeting":"Thanks for calling Harbor Wellness, this is the front desk. How can I help?"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeProfile"},"example":{"summary":"Harbor Wellness is a massage and bodywork studio in the Mission, San Francisco, with four licensed therapists.","hours":{"regular":{"mon":[],"tue":[{"open":"09:00","close":"19:00"}],"wed":[{"open":"09:00","close":"19:00"}],"thu":[{"open":"09:00","close":"19:00"}],"fri":[{"open":"09:00","close":"19:00"}],"sat":[{"open":"10:00","close":"16:00"}],"sun":[]},"exceptions":[],"note":"Last appointment starts one hour before close."},"phone":"+14155550100","bookingUrl":"https://harborwellness.com/book","services":[{"name":"Swedish massage","description":"Relaxing full-body massage.","priceUsd":95,"durationMin":60},{"name":"Deep tissue massage","description":"Focused work on chronic tension.","priceUsd":125,"durationMin":75}],"staff":[],"faqs":[{"q":"Do you take insurance?","a":"We don't bill insurance directly, but we give you a receipt you can submit for reimbursement."},{"q":"Is there parking?","a":"Street parking on Valencia, and a public garage on 21st Street two blocks away."}],"policies":[{"topic":"Cancellations","text":"Cancel at least 24 hours ahead; late cancellations and no-shows are charged 50% of the service."}],"doNotSay":[],"escalationContacts":[],"documents":[],"greeting":"Thanks for calling Harbor Wellness, this is the front desk. How can I help?"}}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`insufficient_scope`: read-scope keys may only GET; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Teach it the business"}},"/v1/businesses/{id}/knowledge/import":{"post":{"operationId":"importKnowledge","summary":"Draft a knowledge profile from a website now (synchronous), optionally applying it.","description":"Draft a knowledge profile from a website now (synchronous), optionally applying it.\n\nLifecycle step: Teach it the business.","tags":["knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"apply":{"default":false,"type":"boolean"}},"required":["url"]},"example":{"url":"https://harborwellness.com","apply":false}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"draft":{"$ref":"#/components/schemas/KnowledgeProfile"},"applied":{"type":"boolean"},"estimatedTokens":{"type":"number"}},"required":["draft","applied","estimatedTokens"],"additionalProperties":false},"example":{"draft":{"summary":"Harbor Wellness is a massage and bodywork studio in the Mission, San Francisco, with four licensed therapists.","hours":{"regular":{"mon":[],"tue":[{"open":"09:00","close":"19:00"}],"wed":[{"open":"09:00","close":"19:00"}],"thu":[{"open":"09:00","close":"19:00"}],"fri":[{"open":"09:00","close":"19:00"}],"sat":[{"open":"10:00","close":"16:00"}],"sun":[]},"exceptions":[],"note":"Last appointment starts one hour before close."},"phone":"+14155550100","bookingUrl":"https://harborwellness.com/book","services":[{"name":"Swedish massage","description":"Relaxing full-body massage.","priceUsd":95,"durationMin":60},{"name":"Deep tissue massage","description":"Focused work on chronic tension.","priceUsd":125,"durationMin":75}],"staff":[],"faqs":[{"q":"Do you take insurance?","a":"We don't bill insurance directly, but we give you a receipt you can submit for reimbursement."},{"q":"Is there parking?","a":"Street parking on Valencia, and a public garage on 21st Street two blocks away."}],"policies":[{"topic":"Cancellations","text":"Cancel at least 24 hours ahead; late cancellations and no-shows are charged 50% of the service."}],"doNotSay":[],"escalationContacts":[],"documents":[]},"applied":false,"estimatedTokens":1840}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`insufficient_scope`: read-scope keys may only GET; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"`import_failed`: The website couldn't be read; check the URL, or set the knowledge profile directly with PUT /v1/businesses/:id/knowledge.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"`llm_unavailable`: The AI model isn't configured on this server; fill the knowledge profile directly with PUT /v1/businesses/:id/knowledge, or retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Teach it the business"}},"/v1/businesses/{id}/knowledge/imports":{"post":{"operationId":"startKnowledgeImport","summary":"Queue a background website import that fills only the profile fields not set yet.","description":"Queue a background website import that fills only the profile fields not set yet.\n\nLifecycle step: Teach it the business.","tags":["knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2000}},"required":["url"]},"example":{"url":"harborwellness.com"}}}},"responses":{"202":{"description":"Accepted: the work is queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeImport"},"example":{"id":"kimp_d2f6h0j4l8n1p5r9","url":"https://harborwellness.com","status":"queued","createdAt":"2026-10-27T16:03:00.000Z"}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`insufficient_scope`: read-scope keys may only GET; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"`llm_unavailable`: The AI model isn't configured on this server; fill the knowledge profile directly with PUT /v1/businesses/:id/knowledge, or retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Teach it the business"}},"/v1/businesses/{id}/knowledge/imports/latest":{"get":{"operationId":"getLatestKnowledgeImport","summary":"The newest website import and its status (poll after startKnowledgeImport).","description":"The newest website import and its status (poll after startKnowledgeImport).\n\nLifecycle step: Teach it the business.","tags":["knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"import":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeImport"},{"type":"null"}]}},"required":["import"],"additionalProperties":false},"example":{"import":{"id":"kimp_d2f6h0j4l8n1p5r9","url":"https://harborwellness.com","status":"done","createdAt":"2026-10-27T16:03:00.000Z","estimatedTokens":1840,"found":{"hours":true,"services":6,"faqs":4,"policies":2,"summary":true},"finishedAt":"2026-10-27T16:03:41.000Z"}}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Teach it the business"}},"/v1/businesses/{id}/onboarding":{"get":{"operationId":"getOnboarding","summary":"First-run setup progress: the next step, whether knowledge is ready, whether there is a number, the latest import.","description":"First-run setup progress: the next step, whether knowledge is ready, whether there is a number, the latest import.","tags":["onboarding"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingStatus"},"example":{"step":"number","hasNumber":false,"knowledgeReady":true,"latestImport":{"id":"kimp_d2f6h0j4l8n1p5r9","url":"https://harborwellness.com","status":"running","createdAt":"2026-10-27T16:03:00.000Z"}}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent"}},"/v1/businesses/{id}/onboarding/complete":{"post":{"operationId":"completeOnboarding","summary":"Mark first-run setup finished so the dashboard stops nudging the owner.","description":"Mark first-run setup finished so the dashboard stops nudging the owner.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nLifecycle step: Hand it to the owner.","tags":["onboarding"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingStatus"},"example":{"step":"done","completedAt":"2026-10-27T19:20:05.000Z","hasNumber":true,"knowledgeReady":true,"latestImport":{"id":"kimp_d2f6h0j4l8n1p5r9","url":"https://harborwellness.com","status":"done","createdAt":"2026-10-27T16:03:00.000Z","estimatedTokens":1840,"found":{"hours":true,"services":6,"faqs":4,"policies":2,"summary":true},"finishedAt":"2026-10-27T16:03:41.000Z"}}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Hand it to the owner"}},"/v1/businesses/{id}/setup-chat":{"get":{"operationId":"getSetupChat","summary":"The open setup-agent conversation, or null.","description":"The open setup-agent conversation, or null.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["setup-chat"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"conversation":{"anyOf":[{"$ref":"#/components/schemas/SetupConversation"},{"type":"null"}]}},"required":["conversation"],"additionalProperties":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true},"post":{"operationId":"startSetupChat","summary":"Start a setup-agent chat that fills knowledge and routing through conversation.","description":"Start a setup-agent chat that fills knowledge and routing through conversation.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nLifecycle step: Teach it the business.","tags":["setup-chat"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"context":{"default":"onboarding","type":"string","enum":["onboarding","knowledge"]},"restart":{"default":false,"type":"boolean"}}},"example":{"context":"onboarding"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetupConversation"},"example":{"id":"schat_h6j0l4n8p2r5t9v3","status":"open","context":"onboarding","messages":[{"role":"assistant","text":"Hi! I'll set up your receptionist. What does Harbor Wellness do, and what hours are you open?","at":"2026-10-27T16:05:00.000Z","writes":[]}],"budget":{"usedCents":1,"limitCents":200},"createdAt":"2026-10-27T16:05:00.000Z","updatedAt":"2026-10-27T16:05:00.000Z"}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`setup_budget_exceeded`: Today's setup-chat budget is spent; continue tomorrow, or edit knowledge and routing directly (PUT .../knowledge, PUT .../routing). `rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"`llm_unavailable`: The AI model isn't configured on this server; fill the knowledge profile directly with PUT /v1/businesses/:id/knowledge, or retry later. `llm_failed`: The AI model call failed; retry in a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Teach it the business"}},"/v1/businesses/{id}/setup-chat/{conversationId}/messages":{"post":{"operationId":"sendSetupChat","summary":"Send a message to the setup agent and get its reply.","description":"Send a message to the setup agent and get its reply.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nLifecycle step: Teach it the business.","tags":["setup-chat"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"conversationId","in":"path","required":true,"description":"A setup-chat conversation id (`schat_…`) from startSetupChat or getSetupChat.","schema":{"type":"string","pattern":"^schat_[0-9a-z]{8,32}$"},"example":"schat_h6j0l4n8p2r5t9v3"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":8000}},"required":["text"]},"example":{"text":"Massage studio. Tuesday to Friday 9 to 7, Saturday 10 to 4, closed Sunday and Monday."}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetupConversation"},"example":{"id":"schat_h6j0l4n8p2r5t9v3","status":"open","context":"onboarding","messages":[{"role":"assistant","text":"Hi! I'll set up your receptionist. What does Harbor Wellness do, and what hours are you open?","at":"2026-10-27T16:05:00.000Z","writes":[]},{"role":"user","text":"Massage studio. Tuesday to Friday 9 to 7, Saturday 10 to 4, closed Sunday and Monday.","at":"2026-10-27T16:05:30.000Z","writes":[]},{"role":"assistant","text":"Saved your hours. Which services do you offer, and what do they cost?","at":"2026-10-27T16:05:34.000Z","writes":[{"tool":"set_hours","summary":"Hours: Tue–Fri 9:00–19:00, Sat 10:00–16:00; closed Sun, Mon"}]}],"budget":{"usedCents":3,"limitCents":200},"createdAt":"2026-10-27T16:05:00.000Z","updatedAt":"2026-10-27T16:05:34.000Z"}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key. `conversation_busy`: The previous setup-chat message is still being answered; wait for it, then send again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`setup_budget_exceeded`: Today's setup-chat budget is spent; continue tomorrow, or edit knowledge and routing directly (PUT .../knowledge, PUT .../routing). `rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"`llm_unavailable`: The AI model isn't configured on this server; fill the knowledge profile directly with PUT /v1/businesses/:id/knowledge, or retry later. `llm_failed`: The AI model call failed; retry in a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Teach it the business"}},"/v1/businesses/{id}/setup-chat/{conversationId}/close":{"post":{"operationId":"closeSetupChat","summary":"Close a setup-agent conversation.","description":"Close a setup-agent conversation.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["setup-chat"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"conversationId","in":"path","required":true,"description":"A setup-chat conversation id (`schat_…`) from startSetupChat or getSetupChat.","schema":{"type":"string","pattern":"^schat_[0-9a-z]{8,32}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetupConversation"}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true}},"/v1/businesses/{id}/knowledge/documents":{"get":{"operationId":"listKnowledgeDocuments","summary":"List uploaded knowledge documents and the tier's usage limits.","description":"List uploaded knowledge documents and the tier's usage limits.","tags":["knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeDocument"}},"usage":{"$ref":"#/components/schemas/KnowledgeUsage"}},"required":["documents","usage"],"additionalProperties":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent"},"post":{"operationId":"uploadKnowledgeDocument","summary":"Upload a PDF, DOCX, TXT, Markdown or HTML file (base64 JSON); its text joins the knowledge for every call.","description":"Upload a PDF, DOCX, TXT, Markdown or HTML file (base64 JSON); its text joins the knowledge for every call.\n\nLifecycle step: Teach it the business.","tags":["knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","minLength":1,"maxLength":200},"contentType":{"type":"string","maxLength":120},"contentBase64":{"type":"string","minLength":1,"maxLength":13981020}},"required":["fileName","contentBase64"]},"example":{"fileName":"price-list.txt","contentType":"text/plain","contentBase64":"U3dlZGlzaCBtYXNzYWdlIDYwIG1pbjogJDk1CkRlZXAgdGlzc3VlIDc1IG1pbjogJDEyNQo="}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"document":{"$ref":"#/components/schemas/KnowledgeDocument"},"usage":{"$ref":"#/components/schemas/KnowledgeUsage"}},"required":["document","usage"],"additionalProperties":false},"example":{"document":{"id":"doc_n4r8v2z6c0f3j7m1","fileName":"price-list.txt","fileType":"txt","contentType":"text/plain","byteSize":52,"sha256":"9c1f4e7a2b5d8c0e3f6a9b2c5d8e1f4a7b0c3d6e9f2a5b8c1d4e7f0a3b6c9d2e","sectionCount":1,"estimatedTokens":15,"originalStored":true,"uploadedAt":"2026-10-27T16:10:00.000Z"},"usage":{"tier":"starter","limits":{"maxDocuments":5,"maxTokens":50000,"maxFileBytes":10485760,"monthlyCents":0},"used":{"documents":1,"tokens":412},"originalsStored":true}}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`insufficient_scope`: read-scope keys may only GET; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key. `document_limit_reached`: Delete documents you no longer need, or move to the pro tier (POST /v1/businesses/:id/knowledge/tier). `token_limit_reached`: Delete documents you no longer need, or move to the pro tier (POST /v1/businesses/:id/knowledge/tier).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"`file_too_large`: Upload a file under the limit in details (10 MB), or split it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"`unsupported_file_type`: Upload PDF, DOCX, TXT, Markdown or HTML.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"`extraction_failed`: No text could be read from the file; upload a text-based version, not a scan. `empty_document`: The file has no readable text; upload one that does.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Teach it the business"}},"/v1/businesses/{id}/knowledge/documents/{documentId}":{"get":{"operationId":"getKnowledgeDocument","summary":"Read one uploaded document with its extracted sections.","description":"Read one uploaded document with its extracted sections.","tags":["knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"documentId","in":"path","required":true,"description":"An uploaded knowledge document's id (`doc_…`) from listKnowledgeDocuments.","schema":{"type":"string","pattern":"^doc_[0-9a-z]{8,32}$"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeDocument"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent"},"delete":{"operationId":"deleteKnowledgeDocument","summary":"Delete an uploaded document and its extracted text.","description":"Delete an uploaded document and its extracted text.","tags":["knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"documentId","in":"path","required":true,"description":"An uploaded knowledge document's id (`doc_…`) from listKnowledgeDocuments.","schema":{"type":"string","pattern":"^doc_[0-9a-z]{8,32}$"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"usage":{"$ref":"#/components/schemas/KnowledgeUsage"}},"required":["ok","usage"],"additionalProperties":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`insufficient_scope`: read-scope keys may only GET; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent"}},"/v1/businesses/{id}/knowledge/documents/{documentId}/file":{"get":{"operationId":"getKnowledgeDocumentFile","summary":"A short-lived download URL for an uploaded document's original file.","description":"A short-lived download URL for an uploaded document's original file.","tags":["knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"documentId","in":"path","required":true,"description":"An uploaded knowledge document's id (`doc_…`) from listKnowledgeDocuments.","schema":{"type":"string","pattern":"^doc_[0-9a-z]{8,32}$"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["url","expiresAt"],"additionalProperties":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"`gone`: The resource expired or was removed; request a new one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent"}},"/v1/businesses/{id}/knowledge/usage":{"get":{"operationId":"getKnowledgeUsage","summary":"Knowledge usage against the current tier's limits.","description":"Knowledge usage against the current tier's limits.","tags":["knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeUsage"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent"}},"/v1/businesses/{id}/knowledge/tier":{"post":{"operationId":"setKnowledgeTier","summary":"Switch the knowledge tier (starter or pro, billed monthly from the wallet).","description":"Switch the knowledge tier (starter or pro, billed monthly from the wallet).\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["knowledge"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"string","enum":["starter","pro"]}},"required":["tier"]}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeUsage"}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"`insufficient_balance`: Top up the wallet: POST /v1/businesses/:id/wallet/top-ups returns a checkoutUrl for the human to pay; trial credit covers calls only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key. `over_tier_limits`: Delete documents until usage fits the starter limits, then change the tier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true}},"/v1/voices":{"get":{"operationId":"listVoices","summary":"List the receptionist voices; set one with updateBusiness `voice`.","description":"List the receptionist voices; set one with updateBusiness `voice`.\n\nLifecycle step: Pick a voice.","tags":["voices"],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"voices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["Ashley","Olivia","Sarah","Elizabeth","Edward","Dennis","Mark","Theodore","el:hpp4J3VqNfWAUOO0d1Us","el:EXAVITQu4vr4xnSDxMaL","el:XrExE9yKIg1WjnnlVkGX","el:cgSgspJ2msm6clMCkdW9","el:Xb7hH8MSUJpSbSDYk0k2","el:pFZP5JQG7iQjIQuC4Bku","el:cjVigY5qzO86Huf0OWal","el:iP95p4xoKVk53GoZ742B","el:nPczCjzI2devNBz1zQrb","el:bIHbv24MWmeRgasZH58o","el:JBFqnCBsd6RMkjVDRZzb","el:onwK4e9ZLuTAKqWW03F9"]},"label":{"type":"string"},"gender":{"type":"string","enum":["female","male"]},"accent":{"type":"string"},"description":{"type":"string"},"provider":{"type":"string","enum":["inworld","elevenlabs"]}},"required":["id","label","gender","accent","description"],"additionalProperties":false}},"default":{"type":"string","enum":["Ashley","Olivia","Sarah","Elizabeth","Edward","Dennis","Mark","Theodore","el:hpp4J3VqNfWAUOO0d1Us","el:EXAVITQu4vr4xnSDxMaL","el:XrExE9yKIg1WjnnlVkGX","el:cgSgspJ2msm6clMCkdW9","el:Xb7hH8MSUJpSbSDYk0k2","el:pFZP5JQG7iQjIQuC4Bku","el:cjVigY5qzO86Huf0OWal","el:iP95p4xoKVk53GoZ742B","el:nPczCjzI2devNBz1zQrb","el:bIHbv24MWmeRgasZH58o","el:JBFqnCBsd6RMkjVDRZzb","el:onwK4e9ZLuTAKqWW03F9"]}},"required":["voices","default"],"additionalProperties":false},"example":{"voices":[{"id":"Ashley","label":"Ashley","gender":"female","accent":"American","description":"Warm, natural (the default)"},{"id":"Sarah","label":"Sarah","gender":"female","accent":"American","description":"Calm, professional"},{"id":"Mark","label":"Mark","gender":"male","accent":"American","description":"Steady, reassuring"}],"default":"Ashley"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Pick a voice"}},"/v1/businesses/{id}/routing":{"get":{"operationId":"getRouting","summary":"Read the routing policy: when the AI answers, transfers or takes a message, and the spend cap.","description":"Read the routing policy: when the AI answers, transfers or takes a message, and the spend cap.\n\nLifecycle step: Decide who answers.","tags":["routing"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoutingPolicy"},"example":{"mode":"ai_first","schedule":[],"afterHoursMode":"ai_only","humanRingTimeoutS":8,"maxHumanOffers":3,"escalateOn":["caller_requests_human","always_human_intent","repeated_failure"],"alwaysHumanIntents":["complaint"],"neverHumanIntents":["hours","location"],"transferTargets":[{"id":"front-desk","label":"Front desk","number":"+14155550142","whenToUse":"Billing questions and complaints"}],"dailySpendCapUsd":25,"recordCalls":true,"discloseAi":true,"requiredAgentSkills":[],"vettedAgentsOnly":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Decide who answers"},"put":{"operationId":"putRouting","summary":"Change the routing policy (transfer targets on the business's own team, handoff preferences, recording, spend cap). Every call is answered by the AI: RingKit's live-rep pool is not offered, so ai_first/human_first modes act as ai_only.","description":"Change the routing policy (transfer targets on the business's own team, handoff preferences, recording, spend cap). Every call is answered by the AI: RingKit's live-rep pool is not offered, so ai_first/human_first modes act as ai_only.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nLifecycle step: Decide who answers.","tags":["routing"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"handoff":{"type":"object","properties":{"unsure":{"type":"string","enum":["message","transfer"]},"requested":{"type":"string","enum":["message","transfer"]},"urgent":{"type":"string","enum":["message","transfer"]},"targetId":{"type":"string"}},"required":["unsure","requested","urgent"]},"mode":{"type":"string","enum":["ai_only","ai_first","human_first"]},"schedule":{"type":"array","items":{"type":"object","properties":{"days":{"minItems":1,"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"from":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"to":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"mode":{"type":"string","enum":["ai_only","ai_first","human_first"]}},"required":["days","from","to","mode"]}},"afterHoursMode":{"type":"string","enum":["ai_only","ai_first","human_first"]},"humanRingTimeoutS":{"type":"integer","minimum":3,"maximum":30},"maxHumanOffers":{"type":"integer","minimum":1,"maximum":5},"escalateOn":{"type":"array","items":{"type":"string","enum":["caller_requests_human","always_human_intent","low_confidence","repeated_failure"]}},"alwaysHumanIntents":{"type":"array","items":{"type":"string"}},"neverHumanIntents":{"type":"array","items":{"type":"string"}},"transferTargets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"whenToUse":{"type":"string","maxLength":300}},"required":["id","label","number"]}},"dailySpendCapUsd":{"type":"number","exclusiveMinimum":0},"recordCalls":{"type":"boolean"},"discloseAi":{"type":"boolean"},"requiredAgentSkills":{"type":"array","items":{"type":"string"}},"vettedAgentsOnly":{"type":"boolean"}}},"example":{"mode":"ai_first","alwaysHumanIntents":["complaint"],"neverHumanIntents":["hours","location"],"transferTargets":[{"id":"front-desk","label":"Front desk","number":"+14155550142","whenToUse":"Billing questions and complaints"}],"dailySpendCapUsd":25}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoutingPolicy"},"example":{"mode":"ai_first","schedule":[],"afterHoursMode":"ai_only","humanRingTimeoutS":8,"maxHumanOffers":3,"escalateOn":["caller_requests_human","always_human_intent","repeated_failure"],"alwaysHumanIntents":["complaint"],"neverHumanIntents":["hours","location"],"transferTargets":[{"id":"front-desk","label":"Front desk","number":"+14155550142","whenToUse":"Billing questions and complaints"}],"dailySpendCapUsd":25,"recordCalls":true,"discloseAi":true,"requiredAgentSkills":[],"vettedAgentsOnly":false}}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Decide who answers"}},"/v1/businesses/{id}/voice-stack":{"get":{"operationId":"getVoiceStack","summary":"Read which voice stack answers the AI tier (livekit, the default, or elevenlabs: the ElevenLabs Agents platform running the same receptionist brain), what is applied at the carrier now, and the steps of the last switch.","description":"Read which voice stack answers the AI tier (livekit, the default, or elevenlabs: the ElevenLabs Agents platform running the same receptionist brain), what is applied at the carrier now, and the steps of the last switch.","tags":["routing"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"desired":{"type":"string","enum":["livekit","elevenlabs"]},"applied":{"type":"string","enum":["livekit","elevenlabs"]},"brainMode":{"type":"string","enum":["elevenlabs","gateway"]},"status":{"type":"string","enum":["ok","pending","error"]},"elevenlabsAgentId":{"type":"string"},"number":{"type":"string"},"steps":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["tools","knowledge","agent","number_import","carrier_route","number_release"]},"status":{"type":"string","enum":["ok","skipped","failed"]},"detail":{"type":"string","maxLength":500}},"required":["name","status"],"additionalProperties":false}},"lastError":{"type":"string"},"forcedByOperator":{"type":"boolean"},"disabled":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["desired","applied","brainMode","status","steps"],"additionalProperties":false},"example":{"desired":"livekit","applied":"livekit","brainMode":"elevenlabs","status":"ok","number":"+14155550187","steps":[],"disabled":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent"},"put":{"operationId":"putVoiceStack","summary":"Switch the voice stack (livekit | elevenlabs). Applies it synchronously (ElevenLabs agent sync, number import or removal, carrier routing), so it can take a few seconds; needs an active number and ai_only/ai_first routing. A failed step answers 502 voice_stack_failed with the status in details; send the same PUT again to resume.","description":"Switch the voice stack (livekit | elevenlabs). Applies it synchronously (ElevenLabs agent sync, number import or removal, carrier routing), so it can take a few seconds; needs an active number and ai_only/ai_first routing. A failed step answers 502 voice_stack_failed with the status in details; send the same PUT again to resume.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["routing"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stack":{"type":"string","enum":["livekit","elevenlabs"]},"brainMode":{"type":"string","enum":["elevenlabs","gateway"]}},"required":["stack"]},"example":{"stack":"elevenlabs"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"desired":{"type":"string","enum":["livekit","elevenlabs"]},"applied":{"type":"string","enum":["livekit","elevenlabs"]},"brainMode":{"type":"string","enum":["elevenlabs","gateway"]},"status":{"type":"string","enum":["ok","pending","error"]},"elevenlabsAgentId":{"type":"string"},"number":{"type":"string"},"steps":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["tools","knowledge","agent","number_import","carrier_route","number_release"]},"status":{"type":"string","enum":["ok","skipped","failed"]},"detail":{"type":"string","maxLength":500}},"required":["name","status"],"additionalProperties":false}},"lastError":{"type":"string"},"forcedByOperator":{"type":"boolean"},"disabled":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["desired","applied","brainMode","status","steps"],"additionalProperties":false},"example":{"desired":"elevenlabs","applied":"elevenlabs","brainMode":"elevenlabs","status":"ok","elevenlabsAgentId":"agent_7801k8q2w6e9r3t7y1","number":"+14155550187","steps":[{"name":"tools","status":"ok","detail":"take_message unchanged tool_4401k8q2, request_human unchanged tool_4402k8q2"},{"name":"knowledge","status":"ok","detail":"created KBDoc8q2w6e9r3t7 (5120 chars), index created"},{"name":"agent","status":"ok","detail":"created agent_7801k8q2w6e9r3t7y1"},{"name":"number_import","status":"ok","detail":"imported phnum_5201k8q2w6e9r3t7"},{"name":"carrier_route","status":"ok","detail":"ringkit-elevenlabs"}],"disabled":false,"updatedAt":"2026-10-27T16:20:04.000Z"}}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`voice_stack_disabled`: The operator switched the ElevenLabs stack off; the business stays on livekit. Try again later. `number_required`: Provision a number first: GET /v1/numbers/search, then POST /v1/businesses/:id/numbers. `voice_stack_unsupported_mode`: Set routing mode, afterHoursMode and every schedule rule to ai_first or ai_only (PUT /v1/businesses/:id/routing), then switch the voice stack again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"502":{"description":"`voice_stack_failed`: A step of the switch failed; details carries the voice-stack status with the failed step. Send the same PUT again to resume.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"`elevenlabs_unavailable`: ElevenLabs is not configured on this server; stay on the livekit stack. `telephony_unavailable`: No telephony host is connected right now; retry in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true}},"/v1/numbers/search":{"get":{"operationId":"searchNumbers","summary":"Search phone numbers available to order, by area code or region ($1.99 a month each).","description":"Search phone numbers available to order, by area code or region ($1.99 a month each).\n\nLifecycle step: Get a phone number.","tags":["numbers"],"parameters":[{"name":"country","in":"query","required":false,"schema":{"default":"US","type":"string"}},{"name":"areaCode","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{3}$"},"example":"415"},{"name":"contains","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":5,"type":"integer","minimum":1,"maximum":20},"example":2}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"numbers":{"type":"array","items":{"$ref":"#/components/schemas/AvailableNumber"}}},"required":["numbers"],"additionalProperties":false},"example":{"numbers":[{"number":"+14155550187","region":"San Francisco, CA","monthlyCents":199,"provider":"telnyx"},{"number":"+14155550163","region":"San Francisco, CA","monthlyCents":199,"provider":"telnyx"}]}}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Get a phone number"}},"/v1/businesses/{id}/numbers":{"post":{"operationId":"provisionNumber","summary":"Order a phone number for the business (needs $2 of paid wallet credit, or, for the first number of a business whose owner signed in, trial credit with a 7-day trial).","description":"Order a phone number for the business (needs $2 of paid wallet credit, or, for the first number of a business whose owner signed in, trial credit with a 7-day trial).\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nStop and ask the human when: it answers 402 funding_required: the wallet needs $2 of paid credit (trial credit only covers a first number once the owner signed in; getOnboarding.canOrderOnTrial says so). Call topUp, give the human the checkoutUrl to pay, then retry. A number with trialUntil is released then unless the wallet is topped up first: tell the human.\n\nLifecycle step: Get a phone number.","tags":["numbers"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"}},"required":["number"]},"example":{"number":"+14155550187"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionedNumber"},"example":{"id":"num_g5k9m3q7s1u4w8y2","businessId":"biz_7k2m9q4x8w3n5p1r","number":"+14155550187","provider":"telnyx","providerNumberId":"2563718291736154","monthlyCents":199,"status":"active","createdAt":"2026-10-27T16:20:40.000Z"}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"`funding_required`: Top up the wallet: POST /v1/businesses/:id/wallet/top-ups returns a checkoutUrl for the human to pay; trial credit covers calls only.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key. `number_limit_reached`: Release a number you no longer need (DELETE /v1/businesses/:id/numbers/:numberId) before ordering another.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"`telephony_unavailable`: No telephony host is connected right now; retry in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Get a phone number"},"get":{"operationId":"listNumbers","summary":"List the business's phone numbers.","description":"List the business's phone numbers.\n\nLifecycle step: Get a phone number.","tags":["numbers"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"numbers":{"type":"array","items":{"$ref":"#/components/schemas/ProvisionedNumber"}}},"required":["numbers"],"additionalProperties":false},"example":{"numbers":[{"id":"num_g5k9m3q7s1u4w8y2","businessId":"biz_7k2m9q4x8w3n5p1r","number":"+14155550187","provider":"telnyx","providerNumberId":"2563718291736154","monthlyCents":199,"status":"active","createdAt":"2026-10-27T16:20:40.000Z"}]}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Get a phone number"}},"/v1/businesses/{id}/numbers/{numberId}":{"delete":{"operationId":"releaseNumber","summary":"Release a phone number; its rental stops.","description":"Release a phone number; its rental stops.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["numbers"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"numberId","in":"path","required":true,"description":"A provisioned number's id (`num_…`) from listNumbers.","schema":{"type":"string","pattern":"^num_[0-9a-z]{8,32}$"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true}},"/v1/businesses/{id}/numbers/{numberId}/forwarding":{"get":{"operationId":"getForwarding","summary":"Forwarding to a RingKit number: the owner's business phone, when forwarding was last proven, and the last forwarding check.","description":"Forwarding to a RingKit number: the owner's business phone, when forwarding was last proven, and the last forwarding check.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nLifecycle step: Get a phone number.","tags":["numbers"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"numberId","in":"path","required":true,"description":"A provisioned number's id (`num_…`) from listNumbers.","schema":{"type":"string","pattern":"^num_[0-9a-z]{8,32}$"},"example":"num_g5k9m3q7s1u4w8y2"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"businessPhone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"verifiedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"lastCheck":{"type":"object","properties":{"checkId":{"type":"string","minLength":1,"maxLength":64},"at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"status":{"type":"string","enum":["pending","done"]},"outcome":{"type":"string","enum":["forwarded","not_forwarded","no_answer","error"]},"detail":{"type":"string","maxLength":500},"finishedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["checkId","at","status"],"additionalProperties":false}},"additionalProperties":false},"example":{"businessPhone":"+14155550142","verifiedAt":"2026-10-27T16:36:31.000Z","lastCheck":{"checkId":"fwd_Zt3qWm8KpX2rVn6YbJ4cHA","at":"2026-10-27T16:36:02.000Z","status":"done","outcome":"forwarded","detail":"Your phone forwarded the test call to your RingKit number.","finishedAt":"2026-10-27T16:36:31.000Z"}}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Get a phone number"},"put":{"operationId":"putForwarding","summary":"Save the owner's existing business phone that forwards (on no-answer) to this RingKit number.","description":"Save the owner's existing business phone that forwards (on no-answer) to this RingKit number.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nStop and ask the human when: the owner turns forwarding on with their carrier's dial code (e.g. **61*<number>#), which only they can do on their phone: give them the code, then run startForwardingCheck.\n\nLifecycle step: Get a phone number.","tags":["numbers"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"numberId","in":"path","required":true,"description":"A provisioned number's id (`num_…`) from listNumbers.","schema":{"type":"string","pattern":"^num_[0-9a-z]{8,32}$"},"example":"num_g5k9m3q7s1u4w8y2"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessPhone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"}},"required":["businessPhone"]},"example":{"businessPhone":"+14155550142"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"businessPhone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"verifiedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"lastCheck":{"type":"object","properties":{"checkId":{"type":"string","minLength":1,"maxLength":64},"at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"status":{"type":"string","enum":["pending","done"]},"outcome":{"type":"string","enum":["forwarded","not_forwarded","no_answer","error"]},"detail":{"type":"string","maxLength":500},"finishedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["checkId","at","status"],"additionalProperties":false}},"additionalProperties":false},"example":{"businessPhone":"+14155550142"}}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Get a phone number"}},"/v1/businesses/{id}/numbers/{numberId}/forwarding/check":{"post":{"operationId":"startForwardingCheck","summary":"Ring the business phone from the RingKit number and wait up to 60 s for it to forward back; poll getForwarding for the outcome.","description":"Ring the business phone from the RingKit number and wait up to 60 s for it to forward back; poll getForwarding for the outcome.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nStop and ask the human when: the business phone really rings: tell the human NOT to answer it (an answered call means not_forwarded), then poll getForwarding every few seconds for lastCheck.outcome.\n\nLifecycle step: Get a phone number.","tags":["numbers"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"numberId","in":"path","required":true,"description":"A provisioned number's id (`num_…`) from listNumbers.","schema":{"type":"string","pattern":"^num_[0-9a-z]{8,32}$"},"example":"num_g5k9m3q7s1u4w8y2"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"202":{"description":"Accepted: the work is queued.","content":{"application/json":{"schema":{"type":"object","properties":{"checkId":{"type":"string"},"status":{"type":"string","const":"started"}},"required":["checkId","status"],"additionalProperties":false},"example":{"checkId":"fwd_Zt3qWm8KpX2rVn6YbJ4cHA","status":"started"}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key. `forwarding_phone_required`: Save the business phone that forwards first: PUT /v1/businesses/:id/numbers/:numberId/forwarding {businessPhone}. `forward_check_limit`: A business may run 3 forwarding checks in 24 hours; try again after the window rolls over. `test_call_limit`: The 24-hour outbound call limit for this business or number was reached; try again after it rolls over. `conflict`: Read the resource again (GET) and retry against its current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"`telephony_unavailable`: No telephony host is connected right now; retry in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Get a phone number"}},"/v1/businesses/{id}/calls":{"get":{"operationId":"listCalls","summary":"List calls, newest first (paginated), with outcome, intent, summary and cost.","description":"List calls, newest first (paginated), with outcome, intent, summary and cost.\n\nLifecycle step: Watch the calls.","tags":["calls"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":25,"type":"integer","minimum":1,"maximum":100},"example":25}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Call"}},"nextCursor":{"type":["string","null"]}},"required":["items","nextCursor"],"additionalProperties":false},"example":{"items":[{"id":"call_x4n8q2w6e9r3t7y1","businessId":"biz_7k2m9q4x8w3n5p1r","direction":"inbound","from":"+14155550199","to":"+14155550187","status":"completed","provider":"livekit-telnyx","providerCallId":"SCL_8hd73ks0","startedAt":"2026-10-27T18:41:02.000Z","answeredAt":"2026-10-27T18:41:03.000Z","endedAt":"2026-10-27T18:42:31.000Z","endReason":"caller_hangup","segments":[{"handler":"ai","startedAt":"2026-10-27T18:41:03.000Z","endedAt":"2026-10-27T18:42:31.000Z"}],"summary":{"intent":"book_appointment","outcome":"answered","callerName":"Sam","summary":"Sam asked about a deep tissue massage on Saturday; given the price and the booking link by SMS.","followUpNeeded":false,"sentiment":"positive"},"billedCents":21}],"nextCursor":null}}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Watch the calls"}},"/v1/businesses/{id}/calls/{callId}/recording":{"get":{"operationId":"getRecording","summary":"A short-lived URL for a call's recording.","description":"A short-lived URL for a call's recording.\n\nLifecycle step: Watch the calls.","tags":["calls"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"callId","in":"path","required":true,"description":"A call id (`call_…`) from listCalls, simulateCall or a call offer.","schema":{"type":"string","pattern":"^call_[0-9a-z]{8,32}$"},"example":"call_x4n8q2w6e9r3t7y1"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["url","expiresAt"],"additionalProperties":false},"example":{"url":"https://storage.ringkit.com/recordings/call_x4n8q2w6e9r3t7y1.ogg?X-Amz-Signature=5e1c","expiresAt":"2026-10-27T19:00:00.000Z"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"`gone`: The resource expired or was removed; request a new one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Watch the calls"}},"/v1/businesses/{id}/calls/{callId}/sse-ticket":{"post":{"operationId":"callSseTicket","summary":"A 60-second single-use ticket for a call's live transcript stream (EventSource).","description":"A 60-second single-use ticket for a call's live transcript stream (EventSource).","tags":["calls"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"callId","in":"path","required":true,"description":"A call id (`call_…`) from listCalls, simulateCall or a call offer.","schema":{"type":"string","pattern":"^call_[0-9a-z]{8,32}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"ticket":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["ticket","expiresAt"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`insufficient_scope`: read-scope keys may only GET; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"dashboard"}},"/v1/businesses/{id}/calls/{callId}":{"get":{"operationId":"getCall","summary":"One call with its full transcript.","description":"One call with its full transcript.\n\nLifecycle step: Watch the calls.","tags":["calls"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"callId","in":"path","required":true,"description":"A call id (`call_…`) from listCalls, simulateCall or a call offer.","schema":{"type":"string","pattern":"^call_[0-9a-z]{8,32}$"},"example":"call_x4n8q2w6e9r3t7y1"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"call":{"$ref":"#/components/schemas/Call"},"transcript":{"type":"array","items":{"type":"object","properties":{"seq":{"type":"number"},"speaker":{"type":"string"},"text":{"type":"string"},"at":{"type":"string"}},"required":["seq","speaker","text","at"],"additionalProperties":false}}},"required":["call","transcript"],"additionalProperties":false},"example":{"call":{"id":"call_x4n8q2w6e9r3t7y1","businessId":"biz_7k2m9q4x8w3n5p1r","direction":"inbound","from":"+14155550199","to":"+14155550187","status":"completed","provider":"livekit-telnyx","providerCallId":"SCL_8hd73ks0","startedAt":"2026-10-27T18:41:02.000Z","answeredAt":"2026-10-27T18:41:03.000Z","endedAt":"2026-10-27T18:42:31.000Z","endReason":"caller_hangup","segments":[{"handler":"ai","startedAt":"2026-10-27T18:41:03.000Z","endedAt":"2026-10-27T18:42:31.000Z"}],"summary":{"intent":"book_appointment","outcome":"answered","callerName":"Sam","summary":"Sam asked about a deep tissue massage on Saturday; given the price and the booking link by SMS.","followUpNeeded":false,"sentiment":"positive"},"billedCents":21},"transcript":[{"seq":0,"speaker":"ai","text":"Thanks for calling Harbor Wellness. This call may be answered by an AI assistant. How can I help?","at":"2026-10-27T18:41:03.000Z"},{"seq":1,"speaker":"caller","text":"Hi, how much is a deep tissue massage, and can I come Saturday?","at":"2026-10-27T18:41:09.000Z"},{"seq":2,"speaker":"ai","text":"Deep tissue is $125 for 75 minutes, and we're open Saturday 10 to 4. Want me to text you the booking link?","at":"2026-10-27T18:41:14.000Z"}]}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Watch the calls"}},"/v1/businesses/{id}/test-call":{"post":{"operationId":"testCall","summary":"Ring one of the business's verified numbers from its RingKit number with the AI (a real, billed call).","description":"Ring one of the business's verified numbers from its RingKit number with the AI (a real, billed call).\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nStop and ask the human when: the phone at `to` rings with the AI receptionist: ask the human to answer and talk to it like a caller, then read the result with listCalls / getCall.\n\nLifecycle step: Place a test call.","tags":["calls"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"}},"required":["to"]},"example":{"to":"+14155550142"}}}},"responses":{"202":{"description":"Accepted: the work is queued.","content":{"application/json":{"schema":{"type":"object","properties":{"queued":{"type":"boolean","const":true},"consentId":{"type":"string","pattern":"^obc_[0-9a-z]{8,32}$"}},"required":["queued","consentId"],"additionalProperties":false},"example":{"queued":true,"consentId":"obc_e3g7j1l5n9q2s6u0"}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business. `destination_not_allowed`: Configure the number on the business first (ownerPhone, a routing transfer target or an SMS notify target), then verify it. `destination_unverified`: Verify the number first: POST .../destinations/verify, then .../destinations/confirm with the code the call read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key. `number_required`: Provision a number first: GET /v1/numbers/search, then POST /v1/businesses/:id/numbers. `test_call_limit`: The 24-hour outbound call limit for this business or number was reached; try again after it rolls over.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"`telephony_unavailable`: No telephony host is connected right now; retry in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Place a test call"}},"/v1/businesses/{id}/destinations/verify":{"post":{"operationId":"verifyDestination","summary":"Call a number and read it a 6-digit code, to prove the business controls it.","description":"Call a number and read it a 6-digit code, to prove the business controls it.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nStop and ask the human when: the call rings `number` and reads a 6-digit code twice (valid 10 minutes): ask the person who answered for the code, then send it with confirmDestination.\n\nLifecycle step: Place a test call.","tags":["destinations"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"}},"required":["number"]},"example":{"number":"+14155550142"}}}},"responses":{"202":{"description":"Accepted: the work is queued.","content":{"application/json":{"schema":{"type":"object","properties":{"queued":{"type":"boolean","const":true},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"consentId":{"type":"string","pattern":"^obc_[0-9a-z]{8,32}$"}},"required":["queued","expiresAt","consentId"],"additionalProperties":false},"example":{"queued":true,"expiresAt":"2026-10-27T16:40:00.000Z","consentId":"obc_b7d1f5h9k3m6p0s4"}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key. `already_verified`. `number_required`: Provision a number first: GET /v1/numbers/search, then POST /v1/businesses/:id/numbers. `test_call_limit`: The 24-hour outbound call limit for this business or number was reached; try again after it rolls over.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"`telephony_unavailable`: No telephony host is connected right now; retry in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Place a test call"}},"/v1/businesses/{id}/destinations/confirm":{"post":{"operationId":"confirmDestination","summary":"Confirm a number with the code its verification call read.","description":"Confirm a number with the code its verification call read.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nStop and ask the human when: you need the 6-digit code the verification call read; only the person who answered that call has it.\n\nLifecycle step: Place a test call.","tags":["destinations"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"code":{"type":"string","pattern":"^\\d{6}$"}},"required":["number","code"]},"example":{"number":"+14155550142","code":"481516"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"verifiedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"method":{"type":"string","enum":["voice_otp"]}},"required":["number","verifiedAt","method"],"additionalProperties":false},"example":{"number":"+14155550142","verifiedAt":"2026-10-27T16:32:10.000Z","method":"voice_otp"}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues. `invalid_code`: Send the 6-digit code the verification call read, exactly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key. `challenge_superseded`: A newer verification call replaced this code; use the code from the latest call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"`code_expired`: Request a new code: POST /v1/businesses/:id/destinations/verify.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`too_many_attempts`: Request a new code: POST /v1/businesses/:id/destinations/verify. `rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Place a test call"}},"/v1/businesses/{id}/destinations":{"get":{"operationId":"listDestinations","summary":"Numbers the business proved it controls (allowed test-call targets).","description":"Numbers the business proved it controls (allowed test-call targets).\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["destinations"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"destinations":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"verifiedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"method":{"type":"string","enum":["voice_otp"]}},"required":["number","verifiedAt","method"],"additionalProperties":false}}},"required":["destinations"],"additionalProperties":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true}},"/v1/businesses/{id}/outbound-consents":{"get":{"operationId":"listOutboundConsents","summary":"The audit trail of outbound calls RingKit placed for the business.","description":"The audit trail of outbound calls RingKit placed for the business.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["destinations"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"consents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^obc_[0-9a-z]{8,32}$"},"businessId":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"purpose":{"type":"string","enum":["test_call","callback","verify","forward_check"]},"basis":{"type":"string","enum":["configured_by_business","verified_destination","verification_request","forwarding_check"]},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"commandId":{"type":"string"},"consumedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","businessId","number","purpose","basis","createdBy","createdAt"],"additionalProperties":false}}},"required":["consents"],"additionalProperties":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true}},"/v1/businesses/{id}/demo-call":{"post":{"operationId":"startDemoCall","summary":"Talk to the receptionist from the browser over WebRTC (LiveKit room + join token): no number needed, not billed, not recorded, a few minutes at most, two per business.","description":"Talk to the receptionist from the browser over WebRTC (LiveKit room + join token): no number needed, not billed, not recorded, a few minutes at most, two per business.","tags":["calls"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"voice":{"type":"string","enum":["Ashley","Olivia","Sarah","Elizabeth","Edward","Dennis","Mark","Theodore","el:hpp4J3VqNfWAUOO0d1Us","el:EXAVITQu4vr4xnSDxMaL","el:XrExE9yKIg1WjnnlVkGX","el:cgSgspJ2msm6clMCkdW9","el:Xb7hH8MSUJpSbSDYk0k2","el:pFZP5JQG7iQjIQuC4Bku","el:cjVigY5qzO86Huf0OWal","el:iP95p4xoKVk53GoZ742B","el:nPczCjzI2devNBz1zQrb","el:bIHbv24MWmeRgasZH58o","el:JBFqnCBsd6RMkjVDRZzb","el:onwK4e9ZLuTAKqWW03F9"]}}},"example":{}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"provider":{"type":"string","const":"livekit"},"callId":{"anyOf":[{"type":"string","pattern":"^call_[0-9a-z]{8,32}$"},{"type":"null"}]},"roomName":{"type":"string"},"livekitUrl":{"type":"string"},"token":{"type":"string"},"participantIdentity":{"type":"string"},"maxSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"callsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["provider","callId","roomName","livekitUrl","token","participantIdentity","maxSeconds","expiresAt","callsRemaining"],"additionalProperties":false},{"type":"object","properties":{"provider":{"type":"string","const":"elevenlabs"},"callId":{"type":"string","pattern":"^call_[0-9a-z]{8,32}$"},"agentId":{"type":"string"},"conversationToken":{"type":"string"},"conversationId":{"type":"string"},"voiceId":{"type":"string"},"firstMessage":{"type":"string"},"dynamicVariables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"maxSeconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"callsRemaining":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["provider","callId","agentId","conversationToken","conversationId","dynamicVariables","maxSeconds","expiresAt","callsRemaining"],"additionalProperties":false}]},"example":{"provider":"livekit","callId":null,"roomName":"demo-0b7b6f2e-3c1a-4e0f-9a51-2d3c4b5a6f70","livekitUrl":"wss://ringkit.livekit.cloud","token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ3ZWI6...","participantIdentity":"web:5f1d2c3b-4a59-4e6f-8a7b-9c0d1e2f3a4b","maxSeconds":180,"expiresAt":"2026-10-27T16:42:00.000Z","callsRemaining":1}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`insufficient_scope`: read-scope keys may only GET; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`demo_limit_reached`: This business used its browser demo calls (or this network its daily ones); save the draft and get a number to keep calling, or try the text simulator (POST /v1/businesses/:id/simulate). `rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"`demo_unavailable`: Browser demo calls are unavailable right now; try again later, or use the text simulator (POST /v1/businesses/:id/simulate).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"dashboard"}},"/v1/businesses/{id}/simulate":{"post":{"operationId":"simulateCall","summary":"Run a text-mode call against the real receptionist to test knowledge and routing; no number needed; billed like a call at the AI rate from the wallet (the free trial credit covers it).","description":"Run a text-mode call against the real receptionist to test knowledge and routing; no number needed; billed like a call at the AI rate from the wallet (the free trial credit covers it).\n\nLifecycle step: Try it in text.","tags":["calls"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"callId":{"type":"string","pattern":"^call_[0-9a-z]{8,32}$"},"callerText":{"type":"string","maxLength":1000},"from":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"}},"required":["callerText"]},"example":{"callerText":"Hi, are you open on Saturday?"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"callId":{"type":"string","pattern":"^call_[0-9a-z]{8,32}$"},"aiText":{"type":"string"},"ended":{"type":"boolean"},"intent":{"type":"string"},"escalated":{"type":"boolean"}},"required":["callId","aiText","ended","escalated"],"additionalProperties":false},"example":{"callId":"call_s9d3f7h1k5m8p2r6","aiText":"Yes, we're open Saturday from 10 to 4. Would you like to book a massage?","ended":false,"intent":"hours","escalated":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`insufficient_scope`: read-scope keys may only GET; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Try it in text"}},"/v1/businesses/{id}/agent-controls":{"get":{"operationId":"getAgentControls","summary":"Which human agents may take the business's calls (vetted only, blocked agents). Inactive while RingKit's live-rep pool is not offered.","description":"Which human agents may take the business's calls (vetted only, blocked agents). Inactive while RingKit's live-rep pool is not offered.","tags":["agents"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"vettedAgentsOnly":{"type":"boolean"},"blockedAgentIds":{"type":"array","items":{"type":"string","pattern":"^agt_[0-9a-z]{8,32}$"}}},"required":["vettedAgentsOnly","blockedAgentIds"],"additionalProperties":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent"},"put":{"operationId":"putAgentControls","summary":"Change which human agents may take the business's calls. Inactive while RingKit's live-rep pool is not offered.","description":"Change which human agents may take the business's calls. Inactive while RingKit's live-rep pool is not offered.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["agents"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"vettedAgentsOnly":{"type":"boolean"},"blockedAgentIds":{"maxItems":500,"type":"array","items":{"type":"string","pattern":"^agt_[0-9a-z]{8,32}$"}}}}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"vettedAgentsOnly":{"type":"boolean"},"blockedAgentIds":{"type":"array","items":{"type":"string","pattern":"^agt_[0-9a-z]{8,32}$"}}},"required":["vettedAgentsOnly","blockedAgentIds"],"additionalProperties":false}}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true}},"/v1/businesses/{id}/agent-invites":{"post":{"operationId":"createBusinessAgentInvite","summary":"An invite code for the business's own receptionist, who will take only its calls.","description":"An invite code for the business's own receptionist, who will take only its calls.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["agents"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"expiresInHours":{"type":"number","exclusiveMinimum":0,"maximum":720}}}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["code","expiresAt"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true}},"/v1/businesses/{id}/agents/own":{"post":{"operationId":"markOwnAgent","summary":"Mark an agent who enrolled with the business's invite as its own staff.","description":"Mark an agent who enrolled with the business's invite as its own staff.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["agents"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","pattern":"^agt_[0-9a-z]{8,32}$"}},"required":["agentId"]}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","pattern":"^agt_[0-9a-z]{8,32}$"},"ownBusinessId":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"}},"required":["agentId","ownBusinessId"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business. `forbidden`: This credential can't act on this resource; use an API key or session that belongs to this business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true}},"/v1/businesses/{id}/wallet":{"get":{"operationId":"getWallet","summary":"Wallet balance, unspent trial credit and auto-refill settings.","description":"Wallet balance, unspent trial credit and auto-refill settings.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nLifecycle step: Fund the wallet.","tags":["wallet"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"balanceCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"trialCreditCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"autoRefill":{"anyOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"thresholdCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amountCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["enabled","thresholdCents","amountCents"],"additionalProperties":false},{"type":"null"}]},"canOrderOnTrial":{"default":false,"type":"boolean"},"numberTrial":{"type":"object","properties":{"numberId":{"type":"string","pattern":"^num_[0-9a-z]{8,32}$"},"number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"until":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["numberId","number","until"],"additionalProperties":false}},"required":["balanceCents","trialCreditCents","autoRefill","canOrderOnTrial"],"additionalProperties":false},"example":{"balanceCents":2500,"trialCreditCents":500,"autoRefill":null}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Fund the wallet"}},"/v1/businesses/{id}/wallet/top-ups":{"post":{"operationId":"topUp","summary":"Start a wallet top-up: returns a Stripe checkoutUrl for the human to pay.","description":"Start a wallet top-up: returns a Stripe checkoutUrl for the human to pay.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nStop and ask the human when: it returns a checkoutUrl: paying is the one setup step only a human can do. Give them the link, wait until they say they paid, then read getWallet to see the credit (checkoutUrl is null when payments are mocked and the wallet was credited at once).\n\nLifecycle step: Fund the wallet.","tags":["wallet"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amountCents":{"type":"integer","minimum":1000,"maximum":9007199254740991},"returnTo":{"default":"wallet","type":"string","enum":["wallet","onboard"]}},"required":["amountCents"]},"example":{"amountCents":2000}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"checkoutUrl":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"balanceCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["checkoutUrl","balanceCents"],"additionalProperties":false},"example":{"checkoutUrl":"https://checkout.stripe.com/c/pay/cs_live_a1b2c3d4e5f6","balanceCents":500}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"`payments_unavailable`: In-page payments aren't configured here; use POST /v1/businesses/:id/wallet/top-ups (hosted checkout), or retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Fund the wallet"}},"/v1/businesses/{id}/wallet/top-ups/{sessionId}/confirm":{"post":{"operationId":"confirmTopUp","summary":"After Stripe Checkout returns, credit a paid session (the webhook does it too).","description":"After Stripe Checkout returns, credit a paid session (the webhook does it too).\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["wallet"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"sessionId","in":"path","required":true,"description":"The Stripe Checkout session id (`cs_test_…` / `cs_live_…`) from the `session` query parameter Stripe returns with.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["paid","pending","unpaid"]},"balanceCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"credited":{"type":"boolean"},"duplicate":{"type":"boolean"},"amountCents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["status","balanceCents","credited","duplicate","amountCents"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"dashboard","x-owner-only":true}},"/v1/businesses/{id}/wallet/top-ups/intents":{"post":{"operationId":"createTopUpIntent","summary":"An in-page top-up PaymentIntent for the Stripe Payment Element.","description":"An in-page top-up PaymentIntent for the Stripe Payment Element.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["wallet"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amountCents":{"type":"integer","minimum":1000,"maximum":9007199254740991}},"required":["amountCents"]}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"paymentIntentId":{"type":"string"},"clientSecret":{"type":["string","null"]},"publishableKey":{"type":["string","null"]},"provider":{"type":"string","enum":["stripe","mock"]},"amountCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"balanceCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["paymentIntentId","clientSecret","publishableKey","provider","amountCents","balanceCents"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"`payments_unavailable`: In-page payments aren't configured here; use POST /v1/businesses/:id/wallet/top-ups (hosted checkout), or retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"dashboard","x-owner-only":true}},"/v1/businesses/{id}/wallet/top-ups/intents/{paymentIntentId}/confirm":{"post":{"operationId":"confirmTopUpIntent","summary":"After an in-page payment, credit a paid PaymentIntent (the webhook does it too).","description":"After an in-page payment, credit a paid PaymentIntent (the webhook does it too).\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["wallet"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"paymentIntentId","in":"path","required":true,"description":"The Stripe PaymentIntent id (`pi_…`) from createTopUpIntent.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["paid","pending","unpaid"]},"balanceCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"credited":{"type":"boolean"},"duplicate":{"type":"boolean"},"amountCents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["status","balanceCents","credited","duplicate","amountCents"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"dashboard","x-owner-only":true}},"/v1/businesses/{id}/wallet/auto-refill":{"get":{"operationId":"getAutoRefill","summary":"Read the auto-refill settings.","description":"Read the auto-refill settings.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["wallet"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"thresholdCents":{"type":"integer","minimum":0,"maximum":100000},"amountCents":{"type":"integer","minimum":1000,"maximum":100000},"hasPaymentMethod":{"type":"boolean"},"paymentMethod":{"anyOf":[{"type":"object","properties":{"brand":{"type":"string"},"last4":{"type":"string"}},"required":["brand","last4"],"additionalProperties":false},{"type":"null"}]},"lastRefillAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"lastError":{"type":"string"}},"required":["enabled","thresholdCents","amountCents","hasPaymentMethod","paymentMethod"],"additionalProperties":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true},"put":{"operationId":"putAutoRefill","summary":"Turn auto-refill on or off and set its threshold and amount (needs a saved card to run).","description":"Turn auto-refill on or off and set its threshold and amount (needs a saved card to run).\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nLifecycle step: Fund the wallet.","tags":["wallet"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"thresholdCents":{"type":"integer","minimum":0,"maximum":100000},"amountCents":{"type":"integer","minimum":1000,"maximum":100000}},"required":["enabled","thresholdCents","amountCents"]},"example":{"enabled":true,"thresholdCents":500,"amountCents":2000}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"},"thresholdCents":{"type":"integer","minimum":0,"maximum":100000},"amountCents":{"type":"integer","minimum":1000,"maximum":100000},"hasPaymentMethod":{"type":"boolean"},"paymentMethod":{"anyOf":[{"type":"object","properties":{"brand":{"type":"string"},"last4":{"type":"string"}},"required":["brand","last4"],"additionalProperties":false},{"type":"null"}]},"lastRefillAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"lastError":{"type":"string"}},"required":["enabled","thresholdCents","amountCents","hasPaymentMethod","paymentMethod"],"additionalProperties":false},"example":{"enabled":true,"thresholdCents":500,"amountCents":2000,"hasPaymentMethod":false,"paymentMethod":null}}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Fund the wallet"}},"/v1/businesses/{id}/wallet/setup-intent":{"post":{"operationId":"createSetupIntent","summary":"A Stripe SetupIntent to save a card for auto-refill.","description":"A Stripe SetupIntent to save a card for auto-refill.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["wallet"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"clientSecret":{"type":"string"},"setupIntentId":{"type":"string"},"provider":{"type":"string","enum":["stripe","mock"]},"publishableKey":{"type":["string","null"]},"mode":{"type":"string","enum":["live","test"]}},"required":["clientSecret","setupIntentId","provider","publishableKey","mode"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"503":{"description":"`payments_unavailable`: In-page payments aren't configured here; use POST /v1/businesses/:id/wallet/top-ups (hosted checkout), or retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"dashboard","x-owner-only":true}},"/v1/businesses/{id}/ledger":{"get":{"operationId":"listLedger","summary":"Wallet ledger entries (top-ups, call charges, rentals), newest first.","description":"Wallet ledger entries (top-ups, call charges, rentals), newest first.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).","tags":["wallet"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/LedgerEntry"}},"nextCursor":{"type":["string","null"]}},"required":["items","nextCursor"],"additionalProperties":false}}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true}},"/v1/businesses/{id}/webhooks":{"get":{"operationId":"listWebhooks","summary":"List the business's webhook endpoints.","description":"List the business's webhook endpoints.\n\nLifecycle step: Get told about calls.","tags":["webhooks"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^whk_[0-9a-z]{8,32}$"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["call.completed","message.taken","balance.low"]}},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","url","events","createdAt"],"additionalProperties":false}}},"required":["webhooks"],"additionalProperties":false},"example":{"webhooks":[{"id":"whk_c8e2g6j0l4n7q1s5","url":"https://hooks.example.com/ringkit","events":["call.completed","message.taken","balance.low"],"createdAt":"2026-10-27T16:50:00.000Z"}]}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-lifecycle-step":"Get told about calls"},"post":{"operationId":"createWebhook","summary":"Register a webhook for call.completed, message.taken or balance.low; the signing secret is returned once.","description":"Register a webhook for call.completed, message.taken or balance.low; the signing secret is returned once.\n\nOwner only (API keys act as owner; a member session gets 403 owner_required).\n\nLifecycle step: Get told about calls.","tags":["webhooks"],"parameters":[{"name":"id","in":"path","required":true,"description":"The business id (`biz_…`), as returned by POST /v1/businesses or GET /v1/me.","schema":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"example":"biz_7k2m9q4x8w3n5p1r"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["call.completed","message.taken","balance.low"]}}},"required":["url","events"]},"example":{"url":"https://hooks.example.com/ringkit","events":["call.completed","message.taken","balance.low"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^whk_[0-9a-z]{8,32}$"},"secret":{"type":"string"}},"required":["id","secret"],"additionalProperties":false},"example":{"id":"whk_c8e2g6j0l4n7q1s5","secret":"whsec_6b9f2d4a8c1e7f3b5d0a9c2e4f6b8d1a"}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`owner_required`: a member session can't call this (API keys act as owner); `insufficient_scope`: a read-scope key; `forbidden`: the credential belongs to another business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: over the per-key (or per-route) limit; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent","x-owner-only":true,"x-lifecycle-step":"Get told about calls"}},"/v1/agents":{"post":{"operationId":"createAgent","summary":"Dev only: create a gig agent and get a dev bearer token.","description":"Dev only: create a gig agent and get a dev bearer token.","tags":["agents"],"security":[],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"skills":{"default":[],"type":"array","items":{"type":"string"}}},"required":["name","email"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string","pattern":"^agt_[0-9a-z]{8,32}$"},"name":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"skills":{"default":[],"type":"array","items":{"type":"string"}},"tier":{"default":"trainee","type":"string","enum":["trainee","standard","vetted"]},"payRatePerMinCents":{"default":30,"type":"integer","minimum":0,"maximum":9007199254740991},"payPerCallCents":{"default":10,"type":"integer","minimum":0,"maximum":9007199254740991},"qualityScore":{"type":"number","minimum":0,"maximum":100},"blockedBy":{"default":[],"type":"array","items":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"}},"ownBusinessId":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","name","email","skills","tier","payRatePerMinCents","payPerCallCents","blockedBy","createdAt"],"additionalProperties":false},"token":{"type":"string"}},"required":["agent","token"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: This credential can't act on this resource; use an API key or session that belongs to this business.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: too many unauthenticated requests from this IP; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"console"}},"/v1/agents/enroll":{"post":{"operationId":"enrollAgent","summary":"Enroll as a human agent with an invite code; emails a console sign-in link.","description":"Enroll as a human agent with an invite code; emails a console sign-in link.","tags":["agents"],"security":[],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inviteCode":{"type":"string","minLength":6,"maxLength":100},"name":{"type":"string","minLength":1,"maxLength":120},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"skills":{"default":[],"type":"array","items":{"type":"string"}}},"required":["inviteCode","name","email"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string","pattern":"^agt_[0-9a-z]{8,32}$"},"magicLinkSent":{"type":"boolean","const":true}},"required":["agentId","magicLinkSent"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: too many unauthenticated requests from this IP; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"console"}},"/v1/agents/me/sse-ticket":{"post":{"operationId":"agentSseTicket","summary":"A 60-second single-use ticket for the agent console event stream.","description":"A 60-second single-use ticket for the agent console event stream.","tags":["agents"],"security":[{"agentSession":[]}],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"ticket":{"type":"string"},"expiresAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["ticket","expiresAt"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"console"}},"/v1/agents/me":{"get":{"operationId":"agentMe","summary":"The signed-in human agent.","description":"The signed-in human agent.","tags":["agents"],"security":[{"agentSession":[]}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","pattern":"^agt_[0-9a-z]{8,32}$"},"name":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"skills":{"default":[],"type":"array","items":{"type":"string"}},"tier":{"default":"trainee","type":"string","enum":["trainee","standard","vetted"]},"payRatePerMinCents":{"default":30,"type":"integer","minimum":0,"maximum":9007199254740991},"payPerCallCents":{"default":10,"type":"integer","minimum":0,"maximum":9007199254740991},"qualityScore":{"type":"number","minimum":0,"maximum":100},"blockedBy":{"default":[],"type":"array","items":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"}},"ownBusinessId":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","name","email","skills","tier","payRatePerMinCents","payPerCallCents","blockedBy","createdAt"],"additionalProperties":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"console"}},"/v1/agents/me/earnings":{"get":{"operationId":"agentEarnings","summary":"The agent's unpaid earnings and payouts.","description":"The agent's unpaid earnings and payouts.","tags":["agents"],"security":[{"agentSession":[]}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"unpaidCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"payouts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","pattern":"^pay_[0-9a-z]{8,32}$"},"period":{"type":"string"},"periodStart":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"periodEnd":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"amountCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["pending","exported","paid"]},"exportedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"paidAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"externalRef":{"type":"string"}},"required":["id","period","periodStart","periodEnd","amountCents","status"],"additionalProperties":false}}},"required":["unpaidCents","payouts"],"additionalProperties":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"console"}},"/v1/agents/me/calls/{callId}/command":{"post":{"operationId":"agentCommand","summary":"Act on the agent's active call: ask the copilot, speak (text mode), or take an action (take a message, transfer, SMS, flag spam, end).","description":"Act on the agent's active call: ask the copilot, speak (text mode), or take an action (take a message, transfer, SMS, flag spam, end).","tags":["agents"],"security":[{"agentSession":[]}],"parameters":[{"name":"callId","in":"path","required":true,"description":"A call id (`call_…`) from listCalls, simulateCall or a call offer.","schema":{"type":"string","pattern":"^call_[0-9a-z]{8,32}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"ask"},"text":{"type":"string","maxLength":500}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"say"},"text":{"type":"string","maxLength":2000}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"action"},"action":{"type":"string","enum":["take_message","transfer","send_sms","flag_spam","end_call"]},"args":{"default":{},"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["type","action"]}]}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"console"}},"/v1/agents/me/presence":{"get":{"operationId":"getPresence","summary":"The agent's presence (offline, available, wrap-up, ...).","description":"The agent's presence (offline, available, wrap-up, ...).","tags":["agents"],"security":[{"agentSession":[]}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"presence":{"type":"string","enum":["offline","available","ringing","on_call","wrap_up"]}},"required":["presence"],"additionalProperties":false}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"console"},"put":{"operationId":"setPresence","summary":"Go available, offline or into wrap-up.","description":"Go available, offline or into wrap-up.","tags":["agents"],"security":[{"agentSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"presence":{"type":"string","enum":["offline","available","ringing","on_call","wrap_up"]}},"required":["presence"]}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"presence":{"type":"string","enum":["offline","available","ringing","on_call","wrap_up"]}},"required":["presence"],"additionalProperties":false}}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"console"}},"/v1/agents/me/offers/{callId}/accept":{"post":{"operationId":"acceptOffer","summary":"Accept a call offer and get the token to join it.","description":"Accept a call offer and get the token to join it.","tags":["agents"],"security":[{"agentSession":[]}],"parameters":[{"name":"callId","in":"path","required":true,"description":"A call id (`call_…`) from listCalls, simulateCall or a call offer.","schema":{"type":"string","pattern":"^call_[0-9a-z]{8,32}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"joinToken":{"type":"string"},"callId":{"type":"string","pattern":"^call_[0-9a-z]{8,32}$"},"livekitUrl":{"type":"string"}},"required":["joinToken","callId"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"console"}},"/v1/agents/me/offers/{callId}/decline":{"post":{"operationId":"declineOffer","summary":"Decline a call offer.","description":"Decline a call offer.","tags":["agents"],"security":[{"agentSession":[]}],"parameters":[{"name":"callId","in":"path","required":true,"description":"A call id (`call_…`) from listCalls, simulateCall or a call offer.","schema":{"type":"string","pattern":"^call_[0-9a-z]{8,32}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"401":{"description":"`unauthorized`: missing, invalid or revoked credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"`forbidden`: the credential can't act on this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"`not_found`: no such resource (check the id).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"console"}},"/v1/feedback":{"post":{"operationId":"submitFeedback","summary":"Send product feedback to the RingKit team (any caller, including anonymous).","description":"Send product feedback to the RingKit team (any caller, including anonymous).","tags":["feedback"],"security":[],"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":2000},"category":{"type":"string","enum":["bug","idea","question","other"]},"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"page":{"type":"string","maxLength":200,"pattern":"^\\/"},"context":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["message","category"]}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"id":{"type":"string","pattern":"^fbk_[0-9a-z]{8,32}$"}},"required":["ok","id"],"additionalProperties":false}}},"headers":{"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}}},"400":{"description":"`validation_error`: the body, query or path failed the schema; `details` lists the issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"`idempotency_in_progress` / `lost_claim`: another request with this Idempotency-Key is running or won; retry with the same key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"`rate_limited`: too many unauthenticated requests from this IP; wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/RetryAfter"}}},"5XX":{"description":"`internal` or a `*_unavailable` code: retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"x-audience":"agent"}}},"components":{"schemas":{"Business":{"type":"object","properties":{"id":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"name":{"type":"string","minLength":1,"maxLength":120},"timezone":{"type":"string","minLength":1},"vertical":{"type":"string","maxLength":60},"website":{"type":"string","format":"uri"},"ownerEmail":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"ownerPhone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"notify":{"default":[],"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"sms"},"to":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"}},"required":["type","to"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"email"},"to":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["type","to"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"webhook"},"url":{"type":"string","format":"uri"},"secret":{"type":"string","minLength":16}},"required":["type","url"],"additionalProperties":false}]}},"status":{"default":"active","type":"string","enum":["active","paused","suspended"]},"knowledgeTier":{"default":"starter","type":"string","enum":["starter","pro"]},"voice":{"default":"Ashley","type":"string","enum":["Ashley","Olivia","Sarah","Elizabeth","Edward","Dennis","Mark","Theodore","el:hpp4J3VqNfWAUOO0d1Us","el:EXAVITQu4vr4xnSDxMaL","el:XrExE9yKIg1WjnnlVkGX","el:cgSgspJ2msm6clMCkdW9","el:Xb7hH8MSUJpSbSDYk0k2","el:pFZP5JQG7iQjIQuC4Bku","el:cjVigY5qzO86Huf0OWal","el:iP95p4xoKVk53GoZ742B","el:nPczCjzI2devNBz1zQrb","el:bIHbv24MWmeRgasZH58o","el:JBFqnCBsd6RMkjVDRZzb","el:onwK4e9ZLuTAKqWW03F9"]},"voiceSource":{"default":"default","type":"string","enum":["default","auto","owner"]},"voiceReason":{"type":"string","maxLength":200},"onboardingCompletedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"createdVia":{"default":"api","type":"string","enum":["dashboard","api","mcp"]},"ownerSignedInAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"voiceStack":{"default":"livekit","type":"string","enum":["livekit","elevenlabs"]},"voiceStackState":{"type":"object","properties":{"applied":{"type":"string","enum":["livekit","elevenlabs"]},"brainMode":{"type":"string","enum":["elevenlabs","gateway"]},"elevenlabsAgentId":{"type":"string"},"elevenlabsKnowledgeDocId":{"type":"string"},"elevenlabsKnowledgeHash":{"type":"string"},"elevenlabsToolIds":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"elevenlabsAgentPromptHash":{"type":"string"},"elevenlabsPhoneNumberId":{"type":"string"},"carrierConnectionId":{"type":"string"},"steps":{"default":[],"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["tools","knowledge","agent","number_import","carrier_route","number_release"]},"status":{"type":"string","enum":["ok","skipped","failed"]},"detail":{"type":"string","maxLength":500}},"required":["name","status"],"additionalProperties":false}},"lastError":{"type":"string","maxLength":1000},"forcedByOperator":{"type":"boolean"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["applied","steps","updatedAt"],"additionalProperties":false},"billingMode":{"default":"live","type":"string","enum":["live","test"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","name","timezone","ownerEmail","notify","status","knowledgeTier","voice","voiceSource","createdVia","voiceStack","billingMode","createdAt","updatedAt"],"additionalProperties":false},"KnowledgeProfile":{"type":"object","properties":{"businessName":{"type":"string","minLength":1,"maxLength":120},"tagline":{"type":"string","maxLength":200},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"serviceArea":{"type":"string","maxLength":1000},"credentials":{"type":"array","items":{"type":"string","maxLength":300}},"estimateUrl":{"type":"string","pattern":"^https?:\\/\\/"},"evidence":{"type":"object","propertyNames":{"type":"string","enum":["businessName","tagline","summary","hours","address","phone","email","serviceArea","credentials","estimateUrl","bookingUrl","services","staff","faqs","policies"]},"additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["found","inferred","owner"]},"sourceUrl":{"type":"string","pattern":"^https?:\\/\\/"},"quote":{"type":"string","maxLength":1200}},"required":["status"],"additionalProperties":false}},"summary":{"default":"","type":"string","maxLength":1500},"hours":{"type":"object","properties":{"regular":{"default":{},"type":"object","propertyNames":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]},"additionalProperties":{"type":"array","items":{"type":"object","properties":{"open":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"close":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["open","close"],"additionalProperties":false}}},"exceptions":{"default":[],"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"windows":{"type":"array","items":{"type":"object","properties":{"open":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"close":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["open","close"],"additionalProperties":false}},"note":{"type":"string"}},"required":["date","windows"],"additionalProperties":false}},"note":{"type":"string","maxLength":300}},"required":["regular","exceptions"],"additionalProperties":false},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postalCode":{"type":"string"},"country":{"default":"US","type":"string"},"directions":{"type":"string","maxLength":500},"parking":{"type":"string","maxLength":300}},"required":["line1","city","region","postalCode","country"],"additionalProperties":false},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"bookingUrl":{"type":"string","format":"uri"},"services":{"default":[],"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","maxLength":500},"priceUsd":{"type":"number","minimum":0},"priceNote":{"type":"string","maxLength":120},"durationMin":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"bookingUrl":{"type":"string","format":"uri"}},"required":["name"],"additionalProperties":false}},"staff":{"default":[],"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string"},"bio":{"type":"string","maxLength":500},"schedule":{"type":"string","maxLength":200}},"required":["name"],"additionalProperties":false}},"faqs":{"default":[],"type":"array","items":{"type":"object","properties":{"q":{"type":"string"},"a":{"type":"string","maxLength":1000}},"required":["q","a"],"additionalProperties":false}},"policies":{"default":[],"type":"array","items":{"type":"object","properties":{"topic":{"type":"string"},"text":{"type":"string","maxLength":1000}},"required":["topic","text"],"additionalProperties":false}},"doNotSay":{"default":[],"type":"array","items":{"type":"string","maxLength":300}},"escalationContacts":{"default":[],"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"when":{"type":"string","maxLength":300}},"required":["label","when"],"additionalProperties":false}},"documents":{"default":[],"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"text":{"type":"string","maxLength":50000},"sourceUrl":{"type":"string","format":"uri"},"source":{"type":"object","properties":{"kind":{"type":"string","const":"upload"},"documentId":{"type":"string","pattern":"^doc_[0-9a-z]{8,32}$"},"fileName":{"type":"string"},"label":{"type":"string"},"uploadedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["kind","documentId","fileName","label","uploadedAt"],"additionalProperties":false}},"required":["id","title","text"],"additionalProperties":false}},"greeting":{"type":"string","maxLength":300},"voiceNotes":{"type":"string","maxLength":1000},"vibe":{"type":"object","properties":{"tones":{"minItems":1,"maxItems":2,"type":"array","items":{"type":"string","enum":["warm","professional","upbeat","calm","luxury","clinical","friendly","authoritative"]}},"formality":{"type":"string","enum":["casual","neutral","formal"]},"energy":{"type":"string","enum":["low","medium","high"]},"audience":{"type":"string","maxLength":60},"evidence":{"type":"string","maxLength":120}},"required":["tones","formality","energy","audience","evidence"],"additionalProperties":false}},"required":["summary","services","staff","faqs","policies","doNotSay","escalationContacts","documents"],"additionalProperties":false},"RoutingPolicy":{"type":"object","properties":{"handoff":{"type":"object","properties":{"unsure":{"type":"string","enum":["message","transfer"]},"requested":{"type":"string","enum":["message","transfer"]},"urgent":{"type":"string","enum":["message","transfer"]},"targetId":{"type":"string"}},"required":["unsure","requested","urgent"],"additionalProperties":false},"mode":{"default":"ai_only","type":"string","enum":["ai_only","ai_first","human_first"]},"schedule":{"default":[],"type":"array","items":{"type":"object","properties":{"days":{"minItems":1,"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}},"from":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"to":{"type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"mode":{"type":"string","enum":["ai_only","ai_first","human_first"]}},"required":["days","from","to","mode"],"additionalProperties":false}},"afterHoursMode":{"default":"ai_only","type":"string","enum":["ai_only","ai_first","human_first"]},"humanRingTimeoutS":{"default":8,"type":"integer","minimum":3,"maximum":30},"maxHumanOffers":{"default":3,"type":"integer","minimum":1,"maximum":5},"escalateOn":{"default":["caller_requests_human","always_human_intent","repeated_failure"],"type":"array","items":{"type":"string","enum":["caller_requests_human","always_human_intent","low_confidence","repeated_failure"]}},"alwaysHumanIntents":{"default":[],"type":"array","items":{"type":"string"}},"neverHumanIntents":{"default":[],"type":"array","items":{"type":"string"}},"transferTargets":{"default":[],"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"whenToUse":{"type":"string","maxLength":300}},"required":["id","label","number"],"additionalProperties":false}},"dailySpendCapUsd":{"type":"number","exclusiveMinimum":0},"recordCalls":{"default":true,"type":"boolean"},"discloseAi":{"default":true,"type":"boolean"},"requiredAgentSkills":{"default":[],"type":"array","items":{"type":"string"}},"vettedAgentsOnly":{"default":false,"type":"boolean"}},"required":["mode","schedule","afterHoursMode","humanRingTimeoutS","maxHumanOffers","escalateOn","alwaysHumanIntents","neverHumanIntents","transferTargets","recordCalls","discloseAi","requiredAgentSkills","vettedAgentsOnly"],"additionalProperties":false},"Call":{"type":"object","properties":{"id":{"type":"string","pattern":"^call_[0-9a-z]{8,32}$"},"businessId":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"direction":{"type":"string","enum":["inbound","outbound"]},"from":{"anyOf":[{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},{"type":"string","const":"anonymous"}]},"to":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"status":{"type":"string","enum":["ringing","in_progress","completed","failed","rejected"]},"provider":{"type":"string"},"providerCallId":{"type":"string"},"startedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"answeredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"endedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"endReason":{"type":"string","enum":["caller_hangup","agent_hangup","transferred","no_balance","spam","error","voicemail"]},"segments":{"default":[],"type":"array","items":{"type":"object","properties":{"handler":{"type":"string","enum":["ai","human"]},"agentId":{"type":"string","pattern":"^agt_[0-9a-z]{8,32}$"},"startedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"endedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["handler","startedAt"],"additionalProperties":false}},"summary":{"type":"object","properties":{"intent":{"type":"string","minLength":1,"maxLength":60},"outcome":{"type":"string","enum":["answered","message_taken","transferred","booked","callback_scheduled","spam","abandoned","unresolved"]},"callerName":{"type":"string"},"summary":{"type":"string","maxLength":1500},"message":{"type":"object","properties":{"callerName":{"type":"string"},"callbackNumber":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"message":{"type":"string"},"urgency":{"default":"normal","type":"string","enum":["low","normal","high"]}},"required":["message","urgency"],"additionalProperties":false},"followUpNeeded":{"default":false,"type":"boolean"},"sentiment":{"type":"string","enum":["positive","neutral","negative"]}},"required":["intent","outcome","summary","followUpNeeded"],"additionalProperties":false},"recordingUrl":{"type":"string"},"spamScore":{"type":"number","minimum":0,"maximum":1},"billedCents":{"type":"integer","minimum":0,"maximum":9007199254740991},"knowledgeHash":{"type":"string"}},"required":["id","businessId","direction","from","to","status","provider","providerCallId","startedAt","segments"],"additionalProperties":false},"LedgerEntry":{"type":"object","properties":{"id":{"type":"string","pattern":"^led_[0-9a-z]{8,32}$"},"account":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"business"},"id":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"}},"required":["kind","id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"agent"},"id":{"type":"string","pattern":"^agt_[0-9a-z]{8,32}$"}},"required":["kind","id"],"additionalProperties":false}]},"type":{"type":"string","enum":["top_up","call_charge","number_rental","knowledge_plan","adjustment","refund","agent_earning","agent_payout","trial_credit"]},"amountCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"callId":{"type":"string","pattern":"^call_[0-9a-z]{8,32}$"},"externalRef":{"type":"string"},"memo":{"type":"string","maxLength":300},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","account","type","amountCents","createdAt"],"additionalProperties":false},"KnowledgeDocument":{"type":"object","properties":{"id":{"type":"string","pattern":"^doc_[0-9a-z]{8,32}$"},"fileName":{"type":"string","minLength":1,"maxLength":200},"fileType":{"type":"string","enum":["pdf","docx","txt","md","html"]},"contentType":{"type":"string","maxLength":120},"byteSize":{"type":"integer","minimum":0,"maximum":9007199254740991},"sha256":{"type":"string","minLength":64,"maxLength":64},"sectionCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"estimatedTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"originalStored":{"type":"boolean"},"uploadedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"sections":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"label":{"type":"string","maxLength":200},"text":{"type":"string","maxLength":50000}},"required":["index","label","text"],"additionalProperties":false}}},"required":["id","fileName","fileType","contentType","byteSize","sha256","sectionCount","estimatedTokens","originalStored","uploadedAt"],"additionalProperties":false},"KnowledgeUsage":{"type":"object","properties":{"tier":{"type":"string","enum":["starter","pro"]},"tierSince":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"limits":{"type":"object","properties":{"maxDocuments":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"maxTokens":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"maxFileBytes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"monthlyCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["maxDocuments","maxTokens","maxFileBytes","monthlyCents"],"additionalProperties":false},"used":{"type":"object","properties":{"documents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tokens":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["documents","tokens"],"additionalProperties":false},"originalsStored":{"type":"boolean"}},"required":["tier","limits","used","originalsStored"],"additionalProperties":false},"OnboardingStatus":{"type":"object","properties":{"step":{"type":"string","enum":["number","done"]},"completedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"hasNumber":{"type":"boolean"},"knowledgeReady":{"type":"boolean"},"latestImport":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeImport"},{"type":"null"}]},"canOrderOnTrial":{"default":false,"type":"boolean"},"numberTrialDays":{"default":0,"type":"integer","minimum":0,"maximum":9007199254740991},"numberTrial":{"type":"object","properties":{"numberId":{"type":"string","pattern":"^num_[0-9a-z]{8,32}$"},"number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"until":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["numberId","number","until"],"additionalProperties":false},"forwarding":{"type":"object","properties":{"businessPhone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"verifiedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"lastCheck":{"type":"object","properties":{"checkId":{"type":"string","minLength":1,"maxLength":64},"at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"status":{"type":"string","enum":["pending","done"]},"outcome":{"type":"string","enum":["forwarded","not_forwarded","no_answer","error"]},"detail":{"type":"string","maxLength":500},"finishedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["checkId","at","status"],"additionalProperties":false},"numberId":{"type":"string","pattern":"^num_[0-9a-z]{8,32}$"},"number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"}},"required":["numberId","number"],"additionalProperties":false}},"required":["step","hasNumber","knowledgeReady","latestImport","canOrderOnTrial","numberTrialDays"],"additionalProperties":false},"KnowledgeImport":{"type":"object","properties":{"id":{"type":"string","pattern":"^kimp_[0-9a-z]{8,32}$"},"url":{"type":"string","format":"uri"},"status":{"type":"string","enum":["queued","running","done","failed"]},"estimatedTokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"found":{"type":"object","properties":{"hours":{"type":"boolean"},"services":{"type":"integer","minimum":0,"maximum":9007199254740991},"faqs":{"type":"integer","minimum":0,"maximum":9007199254740991},"policies":{"type":"integer","minimum":0,"maximum":9007199254740991},"summary":{"type":"boolean"}},"required":["hours","services","faqs","policies","summary"],"additionalProperties":false},"error":{"type":"string","maxLength":500},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"finishedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","url","status","createdAt"],"additionalProperties":false},"SetupConversation":{"type":"object","properties":{"id":{"type":"string","pattern":"^schat_[0-9a-z]{8,32}$"},"status":{"type":"string","enum":["open","closed"]},"context":{"type":"string","enum":["onboarding","knowledge"]},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"text":{"type":"string"},"at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"writes":{"default":[],"type":"array","items":{"type":"object","properties":{"tool":{"type":"string"},"summary":{"type":"string","maxLength":300}},"required":["tool","summary"],"additionalProperties":false}}},"required":["role","text","at","writes"],"additionalProperties":false}},"budget":{"type":"object","properties":{"usedCents":{"type":"integer","minimum":0,"maximum":9007199254740991},"limitCents":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["usedCents","limitCents"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","status","context","messages","budget","createdAt","updatedAt"],"additionalProperties":false},"ProvisionedNumber":{"type":"object","properties":{"id":{"type":"string","pattern":"^num_[0-9a-z]{8,32}$"},"businessId":{"type":"string","pattern":"^biz_[0-9a-z]{8,32}$"},"number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"provider":{"type":"string"},"providerNumberId":{"type":"string"},"monthlyCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"status":{"type":"string","enum":["active","released"]},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"releasedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"trialUntil":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"forwarding":{"type":"object","properties":{"businessPhone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"verifiedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"lastCheck":{"type":"object","properties":{"checkId":{"type":"string","minLength":1,"maxLength":64},"at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"status":{"type":"string","enum":["pending","done"]},"outcome":{"type":"string","enum":["forwarded","not_forwarded","no_answer","error"]},"detail":{"type":"string","maxLength":500},"finishedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["checkId","at","status"],"additionalProperties":false}},"additionalProperties":false}},"required":["id","businessId","number","provider","providerNumberId","monthlyCents","status","createdAt"],"additionalProperties":false},"AvailableNumber":{"type":"object","properties":{"number":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"},"region":{"type":"string"},"monthlyCents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"provider":{"type":"string"}},"required":["number","monthlyCents","provider"],"additionalProperties":false},"ApiKeyInfo":{"type":"object","properties":{"id":{"type":"string","pattern":"^key_[0-9a-z]{8,32}$"},"name":{"type":"string"},"scope":{"type":"string","enum":["manage","read"]},"prefix":{"type":"string"},"createdAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"lastUsedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"revokedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["id","name","scope","prefix","createdAt"],"additionalProperties":false},"ApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"docs":{"type":"string"},"details":{}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"rk_live_…","description":"The business API key, returned once by POST /v1/businesses (and by POST /v1/businesses/{id}/api-keys). Scopes: `manage` (default; acts as owner) and `read` (GET only: any other method is 403 insufficient_scope). The dashboard's `rk_session` cookie is accepted on the same routes."},"businessSession":{"type":"apiKey","in":"cookie","name":"rk_session","description":"Dashboard session (set by consumeMagicLink)."},"agentSession":{"type":"apiKey","in":"cookie","name":"rk_agent_session","description":"Human-agent console session (outside production, `Authorization: Bearer agent:<id>` also works)."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Any unique string (≤ 255 chars). A retry with the same key within 24 h returns the stored response with `Idempotent-Replayed: true` instead of running again.","schema":{"type":"string","maxLength":255}}},"headers":{"IdempotentReplayed":{"description":"`true` when this response is a stored replay of an earlier request with the same Idempotency-Key.","schema":{"type":"string","enum":["true"]}},"RetryAfter":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":0}}}}}