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

# API quickstart

> Authenticate, choose compatible models and a saved voice, and create an agent with the Threetone API.

This guide lists the voices saved in your workspace, creates an agent with a compatible voice ID, and reads the saved configuration back.

For the dashboard workflow, start with [Create your first agent](/agents-platform/get-started/first-agent). For key permissions, expiry, and rotation, read [API keys](/overview/administration/workspaces/api-keys).

<Note>
  This guide creates a configuration and its initial version. Creation validates authoring structure; it does not compile or prove a working runtime. Later voice and custom-model publication are unavailable even when creation succeeds. Review [current availability](/agents-platform/overview#current-availability) before planning an execution test.
</Note>

## 1. Create an API key

Open [API Keys](https://threetone.in/app/developers/api-keys) in the Threetone dashboard. Create a key with the permissions required for agents and voices, then store it in a server-side environment variable.

```bash theme={null}
export THREETONE_API_KEY="your_api_key"
```

## 2. Choose models and a saved voice

```bash cURL theme={null}
curl --request GET \
  --url https://api.threetone.in/v1/voices \
  --header "x-api-key: $THREETONE_API_KEY"
```

Choose a saved `voice_id` compatible with your selected TTS model. If your voice library is empty, add a voice in the dashboard first.

Use [List available AI models](/api-reference/agents-platform/list-available-ai-models) to check which ASR, TTS, and LLM models are available to your workspace. Model IDs use `provider/model` format. The request below uses `cartesia/ink-2`, `cartesia/sonic-3.6`, and `google/gemma-4-31b`; replace them with available, language-compatible model IDs when needed.

## 3. Create an agent

Replace `YOUR_VOICE_ID` with the selected voice ID.

```bash cURL theme={null}
curl --request POST \
  --url https://api.threetone.in/v1/convai/agents/create \
  --header "x-api-key: $THREETONE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Customer support agent",
    "conversation_config": {
      "asr": {
        "model_id": "cartesia/ink-2",
        "recognition": { "mode": "fixed", "language": "en" }
      },
      "tts": {
        "model_id": "cartesia/sonic-3.6",
        "voice_id": "YOUR_VOICE_ID"
      },
      "agent": {
        "first_message": "Hello, how can I help?",
        "language": "en",
        "prompt": {
          "prompt": "Help customers clearly and accurately.",
          "llm": "google/gemma-4-31b",
          "tool_ids": [],
          "mcp_server_ids": [],
          "native_mcp_server_ids": []
        }
      }
    }
  }'
```

A successful response returns the new agent, main branch, and initial version identifiers:

```json theme={null}
{
  "agent_id": "agent_3701kwyb5spce24t3h8gpqpsy6zh",
  "main_branch_id": "agtbrch_2201kwyb5tmbfb3a8a3jmtd5v28d",
  "initial_version_id": "agtvrsn_1401kwyb5tpwe868p2dtmj62q48t"
}
```

## 4. Read the configuration back

Replace `YOUR_AGENT_ID` with the returned `agent_id` and retrieve the saved agent:

```bash cURL theme={null}
curl --request GET \
  --url https://api.threetone.in/v1/convai/agents/YOUR_AGENT_ID \
  --header "x-api-key: $THREETONE_API_KEY"
```

Confirm the name, `conversation_config`, and the branch and version metadata. Keep the identifiers with your integration settings. This verifies the saved configuration, not a successful conversation or traffic deployment. See [Get agent](/api-reference/agents-platform/get-agent) for the complete response schema.

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Store keys safely and diagnose authentication failures.
  </Card>

  <Card title="Agents API" icon="robot" href="/api-reference/agents-platform/create-agent">
    Review the generated request and response schemas.
  </Card>

  <Card title="Knowledge base" icon="book" href="/agents-platform/configure/knowledge-base/overview">
    Prepare documents, inspect stored content, and review dependencies.
  </Card>

  <Card title="Channels and telephony" icon="phone" href="/agents-platform/deploy/telephony/overview">
    Review phone configuration and current execution limits.
  </Card>
</CardGroup>


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