API quickstart

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. For key permissions, expiry, and rotation, read API keys.

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 before planning an execution test.

1. Create an API key

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

export THREETONE_API_KEY="your_api_key"

2. Choose models and a saved voice

cURL

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

cURL

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:

{
  "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:

cURL

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 for the complete response schema.

Next steps

Authentication

Store keys safely and diagnose authentication failures.

Agents API

Review the generated request and response schemas.

Knowledge base

Prepare documents, inspect stored content, and review dependencies.

Channels and telephony

Review phone configuration and current execution limits.

Get started

Configure

Deploy

Monitor

Advanced

Resources

Guides

Legal

1. Create an API key

2. Choose models and a saved voice

3. Create an agent

4. Read the configuration back

Next steps

Authentication

Agents API

Knowledge base

Channels and telephony

​1. Create an API key

​2. Choose models and a saved voice

​3. Create an agent

​4. Read the configuration back

​Next steps

Authentication

Agents API

Knowledge base

Channels and telephony

1. Create an API key

2. Choose models and a saved voice

3. Create an agent

4. Read the configuration back

Next steps