VocalDocscontracts 1.65.0

Introduction

Vocal runs voice Agents. You describe an Agent through the API, with its instructions, the Providers it listens, thinks and speaks with, and its Tools and Policies, and Vocal runs its Calls in a browser or on the phone and keeps a trace of each one.

Not published yet. This is a development copy of the site, built from released public artifacts and kept out of search engines until the documentation is published.

Quick start

Four HTTP quick starts take you from an API key to an Agent that answers. Each request is a curl command, shown beside the same request in Node.js and Python, and every command is checked against the API reference these pages are generated from.

  • Your first Agent Read the Provider catalog, create an Agent draft and publish a version of it.
  • Place a web Call Start a Call for the browser, read it, end it and read its trace.
  • Receive events Read the event catalog, filter the event log and open the event stream.
  • Knowledge for an Agent Upload a document to a Knowledge base, bind it to an Agent and ask it a question.

Run Calls

  • Authentication and keys API keys, Members, the live and test environments, and the conventions every request shares.
  • Web Calls Start a Call on your server and join it from a browser with a token good for that Call alone.
  • Phone numbers Route a number to an Agent, place outbound Calls and set the dial policy.
  • The Call trace The timeline of a finalized Call: its Turns, stages, Providers, quality flags and cost.
  • Outcomes and analyses The typed results a Call leaves behind, and the analyzers that run after it.

Shape an Agent

  • Tools and the events channel Functions the model may call, request signatures, and the per-Call WebSocket.
  • Policies Deterministic rules at the hook points of a Call, with versions and dry runs.
  • Knowledge bases Documents an Agent may cite, ingested into passages and retrieved during a Call.
  • Prompt templates The Agent layer of the model request as a versioned, linted resource.
  • Statecharts and Workflows Explicit states, guarded transitions, slots, squad Agents and conversation-scope Workflows.
  • Integrations Connectors, Connections, Tool bindings, MCP servers and Triggers; the service that runs them is not deployed.

API reference

  • Overview Every public operation, grouped by resource, with its scope, shapes, error codes and the release that added it.
  • Error codes Every error code with its HTTP status.
  • Event types The event types and the Call event types.
  • Contracts versions What each contracts release added and whether the Phase 0 host serves it.

How to read these pages

Each page says whether what it describes is served by the api on the Phase 0 host, released in the contracts and not deployed, or planned. A figure is either measured, with its source, or labelled a target.

The API is described by the contracts: a versioned package whose public OpenAPI document is the source of every reference page. The reference documents contracts 1.65.0. The api on the Phase 0 host may pin an earlier release, and may not serve every operation of the release it pins: the reference overview names the release the hosted api pins, and every operation page says whether the host serves the operation, whether it is released in a later contracts version and not deployed, or whether it is released and not served on the host yet.

The Node.js samples use the fetch built into Node.js, and the Python samples use the requests library. Both are plain HTTP; the Vocal SDKs are planned and not built.

Not here yet

A CI job that runs the quick starts against a stack, the pages of the Connector catalog, and quick starts for the SDKs are planned. The HTTP quick starts have been run by hand against the Phase 0 host; see HTTP quick starts.