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

# API Reference

> Complete API reference for Truedy Public API

# API Reference

Welcome to the Truedy Public API reference. All endpoints are automatically generated from our OpenAPI specification.

## Base URL

All Public API endpoints are available at:

```
https://api.truedy.ai/api/public/v1
```

If you use a different deployment (e.g. self-hosted), replace the host with your instance base URL.

## Authentication

All endpoints require API key authentication using the **Authorization** header: `Authorization: Bearer <your-api-key>`. Create and manage keys in the dashboard ([API Keys](/api-reference/api-keys)); see [Authentication](/authentication) for details and error codes.

**Request examples:** All examples in this reference are **cURL** so you can copy, replace `YOUR_API_KEY` with your key, and run the request from your terminal.

**Idempotency:** Send `X-Idempotency-Key` (any unique string, e.g. UUID) on create requests to safely retry. These endpoints support it: **POST** `/calls`, **POST** `/batch-calls`, **POST** `/tools`, **POST** `/agents`.

```bash theme={null}
curl https://api.truedy.ai/api/public/v1/agents \
  -H "Authorization: Bearer truedy_YOUR_API_KEY"
```

## OpenAPI Specification

The complete OpenAPI 3.1 specification is available at:

* **Live Endpoint**: `https://api.truedy.ai/api/public/v1/openapi.json`
* **Local File**: [openapi.json](./openapi.json)

<Card title="View OpenAPI Spec" icon="code" href="https://api.truedy.ai/api/public/v1/openapi.json">
  View the live OpenAPI specification
</Card>

## Response format

Successful responses use a consistent shape:

* **data** – The resource(s) (object or array). Single-resource endpoints return an object; list endpoints return an array.
* **meta** – Includes `request_id` (use when contacting support) and `ts` (server timestamp).

Error responses use the structure in [Error Handling](/guides/error-handling) (`error` object with `code`, `message`, optional `details`; `meta` with `request_id`, `ts`).

**Pagination:** List endpoints use either `limit`/`offset` (e.g. calls, batch-calls, agents) or `page`/`limit` (e.g. contacts, telephony search). The response includes a `pagination` object (e.g. `total`, `limit`, `offset`, `has_more` or `page`, `pages`, `total`). See each resource’s List section for details.

## API Endpoints

The API is organized into the following resource groups:

* **Agents** - Manage AI voice agents
* **Calls** - Create and manage voice calls
* **Tools** - Configure external tool integrations
* **Knowledge Bases** - Manage knowledge base content
* **Voices** - Manage voice configurations
* **Telephony** - Phone number management
* **Batch Calls** - Batch call management
* **Contacts** - Contact and folder management

All endpoints are documented below with **cURL** request examples (paste and run with your API key), parameters, and **all possible response codes** (200, 201, 400, 401, 403, 404, 422, 429, 500) so you can handle success and errors accordingly. For error response shape and retries, see [Error Handling](/guides/error-handling).