API reference
This reference is generated from the public OpenAPI document of @vocalai/contracts 1.65.0. It lists 346 public operations; the api on the Phase 0 host serves 346 of them, and 0 are released in a later contracts version and not deployed. The api on the Phase 0 host pins contracts 1.65.0 since deploy #77 (2026-10-25). An operation first released in 1.65.0 or earlier is served there unless its page says it is not served yet, with the roadmap slice that owes it; an operation of a later release is released and not deployed.
The public Vocal API. JSON bodies use snake_case; unknown request fields are refused with 400, and clients must ignore unknown response fields. Every response carries X-Request-Id. From 1.51.0 every operation can answer 429 rate_limited, every success answer and every 429 carry the RateLimit-* counters, and every 429 and 503 carries Retry-After. From 1.52.0 the event catalog ships as the *EventData components, each field with its data class in x-vocal-data-class; from 1.62.0 a customer-emitted event of the family custom carries the data of the customer, which travels in no payload in PHI mode. From 1.63.0 the Webhook subscriptions are a resource of their own (/v1/webhooks): a delivery posts the envelope with the headers Vocal-Event-Id, Vocal-Delivery-Id, Vocal-Delivery-Attempt and Vocal-Signature: t=<unix seconds>,v1=<hex>, an HMAC-SHA256 under the subscription secret over the timestamp, a period and the raw body.
Requests carry a bearer credential, Authorization: Bearer ...: an API key (vk_...) used from a server and never from a browser, or a signed-in Member's token. An operation whose description says "Session only" refuses every API key. Error codes, event types, scopes and contracts versions have their own pages.
Resources
| Group | What it covers | Operations | Served on the Phase 0 host |
|---|---|---|---|
| Organization | The Organization a credential belongs to, its settings and its Agent defaults. | 4 | 4 |
| Members | The people of the Organization, their roles and the approval of their sign-ins. | 8 | 8 |
| API keys | The keys of the Organization, listed, created and revoked by Members. | 4 | 4 |
| Agents | The editable Agent draft, its resolved settings and the publish check. | 6 | 6 |
| Agent versions | Published Agent versions, their activation, dry runs, renders and tests. | 10 | 10 |
| Policies | Deterministic rules bound to hook points of a Call, with versions and dry runs. | 10 | 10 |
| Tools | Functions the model may call, and the secret that signs their requests. | 8 | 8 |
| Providers and credentials | The Provider catalog and the Provider credentials of the Organization. | 5 | 5 |
| Phone numbers | The Phone numbers of the Organization and the Agents they route to. | 3 | 3 |
| Calls | Starting, reading, controlling and ending Calls, their events, transcripts and judgments. | 11 | 11 |
| Recordings | The recordings of a Call and their audio. | 3 | 3 |
| Webhooks | Webhook subscriptions, their secrets, test events and deliveries, and the replay of past events to a subscription. | 10 | 10 |
| Usage | Usage events, the spend counter, the usage of one Call and the evaluation quota. | 4 | 4 |
| Compliance profile | The compliance profile of the Organization and its versions. | 2 | 2 |
| Knowledge bases | Knowledge bases, their versions, Sources, Documents, queries and evaluations. | 33 | 33 |
| Prompt templates | Prompt templates, their versions and renders, the prompt bases and the library. | 16 | 16 |
| Prompt evaluations and experiments | Evaluation suites, their scenarios, runs, labels and calibrations, and experiments on an Agent. | 28 | 28 |
| Decision corpora | Labelled decision cases of an Agent and the runs that score its decision lane. | 13 | 13 |
| Workflows | Conversation-scope Workflows, their versions and dry runs. | 11 | 11 |
| Events | The event catalog, the event log, the Organization event stream, event filters and the emission of a customer event. | 10 | 10 |
| Jobs | Long-running work and its results. | 4 | 4 |
| Pre-call hooks | Endpoints Vocal asks before a Call starts. | 8 | 8 |
| Outcomes and analyses | The Outcome of a Call and the analyses of its transcript. | 4 | 4 |
| Call trace and analytics | The trace of one Call, comparisons, content access and the analytics reads. | 13 | 13 |
| Capture windows and reveal grants | Time-boxed capture of the Calls of an Agent, and approved reveals of their content. | 10 | 10 |
| Connectors | The Connector catalog. | 2 | 2 |
| Connections | The authorized links of the Organization to external systems. | 8 | 8 |
| Tool bindings | Grants that let an Agent call named tools of a Connection. | 5 | 5 |
| Runs | The run log of tool calls and Triggers executed by the integrations service. | 2 | 2 |
| MCP servers | Third-party MCP servers, their tools and the pins of their schemas. | 8 | 8 |
| Triggers | Trigger subscriptions and the Trigger events they received. | 9 | 9 |
| Messages | Messages sent through a Connection. | 3 | 3 |
| Notification rules | Rules that send a notification when an event happens. | 5 | 5 |
| Contacts | The Contacts of the Organization: create, read, update and delete, lookup, batch upsert, imports, merge and purge, and the consent states of one Contact. | 13 | 13 |
| Consent | The consent ledger: consent records, suppression list imports and the check of whether an address may be contacted. | 4 | 4 |
| Processes | Process instances started from a Workflow of scope process, their step log, cancellation, and the customer events delivered to an instance. | 7 | 7 |
| Human tasks | The human tasks that a Process assigns to people: list, read, claim and complete. | 4 | 4 |
| Campaigns | Outbound Campaigns: the draft and its revisions, the attestation, dry runs, launch, pause, resume and cancellation, enrollments, numbers, progress and exports. | 20 | 20 |
| Platform | Platform settings for Vocal operators, the inventory and the prices. | 18 | 18 |