Get, update, list, and delete Conversational AI agents

Once you have created an agent, you can retrieve its configuration, apply partial updates, list all agents in your account, or delete agents you no longer need.

Get an agent

Retrieve the full configuration object for a single agent.

GET https://api.xuna.ai/v1/convai/agents/{agent_id}

string

required

The ID of the agent to retrieve.

agent = client.conversational_ai.agents.get(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)
print(agent)

const agent = await client.conversationalAi.agents.get(
    "agent_7101k5zvyjhmfg983brhmhkd98n6"
);
console.log(agent);

curl https://api.xuna.ai/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6 \
  -H "x-api-key: YOUR_API_KEY"

The response contains the full conversation_config object, metadata, and any knowledge base or tool attachments.

Update an agent

Apply a partial update to an existing agent. Only the fields you include in the request body are changed.

PATCH https://api.xuna.ai/v1/convai/agents/{agent_id}

string

required

The ID of the agent to update.

object

Partial conversation config. Provide only the fields you want to change.

client.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    conversation_config={
        "agent": {
            "first_message": "Hello! How can I assist you today?",
        }
    },
)

await client.conversationalAi.agents.update(
    "agent_7101k5zvyjhmfg983brhmhkd98n6",
    {
        conversationConfig: {
            agent: {
                firstMessage: "Hello! How can I assist you today?",
            },
        },
    }
);

curl -X PATCH https://api.xuna.ai/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_config": {
      "agent": {
        "first_message": "Hello! How can I assist you today?"
      }
    }
  }'

Use PATCH to iterate quickly on your agent’s prompt and voice without recreating it. All existing settings outside the updated fields are preserved.

List agents

Return all agents in your account.

GET https://api.xuna.ai/v1/convai/agents

result = client.conversational_ai.agents.list()
for agent in result.agents:
    print(agent.agent_id, agent.name)

const result = await client.conversationalAi.agents.list();
for (const agent of result.agents) {
    console.log(agent.agentId, agent.name);
}

curl https://api.xuna.ai/v1/convai/agents \
  -H "x-api-key: YOUR_API_KEY"

Response:

object[]

required

Array of agent summary objects. Each entry includes agent_id, name, tags, and creation timestamps.

boolean

required

Indicates whether additional pages of results are available.

Delete an agent

Permanently delete an agent. This action cannot be undone.

DELETE https://api.xuna.ai/v1/convai/agents/{agent_id}

string

required

The ID of the agent to delete.

client.conversational_ai.agents.delete(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
)
print("Agent deleted.")

await client.conversationalAi.agents.delete(
    "agent_7101k5zvyjhmfg983brhmhkd98n6"
);
console.log("Agent deleted.");

curl -X DELETE https://api.xuna.ai/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6 \
  -H "x-api-key: YOUR_API_KEY"

Deleting an agent also removes its association with any phone numbers. Assign a different agent to those numbers before deleting if you want inbound calls to continue.

Overview

Agents

Telephony

Get, update, list, and delete Conversational AI agents

Get an agent

Update an agent

List agents

Delete an agent

​Get an agent

​Update an agent

​List agents

​Delete an agent

Get an agent

Update an agent

List agents

Delete an agent