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

# REST API endpoints for assistants

> Create, retrieve, update, and assign phone numbers to Talkturo AI assistants using the REST API. Includes full request and response field reference.

Assistants are the AI agents that handle your phone calls. Each assistant has its own system prompt, LLM configuration, voice settings, and transcription options. You can create assistants from a template to get sensible defaults quickly, then update individual fields as needed. Once an assistant is configured, you assign phone numbers to it so it can receive inbound calls or place outbound calls through a campaign.

***

## Create an assistant

`POST /api/assistants`

Creates a new assistant with default configuration. Use a `templateId` to pre-populate common settings, or start with `custom` and configure everything yourself via `PATCH`.

### Request body

<ParamField body="accountSlug" type="string" required>
  The slug identifier for your account or workspace. You can find this in your dashboard URL (for example, `my-team` in `https://app.talkturo.com/home/my-team`).
</ParamField>

<ParamField body="name" type="string" required>
  A human-readable name for the assistant (for example, `"Sales Agent"` or `"Support Bot"`).
</ParamField>

<ParamField body="templateId" type="string">
  Pre-populates the assistant with a starter configuration. Accepted values: `outbound-setter`, `inbound-support`, `follow-up`, `custom`. Defaults to `custom` if omitted.
</ParamField>

### Example request

```bash theme={null}
curl -X POST https://<your-domain>/api/assistants \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountSlug": "my-team",
    "name": "Q1 Outbound Setter",
    "templateId": "outbound-setter"
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "assistant": {
    "id": "asst_01j...",
    "account_id": "acct_...",
    "name": "Q1 Outbound Setter",
    "type": "outbound-setter",
    "model": "gpt-4o-mini",
    "provider": "openai",
    "temperature": 0.7,
    "max_tokens": 1024,
    "first_message": "Hi, this is Alex from Talkturo...",
    "system_prompt": "You are a friendly outbound sales assistant...",
    "voice_provider": "cartesia",
    "voice_model": "sonic-english",
    "voice_id": "...",
    "voice_name": "Alex",
    "transcriptor_provider": "deepgram",
    "transcriptor_model": "nova-2",
    "transcriptor_language": "en",
    "recording_enabled": true,
    "inbound_enabled": false,
    "outbound_enabled": true,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}
```

<ResponseField name="success" type="boolean">
  `true` when the assistant was created successfully.
</ResponseField>

<ResponseField name="assistant.id" type="string">
  Unique identifier for the assistant. Use this in subsequent `GET` and `PATCH` requests.
</ResponseField>

<ResponseField name="assistant.account_id" type="string">
  The account this assistant belongs to.
</ResponseField>

<ResponseField name="assistant.name" type="string">
  The name you provided.
</ResponseField>

<ResponseField name="assistant.type" type="string">
  The template type used to create the assistant.
</ResponseField>

<ResponseField name="assistant.model" type="string">
  The LLM model identifier (for example, `gpt-4o-mini`).
</ResponseField>

<ResponseField name="assistant.provider" type="string">
  The LLM provider (for example, `openai`, `anthropic`, `google`).
</ResponseField>

<ResponseField name="assistant.temperature" type="number">
  LLM sampling temperature. Higher values produce more varied output.
</ResponseField>

<ResponseField name="assistant.max_tokens" type="integer">
  Maximum tokens per LLM response.
</ResponseField>

<ResponseField name="assistant.first_message" type="string">
  The first thing the assistant says when a call connects.
</ResponseField>

<ResponseField name="assistant.system_prompt" type="string">
  The system instructions that define the assistant's behavior and persona.
</ResponseField>

<ResponseField name="assistant.voice_provider" type="string">
  The TTS provider (for example, `cartesia`, `elevenlabs`).
</ResponseField>

<ResponseField name="assistant.voice_model" type="string">
  The voice model identifier for the selected TTS provider.
</ResponseField>

<ResponseField name="assistant.voice_id" type="string">
  The specific voice ID within the provider.
</ResponseField>

<ResponseField name="assistant.voice_name" type="string">
  Human-readable name for the selected voice.
</ResponseField>

<ResponseField name="assistant.transcriptor_provider" type="string">
  The STT provider (for example, `deepgram`, `assemblyai`).
</ResponseField>

<ResponseField name="assistant.transcriptor_model" type="string">
  The transcription model (for example, `nova-2`).
</ResponseField>

<ResponseField name="assistant.transcriptor_language" type="string">
  BCP-47 language code for transcription (for example, `en`, `es`, `fr`).
</ResponseField>

<ResponseField name="assistant.recording_enabled" type="boolean">
  Whether call recording is active for this assistant.
</ResponseField>

<ResponseField name="assistant.inbound_enabled" type="boolean">
  Whether this assistant can receive inbound calls.
</ResponseField>

<ResponseField name="assistant.outbound_enabled" type="boolean">
  Whether this assistant can place outbound calls.
</ResponseField>

<ResponseField name="assistant.created_at" type="string">
  ISO 8601 timestamp of when the assistant was created.
</ResponseField>

<ResponseField name="assistant.updated_at" type="string">
  ISO 8601 timestamp of the most recent update.
</ResponseField>

***

## Get an assistant

`GET /api/assistants/{assistantId}`

Retrieves the full configuration of a single assistant.

### Path parameters

<ParamField path="assistantId" type="string" required>
  The unique ID of the assistant to retrieve.
</ParamField>

### Example request

```bash theme={null}
curl https://<your-domain>/api/assistants/asst_01j... \
  -H "Authorization: Bearer <token>"
```

### Response

```json theme={null}
{
  "success": true,
  "assistant": {
    "id": "asst_01j...",
    "name": "Q1 Outbound Setter",
    "provider": "openai",
    "model": "gpt-4o-mini",
    "system_prompt": "You are a friendly outbound sales assistant...",
    "voice_provider": "cartesia",
    "voice_id": "...",
    "inbound_enabled": false,
    "outbound_enabled": true,
    ...
  }
}
```

***

## Update an assistant

`PATCH /api/assistants/{assistantId}`

Updates one or more configuration fields on an existing assistant. All fields except `accountSlug` are optional — include only the fields you want to change.

### Path parameters

<ParamField path="assistantId" type="string" required>
  The unique ID of the assistant to update.
</ParamField>

### Request body

<ParamField body="accountSlug" type="string" required>
  Your account slug. Required to verify ownership.
</ParamField>

<ParamField body="name" type="string">
  Updated assistant name.
</ParamField>

<ParamField body="first_message" type="string">
  The opening line the assistant speaks when a call connects.
</ParamField>

<ParamField body="system_prompt" type="string">
  Updated system instructions. You can use CRM template variables like `{{contact.first_name}}`.
</ParamField>

<ParamField body="provider" type="string">
  LLM provider. Supported values include `openai`, `anthropic`, `google`, `deepseek`, `qwen`.
</ParamField>

<ParamField body="model" type="string">
  LLM model identifier for the selected provider (for example, `gpt-4o`, `gpt-4o-mini`).
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature for the LLM (0.0–2.0).
</ParamField>

<ParamField body="max_tokens" type="integer">
  Maximum tokens per LLM completion.
</ParamField>

<ParamField body="voice_provider" type="string">
  TTS provider. Supported values: `cartesia`, `elevenlabs`.
</ParamField>

<ParamField body="voice_model" type="string">
  Voice model identifier for the selected TTS provider.
</ParamField>

<ParamField body="voice_id" type="string">
  Specific voice ID within the TTS provider.
</ParamField>

<ParamField body="voice_name" type="string">
  Human-readable label for the voice.
</ParamField>

<ParamField body="transcriptor_provider" type="string">
  STT provider. Supported values include `deepgram`, `assemblyai`.
</ParamField>

<ParamField body="transcriptor_model" type="string">
  Transcription model (for example, `nova-2`).
</ParamField>

<ParamField body="transcriptor_language" type="string">
  BCP-47 language code for transcription (for example, `en`, `es`, `fr`).
</ParamField>

<ParamField body="recording_enabled" type="boolean">
  Enable or disable stereo call recording.
</ParamField>

<ParamField body="inbound_enabled" type="boolean">
  Allow this assistant to handle inbound calls.
</ParamField>

<ParamField body="outbound_enabled" type="boolean">
  Allow this assistant to place outbound calls.
</ParamField>

### Example request

```bash theme={null}
curl -X PATCH https://<your-domain>/api/assistants/asst_01j... \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountSlug": "my-team",
    "system_prompt": "You are a helpful sales assistant for Acme Corp. Your goal is to qualify leads and book demos.",
    "voice_provider": "elevenlabs",
    "voice_id": "EXAVITQu4vr4xnSDxMaL",
    "recording_enabled": true
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "assistant": {
    "id": "asst_01j...",
    "name": "Q1 Outbound Setter",
    "system_prompt": "You are a helpful sales assistant for Acme Corp...",
    "voice_provider": "elevenlabs",
    "voice_id": "EXAVITQu4vr4xnSDxMaL",
    "recording_enabled": true,
    ...
  }
}
```

***

## Assign phone numbers to an assistant

`PATCH /api/assistants/{assistantId}/telephony/phone-numbers`

Assigns or replaces the phone numbers linked to an assistant. Passing an empty array removes all assigned numbers. You can get phone number IDs from the [phone numbers endpoints](/en/api-reference/phone-numbers).

### Path parameters

<ParamField path="assistantId" type="string" required>
  The unique ID of the assistant.
</ParamField>

### Request body

<ParamField body="accountSlug" type="string" required>
  Your account slug.
</ParamField>

<ParamField body="phoneNumberIds" type="array" required>
  An array of phone number ID strings to assign to this assistant. This replaces any existing assignments. Pass an empty array (`[]`) to remove all phone numbers from the assistant.
</ParamField>

### Example request

```bash theme={null}
curl -X PATCH https://<your-domain>/api/assistants/asst_01j.../telephony/phone-numbers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountSlug": "my-team",
    "phoneNumberIds": ["pn_01j...", "pn_02k..."]
  }'
```

### Response

```json theme={null}
{
  "success": true
}
```

<Note>
  After assigning a phone number, inbound calls to that number will automatically be routed to this assistant. Make sure `inbound_enabled` is set to `true` on the assistant if you want it to receive calls.
</Note>