Developers

VoiceDesk AI agent API

One set of operations, three ways to call them: REST, MCP and A2A. Public, no API key, rate-limited. Agents can read and request; they can never buy, provision or read customer data.

OpenAPI spec For AI agents

Endpoints

Base URL: https://voicedeskai.org

Method	Path	Operation
GET	/api/agent/v1/services	get_services
GET	/api/agent/v1/pricing	get_pricing
POST	/api/agent/v1/compatibility	check_compatibility
POST	/api/agent/v1/demo-requests	create_demo_request
POST	/api/agent/v1/onboarding-requests	create_onboarding_request
GET	/api/agent/v1/requests/{reference}	get_demo_status (Authorization: Bearer <status_token>)
POST	/api/mcp	MCP Streamable HTTP (2026-07-28; 2025-11-25 clients supported)
POST	/api/a2a	A2A 1.0 JSON-RPC (SendMessage)
GET	/.well-known/agent-card.json	A2A Agent Card
GET	/openapi.json	OpenAPI 3.1 spec

REST quick start

Live pricing

curl https://voicedeskai.org/api/agent/v1/pricing

Check fit

curl -X POST https://voicedeskai.org/api/agent/v1/compatibility \
  -H "Content-Type: application/json" \
  -d '{"industry":"hvac","expected_monthly_minutes":500,"required_capabilities":["human_transfer","after_hours_rules"]}'

Request a demo (only with the owner's consent)

curl -X POST https://voicedeskai.org/api/agent/v1/demo-requests \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-agent-run-7f3c2a91b4" \
  -d '{"contact_name":"Dana Smith","business_name":"Smith Roofing",
       "phone":"+16155550142","industry":"roofing","consent_to_contact":true}'

# 201 Created
{"reference":"VD-8K2M4Q7T9W","request_type":"demo","status":"received",
 "status_token":"vdst_…","idempotent_replay":false, …}

Track it

curl https://voicedeskai.org/api/agent/v1/requests/VD-8K2M4Q7T9W \
  -H "Authorization: Bearer vdst_…"

MCP

Remote server over Streamable HTTP, stateless (no sessions). Tools: get_services, get_pricing, check_compatibility, create_demo_request, get_demo_status, create_onboarding_request. Read-only tools are annotated readOnlyHint; none are destructive.

Client config

{ "mcpServers": { "voicedesk-ai": { "type": "http", "url": "https://voicedeskai.org/api/mcp" } } }

A2A

A2A protocol 1.0, JSON-RPC binding. Send the header A2A-Version: 1.0. Skills complete immediately, so SendMessage replies with a Message (no Tasks, no streaming, no push notifications). Invoke a skill with a data part.

SendMessage

curl -X POST https://voicedeskai.org/api/a2a \
  -H "Content-Type: application/json" -H "A2A-Version: 1.0" \
  -d '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{
        "messageId":"m-1","role":"ROLE_USER",
        "parts":[{"data":{"skill":"get_pricing","input":{}}}]}}}'

Rules of the road

Consent. create_demo_request and create_onboarding_request require consent_to_contact: true: only submit details of a business owner who asked to be contacted.
Idempotency. Send an Idempotency-Key header (REST) or idempotency_key field (16-128 characters). Repeating it with the same phone returns the same reference and a fresh status token; the old token stops working.
Status tokens. Returned once. Keep them private and send them in the Authorization header, never in a URL. Wrong tokens and unknown references both return 404.
Rate limits. 120 calls per minute per client; 5 new requests per hour per client; 40 new requests per hour across all agents.
No purchases. The API never creates accounts, subscriptions, phone numbers, calls or charges, and never returns customer data.
US only. Phone numbers must be valid US (+1) numbers.

Errors

Every error has the same shape

{"error":{"code":"invalid_input","message":"Some fields are missing or invalid.",
  "details":{"phone":"phone must be a valid 10-digit US number, e.g. +16155550123"}}}

HTTP	code	Meaning
400	invalid_input	A field is missing or invalid; see error.details.
404	not_found	Unknown operation, or no request matches that reference and status token.
429	rate_limited	Slow down; honour Retry-After.
503	unavailable	Live pricing could not be read. Retry shortly.
500	internal	Unexpected error. Nothing internal is ever included.

Questions or a production integration? Email help@voicedeskai.org or apply on the partners page.