HTTP quick starts
Four quick starts walk through the API with curl and an API key. Beside each curl command the pages show the same request in Node.js, with the built-in fetch, and in Python, with the requests library; both are written from the command, so they send what it sends. They use no Vocal SDK; quick starts for the SDKs are planned. Each page shows its requests in order, what to look for in each answer, the operations it uses and the contracts release that first served each of them.
On the Phase 0 host. Served. Every operation the four quick starts use was first released in 1.53.0 or earlier, and the api on the Phase 0 host serves all of them. On 2026-10-24 UTC the runner passed the 28 steps of the four quick starts against the Phase 0 host, which has pinned contracts 1.60.0 since deploy #70, with a
livekey: 27 steps were answered and one was skipped, as its page allows. No run with atestkey is recorded.
The quick starts
| Quick start | What you do | Scopes the key needs |
|---|---|---|
| Your first Agent | Read the Provider catalog, create an Agent draft, publish a version, read it | agents:read, agents:write |
| Place a web Call | Create a Call for the web channel, read it, end it, read its trace | calls:read, calls:write |
| Receive events | Read the event catalog, make a filter, read the log and the stream | events:read, webhooks:read, webhooks:write |
| Knowledge for an Agent | Create a Knowledge base, upload a document, bind it to an Agent, ask a query | knowledge:read, knowledge:write, agents:read, agents:write |
The last three use the Agent that the first one creates. A Webhook subscription delivers events to an endpoint of yours; contracts 1.63.0 adds the operations that create and manage one, and each of their reference pages says whether the Phase 0 host serves it. These quick starts create no subscription, so Receive events reads events instead and shows what a replay answers when no subscription exists.
Before you start
Use an API key created by a Member (see Authentication and keys) with the scopes in the table. The environment of the key decides which Providers an Agent may name: a mock Provider, which sends nothing to any vendor, runs for test keys only, and the catalog lists the mock transcriber and voice as not streaming, for which the api refused them with a live key. Your first Agent says how to choose. The pages use these placeholders; replace them with your own:
| Placeholder | Stands for |
|---|---|
https://api.example.test | The base URL of your API, in $VOCAL_API |
vk_test_... | Your API key, in $VOCAL_API_KEY |
agt_..., call_..., kb_... | The ids that earlier answers gave you |
<stt_provider> and so on | A value you chose from the catalog |
The runner
The repository that builds these pages holds a runner that sends the requests of all four quick starts in order and checks each answer's status and the fields the pages name. It prints one line per step, with the quick start, the step, the method and the path template and the result, and no identifier, body or key. It stops at the first failure with a non-zero exit code.
export VOCAL_API_KEY=vk_test_...
pnpm run quickstarts -- --api https://api.example.test --key-env VOCAL_API_KEY--key-env names the environment variable that holds the key, so the key never appears on a command line. --only first-agent,knowledge runs some quick starts and the ones they need, --providers auto|mock|real chooses whether mock Providers are preferred (auto, the default, prefers them for a test key and avoids them for any other), and --dry-run prints the plan and checks it against the document the reference is generated from, without sending anything. The runner leaves what it creates in the Organization, so point it at an Organization where leftovers do not matter.
The box at the top of this page records the runner's run against the Phase 0 host. No CI job runs it against a stack; the repository's gate runs its dry run and its unit tests, which use an in-process fake. A run against a host is a manual pnpm run quickstarts invocation.