Delete AI Agent

curl --request DELETE \
  --url https://api.example.com/v3/ai-agents/{agent_id}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v3/ai-agents/{agent_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v3/ai-agents/{agent_id}"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v3/ai-agents/{agent_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Agent deactivated successfully",
  "data": {
    "ai_agent_id": "3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42",
    "agent_name": "Customer Support Agent",
    "agent_status": "ACTIVE",
    "language_code": "en-US",
    "llm": {
      "llm_id": "9d259647-d5ec-423d-96a9-2750980e8ecb",
      "llm_type": "simple",
      "model_provider": "openai",
      "model_name": "gpt-4o-mini",
      "model_display_name": "GPT-4o mini",
      "model_temperature": 0.1,
      "max_tokens": 4096,
      "system_prompt": "You are a helpful customer support assistant."
    },
    "stt": {
      "provider_id": "6a5c45808d2d94e9d0e255d3",
      "provider": "deepgram",
      "model_id": "af97a5f7-0f10-4eb3-a915-f7fe95a050f8",
      "model": "nova-3-general"
    },
    "tts": {
      "provider_id": "6a5c079f814b8ed08b15172b",
      "provider": "elevenlabs",
      "voice_id": "IKne3meq5aSn9XLyUdCD",
      "voice_name": "Charlie",
      "model_name": "eleven_flash_v2_5",
      "voice_temperature": 1
    },
    "speech_speed": 0.9,
    "vad_activation_threshold": 0.4,
    "knowledge_base_id": "kb-123456",
    "enable_user_interruptions": true,
    "minimum_speech_duration_for_interruptions": 0.5,
    "minimum_words_before_interruption": 2,
    "interruption_mode": "vad",
    "ambient_sound": "office",
    "ambient_sound_volume": 1,
    "webhook_url": "https://api.example.com/webhooks/call-events",
    "end_call_after_silence_seconds": 20,
    "max_call_duration_seconds": 600,
    "welcome_message": "Hello! Thanks for calling. How can I help you today?",
    "end_call_instruction": "End the call politely once the issue is resolved.",
    "amd_voicemail_message": "Sorry we missed you. Please call us back.",
    "voicemail_detection_timeout_seconds": 5,
    "agent_ended_call_delay_seconds": 1,
    "welcome_message_delay_in_seconds": 0.5,
    "enable_amd": true,
    "silence_reminder_enabled": true,
    "silence_reminder_duration_seconds": 15,
    "max_number_of_silence_reminders": 3,
    "interval_between_silence_reminders_seconds": 10,
    "enable_noise_cancellation": true,
    "dynamic_data_config": [
      {
        "name": "customer_data",
        "url": "https://api.example.com/customer-data",
        "method": "GET",
        "timeout": 2000,
        "cache": true,
        "response_data": [
          {
            "name": "customer_name",
            "data": "$.customer.name",
            "context": "Customer's full name for personalization"
          }
        ]
      }
    ],
    "post_call_analysis": [
      {
        "type": "string",
        "name": "call_summary",
        "description": "A brief summary of the call and key points.",
        "examples": [
          "Customer asked about billing; issue resolved."
        ]
      }
    ],
    "pronunciations": [
      {
        "id": "r1",
        "term": "API",
        "replacement": "ay pee eye"
      }
    ],
    "organization_id": "org_7f3a9c",
    "agent_owner_id": "usr_12ab34",
    "created_by_user_id": "usr_12ab34",
    "created_at": "2026-10-15T09:30:12.481Z",
    "modified_at": "2026-10-15T10:02:47.115Z",
    "current_version": 2,
    "operation_type": "DEACTIVATE"
  }
}

AI Agents v3

Delete AI Agent

Delete an agent. This is a soft delete, and the response carries the agent.

The v2 equivalent, DELETE /v2/ai-agents/{agent_id}, is deprecated and stops working on November 30, 2026. This is the v3 endpoint. Migrate from v2 to v3 before that date.

Soft delete

The agent record is kept and its status moves to INACTIVE. After the delete:

Get AI Agent returns 404 for the agent.
List AI Agents returns it only when you filter on agent_status=INACTIVE.

The caller must be in the agent’s scope. A workspace-scoped key must match the agent’s workspace; otherwise the key’s organization must match the agent’s organization.

Response envelope

Every v3 response uses the same envelope:

Field	Meaning
`status`	`success` or `error`. Always lowercase.
`message`	A human-readable summary.
`data`	The result. Absent on errors.
`error_details`	A map from field path to message. Present only on some errors.

Fields with no value are omitted rather than returned as null.

{
  "status": "success",
  "message": "Agent deactivated successfully",
  "data": {
    "ai_agent_id": "3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42",
    "agent_name": "Customer Support Agent",
    "agent_status": "ACTIVE",
    "operation_type": "DEACTIVATE"
  }
}

data is the agent as it was before deactivation, so agent_status still reads ACTIVE.

Status codes

Code	When
`200`	Deleted.
`403`	The agent belongs to another organization or workspace.
`404`	No such agent.

DELETE

ai-agents

{agent_id}

Delete AI Agent

curl --request DELETE \
  --url https://api.example.com/v3/ai-agents/{agent_id}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v3/ai-agents/{agent_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v3/ai-agents/{agent_id}"

	req, _ := http.NewRequest("DELETE", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v3/ai-agents/{agent_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Agent deactivated successfully",
  "data": {
    "ai_agent_id": "3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42",
    "agent_name": "Customer Support Agent",
    "agent_status": "ACTIVE",
    "language_code": "en-US",
    "llm": {
      "llm_id": "9d259647-d5ec-423d-96a9-2750980e8ecb",
      "llm_type": "simple",
      "model_provider": "openai",
      "model_name": "gpt-4o-mini",
      "model_display_name": "GPT-4o mini",
      "model_temperature": 0.1,
      "max_tokens": 4096,
      "system_prompt": "You are a helpful customer support assistant."
    },
    "stt": {
      "provider_id": "6a5c45808d2d94e9d0e255d3",
      "provider": "deepgram",
      "model_id": "af97a5f7-0f10-4eb3-a915-f7fe95a050f8",
      "model": "nova-3-general"
    },
    "tts": {
      "provider_id": "6a5c079f814b8ed08b15172b",
      "provider": "elevenlabs",
      "voice_id": "IKne3meq5aSn9XLyUdCD",
      "voice_name": "Charlie",
      "model_name": "eleven_flash_v2_5",
      "voice_temperature": 1
    },
    "speech_speed": 0.9,
    "vad_activation_threshold": 0.4,
    "knowledge_base_id": "kb-123456",
    "enable_user_interruptions": true,
    "minimum_speech_duration_for_interruptions": 0.5,
    "minimum_words_before_interruption": 2,
    "interruption_mode": "vad",
    "ambient_sound": "office",
    "ambient_sound_volume": 1,
    "webhook_url": "https://api.example.com/webhooks/call-events",
    "end_call_after_silence_seconds": 20,
    "max_call_duration_seconds": 600,
    "welcome_message": "Hello! Thanks for calling. How can I help you today?",
    "end_call_instruction": "End the call politely once the issue is resolved.",
    "amd_voicemail_message": "Sorry we missed you. Please call us back.",
    "voicemail_detection_timeout_seconds": 5,
    "agent_ended_call_delay_seconds": 1,
    "welcome_message_delay_in_seconds": 0.5,
    "enable_amd": true,
    "silence_reminder_enabled": true,
    "silence_reminder_duration_seconds": 15,
    "max_number_of_silence_reminders": 3,
    "interval_between_silence_reminders_seconds": 10,
    "enable_noise_cancellation": true,
    "dynamic_data_config": [
      {
        "name": "customer_data",
        "url": "https://api.example.com/customer-data",
        "method": "GET",
        "timeout": 2000,
        "cache": true,
        "response_data": [
          {
            "name": "customer_name",
            "data": "$.customer.name",
            "context": "Customer's full name for personalization"
          }
        ]
      }
    ],
    "post_call_analysis": [
      {
        "type": "string",
        "name": "call_summary",
        "description": "A brief summary of the call and key points.",
        "examples": [
          "Customer asked about billing; issue resolved."
        ]
      }
    ],
    "pronunciations": [
      {
        "id": "r1",
        "term": "API",
        "replacement": "ay pee eye"
      }
    ],
    "organization_id": "org_7f3a9c",
    "agent_owner_id": "usr_12ab34",
    "created_by_user_id": "usr_12ab34",
    "created_at": "2026-10-15T09:30:12.481Z",
    "modified_at": "2026-10-15T10:02:47.115Z",
    "current_version": 2,
    "operation_type": "DEACTIVATE"
  }
}

Path Parameters

agent_id

string

required

Unique identifier of the AI agent (ai_agent_id).

Response

Agent deleted

Standard v3 envelope. error_details is present only on failures; null fields are omitted.

status

enum<string>

Outcome of the request: success or error, in lowercase.

Available options:

success,

error

message

string

Human-readable message about the result.

data

AIAgentV3Response · object

The agent. Omitted on errors.

Show child attributes

error_details

Error Details · object | null

Field path to message, for validation failures. Omitted when there are none.

Show child attributes

API Reference

AI Agents v3

AI Agents v2

LLM Models

Speech Providers

Built-in Tools

Custom Tools

Calls

Call Recording

Post-call Analysis

Phone Numbers

Knowledge Bases

Prompt Generation

Public Sharing

Webhook Subscriptions

API Keys

Delete AI Agent

Soft delete

Response envelope

Status codes

Path Parameters

Response