Agents & API

Get an API key

Registration is a single unauthenticated request. The apiKey is shown once — store it. New agent workspaces start unverified, with trial credits and reduced daily caps. Send `organization` to name who your forms are run for: respondents hear it in the AI disclosure that opens every voice session. It is optional, and you can set it later with set_organization.

curl -X POST https://api.survoyce.com/public/agents/register \
  -H 'content-type: application/json' \
  -d '{"name": "acme-research-agent", "organization": "Acme Research"}'

# → 201
# {"workspaceId": "…", "keyId": "…", "apiKey": "sv_…",
#  "organization": "Acme Research",
#  "verified": false, "trialCredits": 3, "message": "…"}

Authenticate and rotate

Send the key as a bearer token on every request: Authorization: Bearer <apiKey>. The header is the only accepted form — a key passed in the query string is refused with 401, because URLs end up in access logs, proxies and browser history in a way headers do not. Rotate with POST /v1/keys/rotate — the old key keeps working for a short grace window so in-flight work doesn’t break.

Connect over MCP

The MCP server speaks streamable HTTP at https://api.survoyce.com/api/mcp/survoyce/mcp and SSE at https://api.survoyce.com/api/mcp/survoyce/sse. Any MCP client works — for Claude Desktop, Claude Code, or Cursor, the config is:

{
  "mcpServers": {
    "survoyce": {
      "url": "https://api.survoyce.com/api/mcp/survoyce/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Available tools

Read: get_workspace, list_forms, get_form, list_submissions, get_answers (keyed JSON answers plus transcripts where retained). Write: create_form, add_question, update_question, delete_question, publish_form, unpublish_form, set_organization. Billing: list_credit_packs, purchase_credits (Stripe). Webhooks: list_webhook_events, create_webhook, list_webhooks, get_webhook, update_webhook, delete_webhook, rotate_webhook_secret, test_webhook, list_webhook_deliveries, replay_webhook_delivery — see the webhooks doc.

A2A

Prefer agent-to-agent? The intake agent's card is at https://api.survoyce.com/api/.well-known/intake/agent-card.json and JSON-RPC execution at POST https://api.survoyce.com/api/a2a/intake (bearer auth). It can list your forms and hand out respondent session links; humans always consent on the session page before any conversation starts.

REST

The intake agent is also reachable over plain REST at https://api.survoyce.com/api/agents/intake, and the OpenAPI spec is served at https://api.survoyce.com/api/openapi.json.

Limits & verification

Unverified workspaces have trial credits, reduced daily caps on form creation and credit purchases, and no access to outbound calling. Requests are rate-limited per key. Verification mechanisms are still evolving — contact us if you need higher limits.

The respondent experience

Humans answer your form by natural voice conversation, on the web or by phone — or, on the web, with the keyboard instead. Every session opens with a mandatory AI disclosure — it cannot be disabled. Sessions are designed to finish within about eight minutes, and abandoned sessions never cost a credit. Answers come back in the same structured shape either way; only voice sessions carry a transcript. Published form URLs from publish_form / create_session_link can also be embedded in any web page via the iframe snippet described in the channels doc (swap /f/ for /embed/ and include allow="microphone").