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

# Calls

# Calls

Create and manage outbound voice calls. The public API creates outbound calls only. Inbound calls are handled automatically when a phone number is assigned to an agent.

For UUID / phone / datetime formats used below, see [Data formats](/api-reference/introduction#data-formats).

## List Calls

<Endpoint method="GET" path="/api/public/v1/calls" />

### Parameters

**Query parameters:**

| Parameter   | Type    | Description                                                 |
| ----------- | ------- | ----------------------------------------------------------- |
| `status`    | string  | Filter by call status (see [Call Statuses](#call-statuses)) |
| `direction` | string  | `inbound` or `outbound`                                     |
| `agent_id`  | UUID    | Filter by agent                                             |
| `limit`     | integer | 1–100. Default `50`                                         |
| `offset`    | integer | Pagination offset. Default `0`                              |

```bash theme={null}
curl "https://api.truedy.ai/api/public/v1/calls?status=completed&limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

`data` (array of call objects), `pagination` (`total`, `limit`, `offset`, `has_more`), `meta`.

## Get Call

<Endpoint method="GET" path="/api/public/v1/calls/{call_id}" />

```bash theme={null}
curl "https://api.truedy.ai/api/public/v1/calls/44ec8f61-6d9a-4553-a6ca-777f5f5ef95b" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Create Call

<Endpoint method="POST" path="/api/public/v1/calls" />

Place an outbound call using a specified agent. The call is always outbound when created via the public API.

### Request Body

| Field           | Type           | Required | Description                                                                                                                                                                             |
| --------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_id`      | UUID           | **Yes**  | Agent that will handle the call                                                                                                                                                         |
| `phone_number`  | string (E.164) | **Yes**  | Destination number to call (e.g. `+15551234567`)                                                                                                                                        |
| `from_number`   | string (E.164) | No       | Caller ID override. Must be a number assigned to this agent for outbound. If omitted, the system selects automatically.                                                                 |
| `variables`     | object         | No       | Key-value pairs passed to the agent as **template variables**. Use in your system prompt with mustache syntax: `{{first_name}}`, `{{company}}`, etc. All values are treated as strings. |
| `call_settings` | object         | No       | Per-call overrides (see `call_settings` fields below)                                                                                                                                   |

### `call_settings` Fields

| Field                   | Type    | Default | Description                                                                   |
| ----------------------- | ------- | ------- | ----------------------------------------------------------------------------- |
| `recording_enabled`     | boolean | `true`  | Record the call                                                               |
| `transcription_enabled` | boolean | `true`  | Transcribe the call                                                           |
| `greeting`              | string  | —       | Override the agent's configured greeting for this specific call               |
| `max_duration`          | string  | —       | Maximum call length, e.g. `"3600s"`. Overrides agent default for this call.   |
| `join_timeout`          | string  | —       | Time to wait for the callee to answer, e.g. `"30s"`. Overrides agent default. |

**Outbound call requirements:**

* The agent must have at least one phone number **assigned for outbound** (see [Telephony — Assign Number](/api-reference/telephony#assign-number)), or you must provide `from_number`.
* If no outbound number is available, the API returns **422**.
* The telephony provider (Telnyx, Twilio, Plivo) is determined from the number's credential.

### Example

```json theme={null}
{
  "agent_id": "1f4baf16-1540-4d91-9696-7f34b2f2cb77",
  "phone_number": "+14155550123",
  "variables": {
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "Acme Inc",
    "appointment_time": "2pm Thursday"
  },
  "call_settings": {
    "recording_enabled": true,
    "max_duration": "600s"
  }
}
```

```bash theme={null}
curl -X POST "https://api.truedy.ai/api/public/v1/calls" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 8b7e6494-3839-49dc-9638-a1944fdd8cda" \
  -d '{
    "agent_id": "1f4baf16-1540-4d91-9696-7f34b2f2cb77",
    "phone_number": "+14155550123",
    "variables": { "first_name": "Jane", "company": "Acme Inc" }
  }'
```

**Response:** 201 Created with `data` (call object: `id`, `agent_id`, `phone_number`, `direction`, `status`, etc.) and `meta`. Send `X-Idempotency-Key` for safe retries.

## Update Call

<Endpoint method="PATCH" path="/api/public/v1/calls/{call_id}" />

Update metadata on a call. Only `context` and `call_settings` can be updated after creation.

**Body:** `context` (object, any key-value data to store on the call record) and/or `call_settings` (object with `recording_enabled`, `transcription_enabled`). Only included fields are updated.

```bash theme={null}
curl -X PATCH "https://api.truedy.ai/api/public/v1/calls/44ec8f61-6d9a-4553-a6ca-777f5f5ef95b" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context": { "priority": "high" },
    "call_settings": { "recording_enabled": true }
  }'
```

## Delete Call

<Endpoint method="DELETE" path="/api/public/v1/calls/{call_id}" />

Cannot delete active calls (`queued`, `ringing`, `in_progress`). Completed, failed, and other terminal calls can be deleted.

```bash theme={null}
curl -X DELETE "https://api.truedy.ai/api/public/v1/calls/44ec8f61-6d9a-4553-a6ca-777f5f5ef95b" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Bulk Delete Calls

<Endpoint method="POST" path="/api/public/v1/calls/bulk-delete" />

**Body:** `ids` — array of call UUIDs to delete. Active calls in the list are skipped.

**Response:** `data: { deleted_count, failed_count, deleted_ids, failed_ids }`, `meta`.

```bash theme={null}
curl -X POST "https://api.truedy.ai/api/public/v1/calls/bulk-delete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "44ec8f61-6d9a-4553-a6ca-777f5f5ef95b",
      "f89052b2-3467-4a34-b4e3-e5d1571cbb36"
    ]
  }'
```

## Get Recording

<Endpoint method="GET" path="/api/public/v1/calls/{call_id}/recording" />

Returns a URL to the call recording audio. The URL is fetched from the telephony provider and cached on the call record.

```bash theme={null}
curl "https://api.truedy.ai/api/public/v1/calls/44ec8f61-6d9a-4553-a6ca-777f5f5ef95b/recording" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:** `data: { recording_url }`. Returns **404** if no recording exists (e.g. recording was disabled).

## Get Transcript

<Endpoint method="GET" path="/api/public/v1/calls/{call_id}/transcript" />

Returns the full transcript and summary for a completed call.

```bash theme={null}
curl "https://api.truedy.ai/api/public/v1/calls/44ec8f61-6d9a-4553-a6ca-777f5f5ef95b/transcript" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response:** `data: { transcript: [...], summary }`. Returns **404** if no transcript is available yet.

## Call Object

| Field              | Type     | Description                              |
| ------------------ | -------- | ---------------------------------------- |
| `id`               | UUID     | Call ID                                  |
| `agent_id`         | UUID     | Agent that handled the call              |
| `phone_number`     | string   | The number that was called               |
| `from_number`      | string   | Caller ID used                           |
| `direction`        | string   | `inbound` or `outbound`                  |
| `status`           | string   | See [Call Statuses](#call-statuses)      |
| `started_at`       | datetime | When the call connected                  |
| `ended_at`         | datetime | When the call ended                      |
| `duration_seconds` | integer  | Total call length                        |
| `cost_usd`         | float    | Billed cost                              |
| `summary`          | string   | AI-generated call summary                |
| `recording_url`    | string   | Recording URL (if enabled and available) |
| `context`          | object   | Any metadata stored on the call          |
| `created_at`       | datetime | When the call was created                |
| `updated_at`       | datetime | Last updated                             |

## Call Statuses

| Status        | Description                                           |
| ------------- | ----------------------------------------------------- |
| `queued`      | Call created, waiting to be placed                    |
| `ringing`     | Call is ringing the destination                       |
| `in_progress` | Call is active and connected                          |
| `completed`   | Call ended normally                                   |
| `failed`      | Call could not be placed (check `context.last_error`) |
| `no_answer`   | Callee did not answer                                 |
| `busy`        | Callee line was busy                                  |
| `voicemail`   | Call went to voicemail                                |

## Errors

| HTTP Status | Code               | Meaning                                                                                                 |
| ----------- | ------------------ | ------------------------------------------------------------------------------------------------------- |
| `422`       | `validation_error` | Invalid request — missing `agent_id`, invalid phone number, or no outbound number assigned to the agent |
| `402`       | `payment_required` | Insufficient credits or inactive subscription                                                           |
| `502`       | `provider_error`   | Telephony or voice provider error                                                                       |

**Failed calls:** When a call is created but the provider fails to place it, the call record has `status: "failed"`. The provider error message is stored in `context.last_error`. Fix the underlying issue and retry.