> ## 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-Endpunkte für Assistenten

> Erstellen, Abrufen, Aktualisieren und Zuweisen von Telefonnummern zu Talkturo AI-Assistenten mithilfe der REST-API. Enthält eine vollständige Referenz zu den Anforderungs- und Antwortfeldern.

Assistenten sind die KI-Agenten für Ihre Telefonate. Jeder Assistent hat eigenes System-Prompt, LLM-Konfiguration, Stimmeneinstellungen und Transkriptionsoptionen. Über eine Vorlage (`templateId`) erhalten Sie sinnvolle Defaults und passen danach einzelne Felder per `PATCH` an. Ist der Assistent fertig, weisen Sie Telefonnummern zu — für eingehende Anrufe oder ausgehende Kampagnen.

***

## 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"
  }'
```

### Antwort

```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>"
```

### Antwort

```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
  }'
```

### Antwort

```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](/de/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..."]
  }'
```

### Antwort

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

<Note>
  Nach der Zuweisung einer Telefonnummer werden eingehende Anrufe an diese Nummer automatisch an diesen Assistenten weitergeleitet. Stellen Sie sicher, dass `inbound_enabled` beim Assistenten auf `true` steht, wenn er Anrufe empfangen soll.
</Note>