CallAgent

English

Română

English

Română

Appearance

Assistants ​

14 endpoints. Every path below is relative to the API base URL and already includes the /api/v1 prefix — see conventions for authentication, pagination, errors and idempotency.

Endpoint
GET/assistantsLists the organization's assistants, newest first, with optional search, status and published-only filters
POST/assistantsCreates a draft assistant with its tool, knowledge-base and structured-output attachments and returns it
GET/assistants/{assistant}Returns one assistant with its attached tools and knowledge bases loaded
PUT/assistants/{assistant}Updates the assistant draft with PATCH semantics and re-syncs its tool and knowledge attachments
DELETE/assistants/{assistant}Soft-deletes an assistant so phone numbers, campaigns and past calls keep resolving their history
POST/assistants/{assistant}/duplicateCopies an assistant into a new draft that inherits its tool version pins verbatim
GET/assistants/{assistant}/previewReturns the exact resolved configuration snapshot the Voice Gateway would receive for this draft
POST/assistants/{assistant}/publishFreezes the current draft into a new immutable assistant version and puts it on live traffic
POST/assistants/{assistant}/render-promptRenders the assistant's system prompt and first message against a supplied variable context
POST/assistants/{assistant}/unpublishTakes the assistant off live traffic and back to draft without destroying its version history
GET/assistants/{assistant}/validateRuns the publish-time checks against the draft without publishing and returns the error list
GET/assistants/{assistant}/versionsLists the assistant's published versions with their tool and knowledge-base references
GET/assistants/{assistant}/versions/{version}Returns one published assistant version including its full frozen configuration snapshot
POST/assistants/{assistant}/versions/{version}/restoreCopies an old version's snapshot back onto the draft and, by default, republishes it as a new version

Endpoints ​

Lists the organization's assistants, newest first, with optional search, status and published-only filters ​

GET/assistants
  • Requires assistant.read.
  • Query params: search, status, published_only, limit (default 25, hard-capped at 100).

Query parameters

NameTypeRequiredNotes
published_onlyboolean—default false
limitinteger—default 25
bash
curl -X GET "$CALLAGENT_API_URL/assistants?published_only=false&limit=25" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"
js
const response = await fetch(`${process.env.CALLAGENT_API_URL}/assistants?published_only=false&limit=25`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();
php
<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/assistants?published_only=false&limit=25');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];
python
import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/assistants?published_only=false&limit=25",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

StatusBody
200Paginated set of AssistantResource

Errors

StatusWhen it happens
403The key lacks assistant.read

Example response, generated from the schema:

json
{
  "data": [
    {
      "id": "01JQ0000000000000000000000",
      "object": "string",
      "name": "Support Line",
      "description": "string",
      "status": "string",
      "is_published": true,
      "version": 1,
      "current_version_id": "01JQ0000000000000000000000",
      "published_version_id": "01JQ0000000000000000000000",
      "has_unpublished_changes": true,
      "mode": "string",
      "language": "string",
      "additional_languages": {},
      "first_message": "string",
      "first_message_mode": "string",
      "system_prompt": "string",
      "silence_timeout_seconds": 30,
      "max_duration_seconds": 30,
      "template_strictness": "string",
      "transcriber": {},
      "model": {},
      "voice": {},
      "speech_to_speech_model": {},
      "start_speaking_plan": {},
      "stop_speaking_plan": {},
      "artifact_plan": {},
      "analysis_plan": {},
      "observability_plan": {},
      "message_plan": {},
      "keypad_input_plan": {},
      "recording_consent_plan": {},
      "voicemail_detection_plan": {},
      "transfer_plan": {},
      "compliance_plan": {},
      "background_sound": {},
      "background_speech_denoising": {},
      "end_call_phrases": {},
      "idle_messages": {},
      "background_messages": {},
      "pronunciations": {},
      "custom_keywords": {},
      "voice_formatting": {},
      "server": {},
      "hooks": {},
      "fallbacks": {},
      "variables": {},
      "variable_values": {},
      "knowledge_only": true,
      "knowledge_only_plan": {},
      "metadata": {},
      "tools": [],
      "knowledge_bases": [],
      "created_at": "2026-01-01T12:00:00+00:00",
      "updated_at": "2026-01-01T12:00:00+00:00",
      "last_published_at": "2026-01-01T12:00:00+00:00"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {}
    ],
    "path": "string",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}

Creates a draft assistant with its tool, knowledge-base and structured-output attachments and returns it ​

POST/assistants
  • Requires assistant.write.
  • Always created as a draft (is_published false). A tools[].tool_version_id that belongs to another tool escapes validation and 500s in the service.

Request body

FieldTypeRequiredNotes
namestringyesmax 255 chars
descriptionstring | null—max 255 chars
modepipeline · realtime | null—
languagestring | null—max 16 chars
additional_languagesstring[] | null—
first_messagestring | null—max 5000 chars
first_message_modeassistant_speaks_first · assistant_speaks_first_with_model_generated_message · assistant_waits_for_user | null—
system_promptstring | null—max 100000 chars
template_strictnesslenient · warn · strict | null—
silence_timeout_secondsinteger | null—min 1. max 600
max_duration_secondsinteger | null—min 10. max 3600
transcriberobject—
transcriber.providerstring | null—max 48 chars
modelobject—
model.providerstring | null—max 48 chars
model.modelstring | null—max 96 chars
voiceobject—
voice.providerstring | null—max 48 chars
speech_to_speech_modelstring[] | null—
start_speaking_planstring[] | null—
stop_speaking_planstring[] | null—
artifact_planstring[] | null—
analysis_planstring[] | null—
observability_planstring[] | null—
message_planstring[] | null—
keypad_input_planstring[] | null—
recording_consent_planstring[] | null—
voicemail_detection_planstring[] | null—
transfer_planstring[] | null—
compliance_planstring[] | null—
background_soundstring[] | null—
background_speech_denoisingstring[] | null—
serverobject—
server.urlstring | null—uri. max 2048 chars
hooksstring[] | null—
fallbacksstring[] | null—
end_call_phrasesstring[] | null—
idle_messagesstring[] | null—
background_messagesstring[] | null—
pronunciationsstring[] | null—
custom_keywordsstring[] | null—
voice_formattingstring[] | null—
variablesobject[] | null—
variable_valuesstring[] | null—
knowledge_onlyboolean | null—
knowledge_only_planstring[] | null—
metadatastring[] | null—
toolsobject[] | null—Tenancy: exists is scoped by hand because the global Eloquent scope does not apply to the validator's own query.
tool_idsstring[] | null—
knowledge_base_idsstring[] | null—
structured_output_idsstring[] | null—
bash
curl -X POST "$CALLAGENT_API_URL/assistants" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "name": "Support Line",
       "mode": "pipeline",
       "first_message_mode": "assistant_speaks_first",
       "template_strictness": "lenient",
       "silence_timeout_seconds": 30,
       "max_duration_seconds": 30,
       "transcriber": {
         "provider": "string"
       }
     }'
js
const response = await fetch(`${process.env.CALLAGENT_API_URL}/assistants`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Support Line",
    "mode": "pipeline",
    "first_message_mode": "assistant_speaks_first",
    "template_strictness": "lenient",
    "silence_timeout_seconds": 30,
    "max_duration_seconds": 30,
    "transcriber": {
      "provider": "string"
    }
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();
php
<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/assistants');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Support Line',
    'mode' => 'pipeline',
    'first_message_mode' => 'assistant_speaks_first',
    'template_strictness' => 'lenient',
    'silence_timeout_seconds' => 30,
    'max_duration_seconds' => 30,
    'transcriber' => [
        'provider' => 'string',
    ],
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];
python
import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/assistants",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "name": "Support Line",
      "mode": "pipeline",
      "first_message_mode": "assistant_speaks_first",
      "template_strictness": "lenient",
      "silence_timeout_seconds": 30,
      "max_duration_seconds": 30,
      "transcriber": {
        "provider": "string"
      }
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

StatusBody
201AssistantResource

Errors

StatusWhen it happens
403The key lacks assistant.write
422Validation failed, or a referenced id is not in this organization

Example response, generated from the schema:

json
{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "description": "string",
    "status": "string",
    "is_published": true,
    "version": 1,
    "current_version_id": "01JQ0000000000000000000000",
    "published_version_id": "01JQ0000000000000000000000",
    "has_unpublished_changes": true,
    "mode": "string",
    "language": "string",
    "additional_languages": {},
    "first_message": "string",
    "first_message_mode": "string",
    "system_prompt": "string",
    "silence_timeout_seconds": 30,
    "max_duration_seconds": 30,
    "template_strictness": "string",
    "transcriber": {},
    "model": {},
    "voice": {},
    "speech_to_speech_model": {},
    "start_speaking_plan": {},
    "stop_speaking_plan": {},
    "artifact_plan": {},
    "analysis_plan": {},
    "observability_plan": {},
    "message_plan": {},
    "keypad_input_plan": {},
    "recording_consent_plan": {},
    "voicemail_detection_plan": {},
    "transfer_plan": {},
    "compliance_plan": {},
    "background_sound": {},
    "background_speech_denoising": {},
    "end_call_phrases": {},
    "idle_messages": {},
    "background_messages": {},
    "pronunciations": {},
    "custom_keywords": {},
    "voice_formatting": {},
    "server": {},
    "hooks": {},
    "fallbacks": {},
    "variables": {},
    "variable_values": {},
    "knowledge_only": true,
    "knowledge_only_plan": {},
    "metadata": {},
    "tools": [
      {}
    ],
    "knowledge_bases": [
      {}
    ],
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00",
    "last_published_at": "2026-01-01T12:00:00+00:00"
  }
}

Returns one assistant with its attached tools and knowledge bases loaded ​

GET/assistants/{assistant}
  • Requires assistant.read.

Path parameters

NameTypeRequiredNotes
assistantstringyesThe assistant ID
bash
curl -X GET "$CALLAGENT_API_URL/assistants/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"
js
const response = await fetch(`${process.env.CALLAGENT_API_URL}/assistants/01JQ0000000000000000000000`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();
php
<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/assistants/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];
python
import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/assistants/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

StatusBody
200AssistantResource

Errors

StatusWhen it happens
403The key lacks assistant.read
404No such assistant in this organization

Example response, generated from the schema:

json
{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "description": "string",
    "status": "string",
    "is_published": true,
    "version": 1,
    "current_version_id": "01JQ0000000000000000000000",
    "published_version_id": "01JQ0000000000000000000000",
    "has_unpublished_changes": true,
    "mode": "string",
    "language": "string",
    "additional_languages": {},
    "first_message": "string",
    "first_message_mode": "string",
    "system_prompt": "string",
    "silence_timeout_seconds": 30,
    "max_duration_seconds": 30,
    "template_strictness": "string",
    "transcriber": {},
    "model": {},
    "voice": {},
    "speech_to_speech_model": {},
    "start_speaking_plan": {},
    "stop_speaking_plan": {},
    "artifact_plan": {},
    "analysis_plan": {},
    "observability_plan": {},
    "message_plan": {},
    "keypad_input_plan": {},
    "recording_consent_plan": {},
    "voicemail_detection_plan": {},
    "transfer_plan": {},
    "compliance_plan": {},
    "background_sound": {},
    "background_speech_denoising": {},
    "end_call_phrases": {},
    "idle_messages": {},
    "background_messages": {},
    "pronunciations": {},
    "custom_keywords": {},
    "voice_formatting": {},
    "server": {},
    "hooks": {},
    "fallbacks": {},
    "variables": {},
    "variable_values": {},
    "knowledge_only": true,
    "knowledge_only_plan": {},
    "metadata": {},
    "tools": [
      {}
    ],
    "knowledge_bases": [
      {}
    ],
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00",
    "last_published_at": "2026-01-01T12:00:00+00:00"
  }
}

Updates the assistant draft with PATCH semantics and re-syncs its tool and knowledge attachments ​

PUT/assistants/{assistant}
  • Requires assistant.write.
  • PATCH is accepted on the same path, with the same body.
  • An absent field is left alone, not blanked. Sending tools / knowledge_base_ids replaces the whole attachment set.

Path parameters

NameTypeRequiredNotes
assistantstringyesThe assistant ID

Request body

FieldTypeRequiredNotes
namestring—max 255 chars
descriptionstring | null—max 255 chars
modepipeline · realtime | null—
languagestring | null—max 16 chars
additional_languagesstring[] | null—
first_messagestring | null—max 5000 chars
first_message_modeassistant_speaks_first · assistant_speaks_first_with_model_generated_message · assistant_waits_for_user | null—
system_promptstring | null—max 100000 chars
template_strictnesslenient · warn · strict | null—
silence_timeout_secondsinteger | null—min 1. max 600
max_duration_secondsinteger | null—min 10. max 3600
transcriberobject—
transcriber.providerstring | null—max 48 chars
modelobject—
model.providerstring | null—max 48 chars
model.modelstring | null—max 96 chars
voiceobject—
voice.providerstring | null—max 48 chars
speech_to_speech_modelstring[] | null—
start_speaking_planstring[] | null—
stop_speaking_planstring[] | null—
artifact_planstring[] | null—
analysis_planstring[] | null—
observability_planstring[] | null—
message_planstring[] | null—
keypad_input_planstring[] | null—
recording_consent_planstring[] | null—
voicemail_detection_planstring[] | null—
transfer_planstring[] | null—
compliance_planstring[] | null—
background_soundstring[] | null—
background_speech_denoisingstring[] | null—
serverobject—
server.urlstring | null—uri. max 2048 chars
hooksstring[] | null—
fallbacksstring[] | null—
end_call_phrasesstring[] | null—
idle_messagesstring[] | null—
background_messagesstring[] | null—
pronunciationsstring[] | null—
custom_keywordsstring[] | null—
voice_formattingstring[] | null—
variablesobject[] | null—
variable_valuesstring[] | null—
knowledge_onlyboolean | null—
knowledge_only_planstring[] | null—
metadatastring[] | null—
toolsobject[] | null—Tenancy: exists is scoped by hand because the global Eloquent scope does not apply to the validator's own query.
tool_idsstring[] | null—
knowledge_base_idsstring[] | null—
structured_output_idsstring[] | null—
bash
curl -X PUT "$CALLAGENT_API_URL/assistants/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "name": "Support Line",
       "mode": "pipeline",
       "first_message_mode": "assistant_speaks_first",
       "template_strictness": "lenient",
       "silence_timeout_seconds": 30,
       "max_duration_seconds": 30,
       "transcriber": {
         "provider": "string"
       }
     }'
js
const response = await fetch(`${process.env.CALLAGENT_API_URL}/assistants/01JQ0000000000000000000000`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Support Line",
    "mode": "pipeline",
    "first_message_mode": "assistant_speaks_first",
    "template_strictness": "lenient",
    "silence_timeout_seconds": 30,
    "max_duration_seconds": 30,
    "transcriber": {
      "provider": "string"
    }
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();
php
<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/assistants/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Support Line',
    'mode' => 'pipeline',
    'first_message_mode' => 'assistant_speaks_first',
    'template_strictness' => 'lenient',
    'silence_timeout_seconds' => 30,
    'max_duration_seconds' => 30,
    'transcriber' => [
        'provider' => 'string',
    ],
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];
python
import os, requests

response = requests.put(
    f"{os.environ['CALLAGENT_API_URL']}/assistants/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "name": "Support Line",
      "mode": "pipeline",
      "first_message_mode": "assistant_speaks_first",
      "template_strictness": "lenient",
      "silence_timeout_seconds": 30,
      "max_duration_seconds": 30,
      "transcriber": {
        "provider": "string"
      }
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

StatusBody
200AssistantResource

Errors

StatusWhen it happens
403The key lacks assistant.write
404No such assistant in this organization
422Validation failed, or a referenced id is not in this organization

Example response, generated from the schema:

json
{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "description": "string",
    "status": "string",
    "is_published": true,
    "version": 1,
    "current_version_id": "01JQ0000000000000000000000",
    "published_version_id": "01JQ0000000000000000000000",
    "has_unpublished_changes": true,
    "mode": "string",
    "language": "string",
    "additional_languages": {},
    "first_message": "string",
    "first_message_mode": "string",
    "system_prompt": "string",
    "silence_timeout_seconds": 30,
    "max_duration_seconds": 30,
    "template_strictness": "string",
    "transcriber": {},
    "model": {},
    "voice": {},
    "speech_to_speech_model": {},
    "start_speaking_plan": {},
    "stop_speaking_plan": {},
    "artifact_plan": {},
    "analysis_plan": {},
    "observability_plan": {},
    "message_plan": {},
    "keypad_input_plan": {},
    "recording_consent_plan": {},
    "voicemail_detection_plan": {},
    "transfer_plan": {},
    "compliance_plan": {},
    "background_sound": {},
    "background_speech_denoising": {},
    "end_call_phrases": {},
    "idle_messages": {},
    "background_messages": {},
    "pronunciations": {},
    "custom_keywords": {},
    "voice_formatting": {},
    "server": {},
    "hooks": {},
    "fallbacks": {},
    "variables": {},
    "variable_values": {},
    "knowledge_only": true,
    "knowledge_only_plan": {},
    "metadata": {},
    "tools": [
      {}
    ],
    "knowledge_bases": [
      {}
    ],
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00",
    "last_published_at": "2026-01-01T12:00:00+00:00"
  }
}

Soft-deletes an assistant so phone numbers, campaigns and past calls keep resolving their history ​

DELETE/assistants/{assistant}
  • Requires assistant.delete.
  • This response is not data-wrapped.
  • Body is a bare {"deleted": true, "id": "..."} — not the usual {"data": ...} envelope. The row is soft-deleted, not destroyed.

Path parameters

NameTypeRequiredNotes
assistantstringyesThe assistant ID
bash
curl -X DELETE "$CALLAGENT_API_URL/assistants/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"
js
const response = await fetch(`${process.env.CALLAGENT_API_URL}/assistants/01JQ0000000000000000000000`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();
php
<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/assistants/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];
python
import os, requests

response = requests.delete(
    f"{os.environ['CALLAGENT_API_URL']}/assistants/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

StatusBody
200Bare JSON object, not data-wrapped

Errors

StatusWhen it happens
403The key lacks assistant.delete
404No such assistant in this organization

Example response, generated from the schema:

json
{
  "deleted": true,
  "id": null
}

Copies an assistant into a new draft that inherits its tool version pins verbatim ​

POST/assistants/{assistant}/duplicate
  • Requires assistant.write.
  • Optional body field name; otherwise a unique "copy" name is generated. The copy starts at version 0, unpublished.

Path parameters

NameTypeRequiredNotes
assistantstringyesThe assistant ID
bash
curl -X POST "$CALLAGENT_API_URL/assistants/01JQ0000000000000000000000/duplicate" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"
js
const response = await fetch(`${process.env.CALLAGENT_API_URL}/assistants/01JQ0000000000000000000000/duplicate`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();
php
<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/assistants/01JQ0000000000000000000000/duplicate');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];
python
import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/assistants/01JQ0000000000000000000000/duplicate",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

StatusBody
201AssistantResource

Errors

StatusWhen it happens
403The key lacks assistant.write
404No such assistant in this organization

Example response, generated from the schema:

json
{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "description": "string",
    "status": "string",
    "is_published": true,
    "version": 1,
    "current_version_id": "01JQ0000000000000000000000",
    "published_version_id": "01JQ0000000000000000000000",
    "has_unpublished_changes": true,
    "mode": "string",
    "language": "string",
    "additional_languages": {},
    "first_message": "string",
    "first_message_mode": "string",
    "system_prompt": "string",
    "silence_timeout_seconds": 30,
    "max_duration_seconds": 30,
    "template_strictness": "string",
    "transcriber": {},
    "model": {},
    "voice": {},
    "speech_to_speech_model": {},
    "start_speaking_plan": {},
    "stop_speaking_plan": {},
    "artifact_plan": {},
    "analysis_plan": {},
    "observability_plan": {},
    "message_plan": {},
    "keypad_input_plan": {},
    "recording_consent_plan": {},
    "voicemail_detection_plan": {},
    "transfer_plan": {},
    "compliance_plan": {},
    "background_sound": {},
    "background_speech_denoising": {},
    "end_call_phrases": {},
    "idle_messages": {},
    "background_messages": {},
    "pronunciations": {},
    "custom_keywords": {},
    "voice_formatting": {},
    "server": {},
    "hooks": {},
    "fallbacks": {},
    "variables": {},
    "variable_values": {},
    "knowledge_only": true,
    "knowledge_only_plan": {},
    "metadata": {},
    "tools": [
      {}
    ],
    "knowledge_bases": [
      {}
    ],
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00",
    "last_published_at": "2026-01-01T12:00:00+00:00"
  }
}

Returns the exact resolved configuration snapshot the Voice Gateway would receive for this draft ​

GET/assistants/{assistant}/preview
  • Requires assistant.read.

Path parameters

NameTypeRequiredNotes
assistantstringyesThe assistant ID
bash
curl -X GET "$CALLAGENT_API_URL/assistants/01JQ0000000000000000000000/preview" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"
js
const response = await fetch(`${process.env.CALLAGENT_API_URL}/assistants/01JQ0000000000000000000000/preview`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();
php
<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/assistants/01JQ0000000000000000000000/preview');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];
python
import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/assistants/01JQ0000000000000000000000/preview",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

StatusBody
200data-wrapped object

Errors

StatusWhen it happens
403The key lacks assistant.read
404No such assistant in this organization

Example response, generated from the schema:

json
{
  "data": {
    "schema_version": 1,
    "assistant": {
      "id": null,
      "organization_id": "01JQ0000000000000000000000",
      "name": "Support Line",
      "description": "string",
      "mode": "string",
      "language": "string",
      "additional_languages": {},
      "first_message": "string",
      "first_message_mode": "string",
      "first_message_interruptions_enabled": true,
      "system_prompt": "string",
      "end_call_message": "string",
      "end_call_function_enabled": true,
      "silence_timeout_seconds": 30,
      "max_duration_seconds": 30,
      "template_strictness": "string"
    },
    "transcriber": {},
    "model": {},
    "voice": {},
    "speech_to_speech_model": {},
    "plans": {
      "start_speaking": {},
      "stop_speaking": {},
      "artifact": {},
      "analysis": {},
      "observability": {},
      "message": {},
      "keypad_input": {},
      "recording_consent": {},
      "voicemail_detection": {},
      "transfer": {},
      "compliance": {},
      "background_sound": {},
      "background_speech_denoising": {}
    },
    "conversation": {
      "end_call_phrases": {},
      "idle_messages": {},
      "background_messages": {},
      "pronunciations": {},
      "custom_keywords": {},
      "voice_formatting": {}
    },
    "server": {},
    "hooks": {},
    "fallbacks": {},
    "variables": {},
    "variable_values": {},
    "tools": [
      {}
    ],
    "mcp_servers": [
      {}
    ],
    "knowledge": {
      "bases": [],
      "knowledge_only": true,
      "knowledge_only_plan": {}
    },
    "structured_outputs": [
      {}
    ],
    "credentials": [
      {}
    ],
    "metadata": {}
  }
}

Freezes the current draft into a new immutable assistant version and puts it on live traffic ​

POST/assistants/{assistant}/publish
  • Requires assistant.publish.
  • Optional body fields label and change_summary. Publishing is a separate permission from editing.

Path parameters

NameTypeRequiredNotes
assistantstringyesThe assistant ID
bash
curl -X POST "$CALLAGENT_API_URL/assistants/01JQ0000000000000000000000/publish" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"
js
const response = await fetch(`${process.env.CALLAGENT_API_URL}/assistants/01JQ0000000000000000000000/publish`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();
php
<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/assistants/01JQ0000000000000000000000/publish');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];
python
import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/assistants/01JQ0000000000000000000000/publish",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

StatusBody
201AssistantVersionResource

Errors

StatusWhen it happens
403The key lacks assistant.publish
404No such assistant in this organization
422The draft fails publish-time validation

Example response, generated from the schema:

json
{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "assistant_id": "01JQ0000000000000000000000",
    "version": 1,
    "label": null,
    "change_summary": "string",
    "config_hash": "string",
    "config": {},
    "tool_refs": {},
    "knowledge_base_refs": {},
    "published_at": "2026-01-01T12:00:00+00:00"
  }
}

Renders the assistant's system prompt and first message against a supplied variable context ​

POST/assistants/{assistant}/render-prompt
  • Requires assistant.read.
  • Body accepts variables, call and customer objects, none required. A malformed template or (under strict mode) an undefined variable throws and surfaces as 500.

Path parameters

NameTypeRequiredNotes
assistantstringyesThe assistant ID
bash
curl -X POST "$CALLAGENT_API_URL/assistants/01JQ0000000000000000000000/render-prompt" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"
js
const response = await fetch(`${process.env.CALLAGENT_API_URL}/assistants/01JQ0000000000000000000000/render-prompt`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();
php
<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/assistants/01JQ0000000000000000000000/render-prompt');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];
python
import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/assistants/01JQ0000000000000000000000/render-prompt",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

StatusBody
200data-wrapped object

Errors

StatusWhen it happens
403The key lacks assistant.read
404No such assistant in this organization

Example response, generated from the schema:

json
{
  "data": {
    "system_prompt": "string",
    "first_message": "string",
    "missing": {}
  }
}

Takes the assistant off live traffic and back to draft without destroying its version history ​

POST/assistants/{assistant}/unpublish
  • Requires assistant.publish.

Path parameters

NameTypeRequiredNotes
assistantstringyesThe assistant ID
bash
curl -X POST "$CALLAGENT_API_URL/assistants/01JQ0000000000000000000000/unpublish" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"
js
const response = await fetch(`${process.env.CALLAGENT_API_URL}/assistants/01JQ0000000000000000000000/unpublish`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();
php
<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/assistants/01JQ0000000000000000000000/unpublish');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];
python
import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/assistants/01JQ0000000000000000000000/unpublish",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

StatusBody
200AssistantResource

Errors

StatusWhen it happens
403The key lacks assistant.publish
404No such assistant in this organization

Example response, generated from the schema:

json
{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "description": "string",
    "status": "string",
    "is_published": true,
    "version": 1,
    "current_version_id": "01JQ0000000000000000000000",
    "published_version_id": "01JQ0000000000000000000000",
    "has_unpublished_changes": true,
    "mode": "string",
    "language": "string",
    "additional_languages": {},
    "first_message": "string",
    "first_message_mode": "string",
    "system_prompt": "string",
    "silence_timeout_seconds": 30,
    "max_duration_seconds": 30,
    "template_strictness": "string",
    "transcriber": {},
    "model": {},
    "voice": {},
    "speech_to_speech_model": {},
    "start_speaking_plan": {},
    "stop_speaking_plan": {},
    "artifact_plan": {},
    "analysis_plan": {},
    "observability_plan": {},
    "message_plan": {},
    "keypad_input_plan": {},
    "recording_consent_plan": {},
    "voicemail_detection_plan": {},
    "transfer_plan": {},
    "compliance_plan": {},
    "background_sound": {},
    "background_speech_denoising": {},
    "end_call_phrases": {},
    "idle_messages": {},
    "background_messages": {},
    "pronunciations": {},
    "custom_keywords": {},
    "voice_formatting": {},
    "server": {},
    "hooks": {},
    "fallbacks": {},
    "variables": {},
    "variable_values": {},
    "knowledge_only": true,
    "knowledge_only_plan": {},
    "metadata": {},
    "tools": [
      {}
    ],
    "knowledge_bases": [
      {}
    ],
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00",
    "last_published_at": "2026-01-01T12:00:00+00:00"
  }
}

Runs the publish-time checks against the draft without publishing and returns the error list ​

GET/assistants/{assistant}/validate
  • Requires assistant.read.
  • A failing configuration still answers 200 with valid:false — it is a report, not an error.

Path parameters

NameTypeRequiredNotes
assistantstringyesThe assistant ID
bash
curl -X GET "$CALLAGENT_API_URL/assistants/01JQ0000000000000000000000/validate" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"
js
const response = await fetch(`${process.env.CALLAGENT_API_URL}/assistants/01JQ0000000000000000000000/validate`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();
php
<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/assistants/01JQ0000000000000000000000/validate');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];
python
import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/assistants/01JQ0000000000000000000000/validate",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

StatusBody
200data-wrapped object

Errors

StatusWhen it happens
403The key lacks assistant.read
404No such assistant in this organization

Example response, generated from the schema:

json
{
  "data": {
    "valid": true,
    "errors": [
      null
    ]
  }
}

Lists the assistant's published versions with their tool and knowledge-base references ​

GET/assistants/{assistant}/versions
  • Requires assistant.read.
  • Page size is fixed at 50 and cannot be changed. The full config snapshot is omitted from the listing; only the show route returns it.

Path parameters

NameTypeRequiredNotes
assistantstringyesThe assistant ID
bash
curl -X GET "$CALLAGENT_API_URL/assistants/01JQ0000000000000000000000/versions" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"
js
const response = await fetch(`${process.env.CALLAGENT_API_URL}/assistants/01JQ0000000000000000000000/versions`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();
php
<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/assistants/01JQ0000000000000000000000/versions');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];
python
import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/assistants/01JQ0000000000000000000000/versions",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

StatusBody
200Paginated set of AssistantVersionResource

Errors

StatusWhen it happens
403The key lacks assistant.read
404No such assistant in this organization

Example response, generated from the schema:

json
{
  "data": [
    {
      "id": "01JQ0000000000000000000000",
      "object": "string",
      "assistant_id": "01JQ0000000000000000000000",
      "version": 1,
      "label": null,
      "change_summary": "string",
      "config_hash": "string",
      "config": {},
      "tool_refs": {},
      "knowledge_base_refs": {},
      "published_at": "2026-01-01T12:00:00+00:00"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {}
    ],
    "path": "string",
    "per_page": 25,
    "to": 1,
    "total": 1
  }
}

Returns one published assistant version including its full frozen configuration snapshot ​

GET/assistants/{assistant}/versions/{version}
  • Requires assistant.read.

Path parameters

NameTypeRequiredNotes
assistantstringyesThe assistant ID
versionstringyesThe version ID
bash
curl -X GET "$CALLAGENT_API_URL/assistants/01JQ0000000000000000000000/versions/3" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"
js
const response = await fetch(`${process.env.CALLAGENT_API_URL}/assistants/01JQ0000000000000000000000/versions/3`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();
php
<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/assistants/01JQ0000000000000000000000/versions/3');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];
python
import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/assistants/01JQ0000000000000000000000/versions/3",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

StatusBody
200AssistantVersionResource

Errors

StatusWhen it happens
403The key lacks assistant.read
404No such assistant, or the version belongs to another assistant

Example response, generated from the schema:

json
{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "assistant_id": "01JQ0000000000000000000000",
    "version": 1,
    "label": null,
    "change_summary": "string",
    "config_hash": "string",
    "config": {},
    "tool_refs": {},
    "knowledge_base_refs": {},
    "published_at": "2026-01-01T12:00:00+00:00"
  }
}

Copies an old version's snapshot back onto the draft and, by default, republishes it as a new version ​

POST/assistants/{assistant}/versions/{version}/restore
  • Requires assistant.publish.
  • Optional body flag publish defaults to true. History is never rewritten: a new higher version is created. A republish validation failure escapes as 500, not 422.

Path parameters

NameTypeRequiredNotes
assistantstringyesThe assistant ID
versionstringyesThe version ID

Request body

FieldTypeRequiredNotes
publishboolean—default true
bash
curl -X POST "$CALLAGENT_API_URL/assistants/01JQ0000000000000000000000/versions/3/restore" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
       "publish": true
     }'
js
const response = await fetch(`${process.env.CALLAGENT_API_URL}/assistants/01JQ0000000000000000000000/versions/3/restore`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "publish": true
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();
php
<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/assistants/01JQ0000000000000000000000/versions/3/restore');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
    'publish' => true,
]),
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];
python
import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/assistants/01JQ0000000000000000000000/versions/3/restore",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    json={
      "publish": True
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

StatusBody
200AssistantResource

Errors

StatusWhen it happens
403The key lacks assistant.publish
404No such assistant, or the version belongs to another assistant

Example response, generated from the schema:

json
{
  "data": {
    "id": "01JQ0000000000000000000000",
    "object": "string",
    "name": "Support Line",
    "description": "string",
    "status": "string",
    "is_published": true,
    "version": 1,
    "current_version_id": "01JQ0000000000000000000000",
    "published_version_id": "01JQ0000000000000000000000",
    "has_unpublished_changes": true,
    "mode": "string",
    "language": "string",
    "additional_languages": {},
    "first_message": "string",
    "first_message_mode": "string",
    "system_prompt": "string",
    "silence_timeout_seconds": 30,
    "max_duration_seconds": 30,
    "template_strictness": "string",
    "transcriber": {},
    "model": {},
    "voice": {},
    "speech_to_speech_model": {},
    "start_speaking_plan": {},
    "stop_speaking_plan": {},
    "artifact_plan": {},
    "analysis_plan": {},
    "observability_plan": {},
    "message_plan": {},
    "keypad_input_plan": {},
    "recording_consent_plan": {},
    "voicemail_detection_plan": {},
    "transfer_plan": {},
    "compliance_plan": {},
    "background_sound": {},
    "background_speech_denoising": {},
    "end_call_phrases": {},
    "idle_messages": {},
    "background_messages": {},
    "pronunciations": {},
    "custom_keywords": {},
    "voice_formatting": {},
    "server": {},
    "hooks": {},
    "fallbacks": {},
    "variables": {},
    "variable_values": {},
    "knowledge_only": true,
    "knowledge_only_plan": {},
    "metadata": {},
    "tools": [
      {}
    ],
    "knowledge_bases": [
      {}
    ],
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00",
    "last_published_at": "2026-01-01T12:00:00+00:00"
  }
}

Documented against the code. Anything not yet implemented is labelled, never described as working.

CallAgent