Assistants

curl -X POST "https://api.talkturo.com/api/assistants" \
  -H "Authorization: Bearer tk_live_example_9xmk7q2r4f8n6p1s3d5h7j9k2m4q6w8" \
  -H "Content-Type: application/json" \
  -d '{
    "accountSlug": "acme-sales",
    "name": "Inbound Sales Assistant"
  }'

{
  "success": true,
  "assistant": {
    "id": "7f5a4d6e-1d1b-4f76-9b03-2e9f48d09f6a",
    "name": "Inbound Sales Assistant"
  }
}

curl -X POST "https://api.talkturo.com/api/assistants" \
  -H "Authorization: Bearer tk_live_example_9xmk7q2r4f8n6p1s3d5h7j9k2m4q6w8" \
  -H "Content-Type: application/json" \
  -d '{
    "accountSlug": "acme-sales",
    "name": "Inbound Sales Assistant",
    "templateId": "tmpl_sales_inbound_v1"
  }'

const response = await fetch("https://api.talkturo.com/api/assistants", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tk_live_example_9xmk7q2r4f8n6p1s3d5h7j9k2m4q6w8",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    accountSlug: "acme-sales",
    name: "Inbound Sales Assistant",
    templateId: "tmpl_sales_inbound_v1"
  })
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://api.talkturo.com/api/assistants",
    headers={
        "Authorization": "Bearer tk_live_example_9xmk7q2r4f8n6p1s3d5h7j9k2m4q6w8",
        "Content-Type": "application/json"
    },
    json={
        "accountSlug": "acme-sales",
        "name": "Inbound Sales Assistant",
        "templateId": "tmpl_sales_inbound_v1"
    }
)

print(response.json())

{
  "success": true,
  "assistant": {
    "id": "7f5a4d6e-1d1b-4f76-9b03-2e9f48d09f6a",
    "account_slug": "acme-sales",
    "name": "Inbound Sales Assistant",
    "type": "sales",
    "created_at": "2025-02-18T14:22:31.114Z",
    "updated_at": "2025-02-18T14:22:31.114Z"
  }
}

curl -X PATCH "https://api.talkturo.com/api/assistants/7f5a4d6e-1d1b-4f76-9b03-2e9f48d09f6a" \
  -H "Authorization: Bearer tk_live_example_9xmk7q2r4f8n6p1s3d5h7j9k2m4q6w8" \
  -H "Content-Type: application/json" \
  -d '{
    "accountSlug": "acme-sales",
    "name": "Inbound Sales Assistant v2",
    "voice": "alloy",
    "model": "gpt-4o-realtime"
  }'

const response = await fetch(
  "https://api.talkturo.com/api/assistants/7f5a4d6e-1d1b-4f76-9b03-2e9f48d09f6a",
  {
    method: "PATCH",
    headers: {
      "Authorization": "Bearer tk_live_example_9xmk7q2r4f8n6p1s3d5h7j9k2m4q6w8",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      accountSlug: "acme-sales",
      name: "Inbound Sales Assistant v2",
      voice: "alloy",
      model: "gpt-4o-realtime"
    })
  }
);

const data = await response.json();
console.log(data);

{
  "success": true,
  "assistant": {
    "id": "7f5a4d6e-1d1b-4f76-9b03-2e9f48d09f6a",
    "name": "Inbound Sales Assistant v2",
    "voice": "alloy",
    "model": "gpt-4o-realtime",
    "updated_at": "2025-02-18T14:31:09.027Z"
  }
}

curl -X DELETE "https://api.talkturo.com/api/assistants/7f5a4d6e-1d1b-4f76-9b03-2e9f48d09f6a" \
  -H "Authorization: Bearer tk_live_example_9xmk7q2r4f8n6p1s3d5h7j9k2m4q6w8"

{
  "success": true,
  "message": "Assistant deleted successfully"
}

curl -X POST "https://api.talkturo.com/api/assistants/7f5a4d6e-1d1b-4f76-9b03-2e9f48d09f6a/clone" \
  -H "Authorization: Bearer tk_live_example_9xmk7q2r4f8n6p1s3d5h7j9k2m4q6w8"

const response = await fetch(
  "https://api.talkturo.com/api/assistants/7f5a4d6e-1d1b-4f76-9b03-2e9f48d09f6a/clone",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer tk_live_example_9xmk7q2r4f8n6p1s3d5h7j9k2m4q6w8"
    }
  }
);

const data = await response.json();
console.log(data);

{
  "success": true,
  "assistant": {
    "id": "0f3f8bc6-5e95-4344-88d2-8e5660ec9bf1",
    "name": "Inbound Sales Assistant (Copy)",
    "created_at": "2025-02-18T14:39:12.442Z",
    "updated_at": "2025-02-18T14:39:12.442Z"
  }
}

curl -X GET "https://api.talkturo.com/api/assistants/7f5a4d6e-1d1b-4f76-9b03-2e9f48d09f6a/usage-stats?accountId=9a6e7d1c-3fd1-4af6-a3ab-b0e9d3ac4a71" \
  -H "Authorization: Bearer tk_live_example_9xmk7q2r4f8n6p1s3d5h7j9k2m4q6w8"

const response = await fetch(
  "https://api.talkturo.com/api/assistants/7f5a4d6e-1d1b-4f76-9b03-2e9f48d09f6a/usage-stats?accountId=9a6e7d1c-3fd1-4af6-a3ab-b0e9d3ac4a71",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer tk_live_example_9xmk7q2r4f8n6p1s3d5h7j9k2m4q6w8"
    }
  }
);

const data = await response.json();
console.log(data);

{
  "totalCalls": 148,
  "totalMinutes": 912.0,
  "avgDurationMinutes": 6.2,
  "completedCallsWithDuration": 145,
  "successRatePercent": 87.5,
  "successEvaluatedCount": 130,
  "timeline": {
    "today": 5,
    "last7Days": 45,
    "last30Days": 148,
    "last365Days": 148
  },
  "dailySeries": [
    { "date": "2025-02-18", "count": 6 },
    { "date": "2025-02-17", "count": 4 }
  ]
}

Manage assistants

Create assistants, update their configuration, clone existing setups, delete assistants you no longer need, and retrieve usage data for reporting or operational checks.

Base path

All endpoints on this page are rooted at /api/assistants.

Authentication

Send your API key in the Authorization header as a bearer token.

If you use session-based auth from the Talkturo app, the browser sends the session cookie automatically. External integrations usually use API keys.

Create an assistant

Create a new assistant under an account by sending the account slug and assistant name. If you provide a template ID, Talkturo sets the assistant type from that template.

Endpoint

POST /api/assistants

Body parameters

Response fields

Talkturo creates the assistant with default or null values for fields you do not provide at creation time. Update the assistant afterward to configure prompts, voices, models, or telephony settings.

Update an assistant

Update an existing assistant by assistant ID. The update endpoint accepts accountSlug and any assistant fields supported by the backend.

Endpoint

PATCH /api/assistants/{assistantId}

Path parameters

Body parameters

Response fields

When the update succeeds, the response includes the saved assistant object. Use that object as the source of truth for the assistant's latest configuration.

Delete an assistant

Delete an assistant permanently by ID. Talkturo checks ownership before removing the record.

Endpoint

DELETE /api/assistants/{assistantId}

Path parameters

Response fields

Clone an assistant

Clone an existing assistant to duplicate its configuration into a new assistant record. Use cloning when you want a starting point for a variant instead of rebuilding settings manually.

Endpoint

POST /api/assistants/{assistantId}/clone

Path parameters

Body parameters

Response fields

After cloning, update the new assistant if you need to change the name, prompts, or telephony configuration before using it in production.

Retrieve usage statistics

Fetch usage data for a single assistant. Use this endpoint for monitoring, dashboards, or account-level reporting workflows.

Endpoint

GET /api/assistants/{assistantId}/usage-stats

Path parameters

Query parameters

Response fields

Tool configurations

Tool configs let you attach third-party tools such as Cal.com scheduling, Zapier, or custom webhooks to an assistant.

Get tool configs by type

Use this endpoint to retrieve one config, or all configs, for a specific tool type.

Endpoint

GET /api/assistants/{assistantId}/tool-configs/{toolType}

Path parameters

Query parameters

Create or update a tool config

Use this endpoint to create a new tool config or update an existing one for the selected tool type.

Endpoint

POST /api/assistants/{assistantId}/tool-configs/{toolType}

Path parameters

Query parameters

Body parameters

Delete tool configs

Delete one config by ID, or remove all configs for a tool type.

Endpoint

DELETE /api/assistants/{assistantId}/tool-configs/{toolType}

Path parameters

Query parameters

Billing estimate

Fetch an estimated credits-per-minute cost based on the assistant's provider settings and the active cost catalog.

Endpoint

GET /api/assistants/{assistantId}/billing/estimate

Path parameters

Query parameters

Response fields

Knowledge base attachments

Manage knowledge-base files attached to an assistant. Attach existing files from the account library. These endpoints do not upload new files. See Knowledge Base for file upload and management.

List knowledge-base files

Retrieve all knowledge-base files attached to the assistant. Results are ordered by attachment creation time, newest first.

Endpoint

GET /api/assistants/{assistantId}/knowledge-base

Path parameters

Response fields

Attach a knowledge-base file

Attach an existing knowledge-base file from the account library to the assistant. The file must already exist and belong to the same account as the assistant. This operation is idempotent. Attaching a file that is already attached returns success without creating a duplicate.

Endpoint

POST /api/assistants/{assistantId}/knowledge-base

Path parameters

Body parameters

Response fields

Detach a knowledge-base file

Remove a knowledge-base file from an assistant. This only removes the attachment. The underlying file remains in the account library. Detaching a non-existent attachment still returns success.

Endpoint

DELETE /api/assistants/{assistantId}/knowledge-base/{fileId}

Path parameters

Response fields

Telephony management

Manage inbound and outbound telephony for an assistant. These endpoints provision and configure LiveKit trunks, assign phone numbers, and start test calls.

List assigned phone numbers

Retrieve active, non-deleted phone numbers assigned to the assistant. Results include numbers that are unassigned or assigned to this assistant, sorted by phone number ascending.

Endpoint

GET /api/assistants/{assistantId}/telephony/phone-numbers

Path parameters

Query parameters

Response fields

Assign phone numbers (PATCH)

Assign phone numbers to the assistant. All existing assignments are removed first, then the supplied IDs are assigned. LiveKit routing is resynchronized for affected assistants.

Endpoint

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

Body parameters

Response fields

Enable or disable inbound calling

Toggle inbound calling for the assistant. Enabling requires at least one active, non-deleted phone number assigned to the assistant. Talkturo provisions or updates the LiveKit inbound trunk and dispatch rule when enabling, and removes them when disabling.

Endpoint

POST /api/assistants/{assistantId}/telephony/inbound

Body parameters

Response fields

Enable or disable outbound calling

Toggle outbound calling for the assistant. Enabling requires at least one active assigned phone number. Talkturo provisions or updates the LiveKit outbound trunk when enabling, and removes it when disabling.

Endpoint

POST /api/assistants/{assistantId}/telephony/outbound

Body parameters

Response fields

Update telephony settings

Configure phone number assignments, voicemail, compliance, and destination country in a single request. This endpoint handles LiveKit provisioning, voicemail detection, and compliance consent flows.

Endpoint

POST /api/assistants/{assistantId}/telephony/settings

Body parameters

Response fields

Start a test call

Initiate a test call using the assistant's telephony configuration. Requires sufficient account credits and outbound calling to be enabled.

Endpoint

POST /api/assistants/{assistantId}/telephony/test-call

Body parameters

Response fields

List phone numbers available for assignment

Retrieve phone numbers that are available for assignment to the assistant, including unassigned numbers and numbers already assigned to this assistant.

Endpoint

GET /api/assistants/{assistantId}/telephony/assign-phone-numbers

Path parameters

Query parameters

Response fields

List compliance templates

Retrieve compliance templates available for the assistant's telephony configuration.

Endpoint

GET /api/assistants/{assistantId}/telephony/compliance-templates

Path parameters

Response fields

Create or refresh a test link

Generate or refresh a test link for an assistant. The test link provides a URL that opens a browser-based test call with the assistant.

Endpoint

POST /api/assistants/{assistantId}/test-link

Path parameters

Response fields

CRM group assignment

Assign a CRM group to an assistant. The CRM group determines which contacts the assistant can access during calls. The group must belong to the same account as the assistant.

Endpoint

POST /api/assistants/{assistantId}/crm-group

Path parameters

Body parameters

Response fields

Webhook testing

Send a test webhook event to verify that the assistant's webhook configuration is working. The endpoint generates a synthetic call.ended event and queues it for delivery. It does not make a real call or synchronously invoke the webhook.

Endpoint

POST /api/assistants/{assistantId}/webhooks/test

Path parameters

Response fields

Prompt version history

Track and restore previous versions of an assistant's system prompt. Each time the prompt changes, Talkturo saves a versioned snapshot. Use these endpoints to browse the history, save a new version, restore an old prompt, or delete a version you no longer need.

All prompt-version endpoints use withApiAuth and support both API key and session cookie authentication. API-key requests use the account bound to the key. Session-token requests require accountSlug in the query string. Cookie-session requests require teamId or accountSlug in the query string or request body.

List prompt versions

Retrieve a paginated list of prompt versions, newest first.

Endpoint

GET /api/assistants/{assistantId}/prompt-versions

Path parameters

Query parameters

Response fields

Save a prompt version

Save the assistant's current system prompt as a new version. If the prompt has not changed since the last version, the endpoint returns unchanged: true and does not create a new version.

Endpoint

POST /api/assistants/{assistantId}/prompt-versions

Body parameters

Response fields

Delete a prompt version

Delete a prompt version by ID. The currently active version cannot be deleted.

Endpoint

DELETE /api/assistants/{assistantId}/prompt-versions/{versionId}

Path parameters

Response fields

Restore a prompt version

Restore a previous prompt version by copying its system_prompt onto the assistant. This updates the assistant's current prompt and version pointer but does not create a new version.

Endpoint

POST /api/assistants/{assistantId}/prompt-versions/{versionId}/restore

Path parameters

Response fields

Workflow tool attachment

Attach a published TurboFlow workflow to an assistant as a callable tool. The assistant can invoke the workflow during calls. The workflow's name, description, and parameters are resolved from the published flow version at call time.

Endpoint

POST /api/assistants/{assistantId}/tools/workflow

Path parameters

Body parameters

Response fields

Detach a workflow tool

Remove a workflow tool from an assistant by configuration ID.

Endpoint

DELETE /api/assistants/{assistantId}/tools/workflow?config_id={configId}

Query parameters

Response fields

Common response shape

All mutation endpoints on this page return a top-level success field. Depending on the operation, the response also includes either an assistant object or a message.

Success fields

Endpoint summary