Agents API

Agents are AI voice agents that handle conversations. Each agent has configurable voice, personality, tools, and knowledge bases.

Base URL: https://kalem.me/api/v1/agents

The Agent Object

{
  "id": 1,
  "name": "Sales Agent",
  "description": "Handles outbound sales calls",
  "is_active": true,
  "model": "gpt-realtime",
  "instructions": "You are a friendly sales representative...",
  "timezone": "America/New_York",
  "language": "en",
  "tools": [],
  "knowledge_bases": [],
  "numbers": [],
  "created_at": "2025-01-15T10:30:00+00:00",
  "updated_at": "2025-01-15T10:30:00+00:00"
}

List Agents

GET /api/v1/agents

Retrieve a paginated list of agents for your account.

Query Parameters

Parameter	Type	Description
`search`	string	Search agents by name
`status`	string	Filter by `active` or `inactive`
`include`	string	Comma-separated relationships: `tools`, `knowledgeBases`, `numbers`
`per_page`	integer	Results per page (default: 15, max: 100)

Example Request

curl -X GET "https://kalem.me/api/v1/agents?status=active&include=tools" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

const response = await fetch(
  'https://kalem.me/api/v1/agents?status=active&include=tools',
  { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN', 'Accept': 'application/json' } }
);
const data = await response.json();

import requests

response = requests.get(
    'https://kalem.me/api/v1/agents',
    params={'status': 'active', 'include': 'tools'},
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)
data = response.json()

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://kalem.me/api/v1/agents', [
        'status' => 'active',
        'include' => 'tools',
    ]);
$data = $response->json();

Create Agent

POST /api/v1/agents

Request Body Parameters

Parameter	Type	Required	Description
`name`	string	Required	Agent name (max 255 characters)
`description`	string	Optional	Agent description
`model`	string	Optional	AI model: `gpt-realtime`, `gpt-realtime-mini`, `gpt-realtime-1.5`
`instructions`	string	Optional	System instructions for the agent
`timezone`	string	Optional	Timezone (e.g., `America/New_York`)
`language`	string	Optional	Language code (e.g., `en`, `es`)

Example Request

curl -X POST https://kalem.me/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Agent",
    "model": "gpt-realtime",
    "instructions": "You are a friendly sales representative.",
    "language": "en"
  }'

const response = await fetch('https://kalem.me/api/v1/agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Sales Agent',
    model: 'gpt-realtime',
    instructions: 'You are a friendly sales representative.',
  }),
});
const data = await response.json();

import requests

response = requests.post(
    'https://kalem.me/api/v1/agents',
    json={
        'name': 'Sales Agent',
        'model': 'gpt-realtime',
        'instructions': 'You are a friendly sales representative.',
    },
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)
data = response.json()

$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://kalem.me/api/v1/agents', [
        'name' => 'Sales Agent',
        'model' => 'gpt-realtime',
        'instructions' => 'You are a friendly sales representative.',
    ]);
$data = $response->json();

Get Agent

GET /api/v1/agents/{id}

Retrieve a single agent by ID. Use the include query parameter to load relationships.

Example Request

curl -X GET "https://kalem.me/api/v1/agents/1?include=tools,knowledgeBases,numbers" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Update Agent

PUT /api/v1/agents/{id}

Update an agent. Only include the fields you want to change — partial updates are supported.

Example Request

curl -X PUT https://kalem.me/api/v1/agents/1 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Agent"}'

Delete Agent

DELETE /api/v1/agents/{id}

Soft-delete an agent. The agent will no longer be available for new calls.

Example Request

curl -X DELETE https://kalem.me/api/v1/agents/1 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Success Response

{
  "message": "Agent deleted successfully."
}