{"openapi":"3.1.0","info":{"title":"VoiceDesk AI Agent API","version":"1.0.0","summary":"Services, live pricing, compatibility, and demo / onboarding requests for AI agents.","description":"Public, unauthenticated API for AI agents and developers. Agents can read the catalog and submit requests made with a business owner's consent. It cannot purchase plans, start billable services, buy phone numbers, place calls or read customer data. The same operations are available over MCP (https://voicedeskai.org/api/mcp) and A2A (https://voicedeskai.org/.well-known/agent-card.json).","contact":{"name":"VoiceDesk AI","email":"help@voicedeskai.org","url":"https://voicedeskai.org/developers"},"termsOfService":"https://voicedeskai.org/terms"},"servers":[{"url":"https://voicedeskai.org/api/agent/v1"}],"paths":{"/services":{"get":{"operationId":"get_services","summary":"What VoiceDesk AI does","responses":{"200":{"description":"Service catalog","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pricing":{"get":{"operationId":"get_pricing","summary":"Current plans (USD) from the live catalog","responses":{"200":{"description":"Plans","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pricing"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/compatibility":{"post":{"operationId":"check_compatibility","summary":"Check fit for a business","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompatibilityInput"}}}},"responses":{"200":{"description":"Compatibility result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/demo-requests":{"post":{"operationId":"create_demo_request","summary":"Request a demo or partnership call (owner consent required)","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"16-128 characters ([A-Za-z0-9._:-]). Retrying with the same key and phone returns the same reference.","schema":{"type":"string","minLength":16,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemoRequestInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedRequest"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/onboarding-requests":{"post":{"operationId":"create_onboarding_request","summary":"Prepare onboarding (no account, subscription or charge is created)","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"16-128 characters ([A-Za-z0-9._:-]). Retrying with the same key and phone returns the same reference.","schema":{"type":"string","minLength":16,"maxLength":128}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingRequestInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedRequest"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/requests/{reference}":{"get":{"operationId":"get_demo_status","summary":"Status of a demo, partnership or onboarding request","security":[{"statusToken":[]}],"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","pattern":"^VD-[0-9A-HJKMNP-TV-Z]{10}$"}}],"responses":{"200":{"description":"Status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestStatus"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No request matches that reference and token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"statusToken":{"type":"http","scheme":"bearer","description":"The one-time status_token returned when the request was created."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_input","not_found","rate_limited","unavailable","internal"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{"type":"string"}},"retry_after_seconds":{"type":"integer"}}}}},"RequestStatus":{"type":"object","required":["reference","request_type","status","status_description","created_at","updated_at"],"properties":{"reference":{"type":"string","pattern":"^VD-[0-9A-HJKMNP-TV-Z]{10}$"},"request_type":{"type":"string","enum":["demo","partner","onboarding"]},"status":{"type":"string","enum":["received","in_progress","demo_scheduled","completed","closed"]},"status_description":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CreatedRequest":{"allOf":[{"type":"object","required":["reference","request_type","status","status_description","created_at","updated_at"],"properties":{"reference":{"type":"string","pattern":"^VD-[0-9A-HJKMNP-TV-Z]{10}$"},"request_type":{"type":"string","enum":["demo","partner","onboarding"]},"status":{"type":"string","enum":["received","in_progress","demo_scheduled","completed","closed"]},"status_description":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},{"type":"object","required":["status_token","idempotent_replay"],"properties":{"status_token":{"type":"string","description":"Shown once. Send as `Authorization: Bearer <status_token>` to read status."},"idempotent_replay":{"type":"boolean","description":"True when this answers a repeated Idempotency-Key; the previous token stops working."}}}]},"CompatibilityInput":{"type":"object","properties":{"industry":{"type":"string","maxLength":60},"country":{"type":"string","minLength":2,"maxLength":2},"expected_monthly_minutes":{"type":"integer","minimum":0,"maximum":1000000},"required_capabilities":{"maxItems":25,"type":"array","items":{"type":"string","maxLength":60}}}},"DemoRequestInput":{"type":"object","properties":{"contact_name":{"type":"string","minLength":1,"maxLength":120},"business_name":{"type":"string","minLength":1,"maxLength":160},"phone":{"type":"string","maxLength":40},"email":{"type":"string","maxLength":254},"industry":{"type":"string","maxLength":60},"best_time":{"type":"string","enum":["morning","afternoon","evening"]},"message":{"type":"string","maxLength":2000},"interest":{"default":"receptionist_demo","type":"string","enum":["receptionist_demo","partnership"]},"partner_type":{"type":"string","enum":["ai_agency","reseller","developer","saas_platform","consultant","other"]},"consent_to_contact":{"type":"boolean","const":true},"idempotency_key":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}},"required":["contact_name","business_name","phone","consent_to_contact"]},"OnboardingRequestInput":{"type":"object","properties":{"contact_name":{"type":"string","minLength":1,"maxLength":120},"business_name":{"type":"string","minLength":1,"maxLength":160},"phone":{"type":"string","maxLength":40},"email":{"type":"string","maxLength":254},"industry":{"type":"string","maxLength":60},"plan_code":{"type":"string","maxLength":40},"expected_monthly_minutes":{"type":"integer","minimum":0,"maximum":1000000},"website":{"type":"string","maxLength":300,"format":"uri"},"timezone":{"type":"string","maxLength":64},"message":{"type":"string","maxLength":2000},"consent_to_contact":{"type":"boolean","const":true},"idempotency_key":{"type":"string","minLength":16,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"}},"required":["contact_name","business_name","phone","email","consent_to_contact"]},"Pricing":{"type":"object","properties":{"currency":{"type":"string","const":"USD"},"as_of":{"type":"string","format":"date-time"},"plans":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"monthly_price_usd":{"type":"number"},"setup_fee_usd":{"type":"number"},"included_minutes_per_month":{"type":"integer"},"overage_price_per_minute_usd":{"type":["number","null"]}}}},"billing_notes":{"type":"array","items":{"type":"string"}},"signup_url":{"type":"string","format":"uri"}}}}}}