Quickstart

In a few minutes you will have an API token, a test call made from your browser, and that call’s record and transcript fetched over the API. You need a CallVA account with a project that has a voice agent, and permission to create API keys in its organization (owners and admins have it; it is the api_tokens.create permission).

Create an API token

Sign in to the dashboard at app.callva.io.
Open the organization menu at the top of the sidebar and choose Settings, then API Keys.
Choose Create API Key and fill in the dialog:
- Key Name - what the key is for, such as Quickstart or n8n integration.
- Role - the permissions the key carries. For this quickstart the key needs calls.read and transcripts.read; the built-in Analyst role holds both and can change nothing.
- Project Scope - your project, for a project token that works in that project only, or All projects for an organization-wide token.
Choose Create Key, then copy the key.

The key is shown once, when it is created, and cannot be read again. Store it in your secret manager now. If you lose it, delete it and create another.

The role list offers only roles you may hand out: you cannot give a key a permission you do not hold yourself. Authentication and permissions explains roles and scopes in full.

Set your environment

Every example in these docs reads the base URL and your token from two variables:

export CALLVA_API="https://api.callva.io/api/v1/external"
export CALLVA_TOKEN="<your API token>"

List your projects

Check that the token works by listing the projects it reaches (List projects):

curl "$CALLVA_API/projects" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json"

A project token answers with its own project:

200 OK

{
  "success": true,
  "message": "Projects retrieved successfully",
  "data": [
    {
      "id": "01a1c749-5525-731a-ab9f-61ffbf9e4ef2",
      "tenant_id": "01a1c749-5387-7002-8154-5a7913629e6e",
      "name": "[TEST] docs-4d48b3d0",
      "description": "Synthetic test data for a live check.",
      "is_active": true,
      "is_default": true,
      "created_at": "2026-11-10T21:07:14.000000Z",
      "updated_at": "2026-11-10T21:07:14.000000Z",
      ...
    }
  ],
  "pagination": { "current_page": 1, "last_page": 1, "per_page": 25, "total": 1, "from": 1, "to": 1 }
}

Using an organization-wide token? Name the project.

An organization-wide token reaches every project of its organization, so each request must say which project it acts in - and that includes GET /projects. Without one, the API refuses the request:

400 Bad Request

{
  "success": false,
  "error": "Missing project context",
  "message": "This API token is tenant-scoped. Please provide project_id in the request payload or query parameters, or use a project-scoped token.",
  "code": "PROJECT_REQUIRED"
}

Send the project’s id in the X-Project-ID header, or as project_id - in the query string for reads and deletes, in the JSON body for writes:

export CALLVA_PROJECT="<your project id>"

curl "$CALLVA_API/projects" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "X-Project-ID: $CALLVA_PROJECT" \
  -H "Accept: application/json"

export CALLVA_PROJECT="<your project id>"

curl "$CALLVA_API/projects?project_id=$CALLVA_PROJECT" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json"

To find a project’s id, open the project in the dashboard and choose Project Settings: the id sits under the page title, and a click copies it. A project token ignores both, and always acts in its own project.

Talk to your agent in the browser

The dashboard can call your agent from the browser, using your microphone - no phone number and no phone line involved.

In the dashboard, open your project and choose Voice Agent in the sidebar, then the agent.
Choose Test Agent (the microphone button at the top right of the agent page). A test panel opens beside the page.
Choose Start Call and allow the browser to use your microphone.
Say a few sentences and let the agent answer, then choose End Call.

The test panel runs the agent’s saved configuration. If you edit the agent while the panel is open, the panel says that the change is not in the current call yet and offers Reload.

A test call is a real call on the voice engine, and it is recorded like any other: it becomes a call record in the project, with type set to webrtc (shown as Web in the dashboard). The agent must be active, and the organization must have the CallVA voice engine available.

Find the call

List the project’s calls, newest first (List calls). sort takes a field key, with - in front for descending order; without it the list is not ordered newest first.

curl "$CALLVA_API/calls?sort=-created_at&per_page=5" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json"

200 OK

{
  "success": true,
  "message": "Calls retrieved successfully",
  "data": [
    {
      "id": "01a1c74f-20eb-70d8-ba3f-63afe58bcd8c",
      "tenant_id": "01a1c749-5387-7002-8154-5a7913629e6e",
      "project_id": "01a1c749-5525-731a-ab9f-61ffbf9e4ef2",
      "created_at": "2026-11-10T21:13:34.000000Z",
      "updated_at": "2026-11-10T21:13:34.000000Z",
      "direction": "inbound",
      "duration": 42,
      "ended_at": "2026-11-10T21:13:22.000000Z",
      "name": "Web User",
      "started_at": "2026-11-10T21:12:40.000000Z",
      "status": "complete",
      "transcript": { "message_count": 3, ... },
      "type": "webrtc",
      "provider": "livekit"
    },
    ...
  ],
  "pagination": { "current_page": 1, "last_page": 1, "per_page": 5, "total": 4, "from": 1, "to": 4 }
}

A call carries its identity (id, tenant_id, project_id, created_at, updated_at) and then every field of the project’s data model at the top level, by field key. Fields with no value are left out. Every field key also works as a filter, such as status=complete or started_at_gte=2026-11-01; the Calls guide covers filtering.

Read the call and its transcript

Take the call’s id and fetch the record (Get a call) and its transcript (Get transcript):

export CALLVA_CALL="01a1c74f-20eb-70d8-ba3f-63afe58bcd8c"

curl "$CALLVA_API/calls/$CALLVA_CALL" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json"

curl "$CALLVA_API/calls/$CALLVA_CALL/transcript" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json"

The transcript is the conversation as a list of messages, each with its role (assistant for the agent, user for the caller), content and timestamp:

200 OK

{
  "success": true,
  "message": "Transcript retrieved successfully",
  "data": {
    "version": 1,
    "call_id": "01a1c74f-20eb-70d8-ba3f-63afe58bcd8c",
    "tenant_id": "01a1c749-5387-7002-8154-5a7913629e6e",
    "project_id": "01a1c749-5525-731a-ab9f-61ffbf9e4ef2",
    "created_at": "2026-11-10T21:13:40+00:00",
    "messages": [
      { "role": "assistant", "content": "Hello! Thanks for calling. How can I help you today?", "timestamp": "2026-11-10T21:12:41Z" },
      { "role": "user", "content": "Hi, I would like to know your opening hours.", "timestamp": "2026-11-10T21:12:47Z" },
      { "role": "assistant", "content": "We are open Monday to Friday, nine to six.", "timestamp": "2026-11-10T21:12:50Z" }
    ],
    "metadata": { "total_messages": 3 }
  }
}

A call that has no transcript yet answers 404 with "message": "No transcript found for this call".

Next steps

Authentication and permissions

Choose the right token and role for each integration.

Calls

Place outbound calls and work with call records at scale.

Connect an AI agent

Let Claude, Cursor or any MCP client operate CallVA for you.

API reference

Every endpoint, with a playground that runs on your token.

Get started

Ways in

Guides

Next steps

Authentication and permissions

Calls

Connect an AI agent

API reference

​Next steps

Authentication and permissions

Calls

Connect an AI agent

API reference

Next steps