> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callva.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create an API token, talk to your voice agent in the browser, and read the call back over the API.

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).

**1. Create an API token**

1. Sign in to the dashboard at [app.callva.io](https://app.callva.io).
2. Open the organization menu at the top of the sidebar and choose **Settings**, then **API Keys**.
3. 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.
4. Choose **Create Key**, then copy the key.

> [!WARNING]
>
> 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](https://docs.callva.io/authentication.md) explains roles and scopes in full.

**2. Set your environment**

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

```bash theme={null}
export CALLVA_API="https://api.callva.io/api/v1/external"
export CALLVA_TOKEN="<your API token>"
```

**3. List your projects**

Check that the token works by listing the projects it reaches ([List projects](https://docs.callva.io/api-reference/projects/list-projects.md)):

```bash theme={null}
curl "$CALLVA_API/projects" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json"
```

A project token answers with its own project:

```json 200 OK theme={null}
{
  "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 }
}
```

> [accordion] 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:
>
> ```json 400 Bad Request theme={null}
> {
>   "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:
>
> ```bash Header theme={null}
> 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"
> ```
>
> ```bash Query string theme={null}
> 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.

**4. 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.

1. In the dashboard, open your project and choose **Voice Agent** in the sidebar, then the agent.
2. Choose **Test Agent** (the microphone button at the top right of the agent page). A test panel opens beside the page.
3. Choose **Start Call** and allow the browser to use your microphone.
4. 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**.

> [!NOTE]
>
> 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.

**5. Find the call**

List the project's calls, newest first ([List calls](https://docs.callva.io/api-reference/calls/list-calls.md)). `sort` takes a field key, with `-` in front for descending order; without it the list is not ordered newest first.

```bash theme={null}
curl "$CALLVA_API/calls?sort=-created_at&per_page=5" \
  -H "Authorization: Bearer $CALLVA_TOKEN" \
  -H "Accept: application/json"
```

```json 200 OK theme={null}
{
  "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](https://docs.callva.io/guides/calls.md) covers filtering.

**6. Read the call and its transcript**

Take the call's `id` and fetch the record ([Get a call](https://docs.callva.io/api-reference/calls/get-a-call.md)) and its transcript ([Get transcript](https://docs.callva.io/api-reference/transcripts/get-a-calls-transcript.md)):

```bash Call theme={null}
export CALLVA_CALL="01a1c74f-20eb-70d8-ba3f-63afe58bcd8c"

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

```bash Transcript theme={null}
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`:

```json 200 OK theme={null}
{
  "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

> [card] [Authentication and permissions](https://docs.callva.io/authentication.md)
>
> Choose the right token and role for each integration.

> [card] [Calls](https://docs.callva.io/guides/calls.md)
>
> Place outbound calls and work with call records at scale.

> [card] [Connect an AI agent](https://docs.callva.io/mcp.md)
>
> Let Claude, Cursor or any MCP client operate CallVA for you.

> [card] [API reference](https://docs.callva.io/api-reference/introduction.md)
>
> Every endpoint, with a playground that runs on your token.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.