> ## Documentation Index
> Fetch the complete documentation index at: https://boltcall.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Create, configure, and manage your AI voice agents via the Boltcall API.

Agents are the AI voice personas that answer calls, engage leads, and book appointments on behalf of your business. Each agent has a voice, a greeting, and an optional system prompt that shapes its behavior.

## List agents

<ParamField query="page" type="integer">
  Page number. Default: `1`.
</ParamField>

<ParamField query="limit" type="integer">
  Number of results per page. Default: `20`, max: `100`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.boltcall.org/v1/agents \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.boltcall.org/v1/agents?page=1&limit=20', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  });
  const { data, meta } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.boltcall.org/v1/agents',
      params={'page': 1, 'limit': 20},
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
  )
  result = response.json()
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": [
    {
      "id": "agent_abc123",
      "name": "Front Desk Agent",
      "voice_id": "voice_sarah",
      "status": "active",
      "phone_number": "+1234567890",
      "created_at": "2025-01-15T08:30:00Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 3 }
}
```

***

## Create an agent

<ParamField body="name" type="string" required>
  Display name for the agent.
</ParamField>

<ParamField body="voice_id" type="string" required>
  The voice to use. See the Voice Library in your dashboard for available IDs.
</ParamField>

<ParamField body="greeting" type="string">
  Custom greeting the agent speaks when a call connects.
</ParamField>

<ParamField body="prompt" type="string">
  System prompt or persona instructions that guide the agent's behavior.
</ParamField>

<ParamField body="knowledge_base_id" type="string">
  ID of a knowledge base to link to this agent. See [Knowledge base](/dashboard/knowledge-base).
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.boltcall.org/v1/agents \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "After-Hours Agent",
      "voice_id": "voice_james",
      "greeting": "Thanks for calling! How can I help you today?",
      "prompt": "You are a friendly receptionist for a dental practice..."
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.boltcall.org/v1/agents', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'After-Hours Agent',
      voice_id: 'voice_james',
      greeting: 'Thanks for calling! How can I help you today?',
      prompt: 'You are a friendly receptionist for a dental practice...',
    }),
  });
  const agent = await response.json();
  ```

  ```python Python theme={null}
  import requests

  agent = requests.post(
      'https://api.boltcall.org/v1/agents',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'name': 'After-Hours Agent',
          'voice_id': 'voice_james',
          'greeting': 'Thanks for calling! How can I help you today?',
          'prompt': 'You are a friendly receptionist for a dental practice...',
      },
  ).json()
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "agent_def456",
  "name": "After-Hours Agent",
  "voice_id": "voice_james",
  "status": "active",
  "created_at": "2025-03-20T14:00:00Z"
}
```

***

## Update an agent

Updates one or more fields on an existing agent. Only the fields you include are changed.

**Path parameter**

<ParamField path="agent_id" type="string" required>
  The ID of the agent to update.
</ParamField>

**Body**

<ParamField body="name" type="string">
  Updated display name.
</ParamField>

<ParamField body="greeting" type="string">
  Updated greeting message.
</ParamField>

<ParamField body="status" type="string">
  Set to `"active"` or `"paused"`. A paused agent will not answer calls.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://api.boltcall.org/v1/agents/agent_def456 \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "After-Hours Agent v2",
      "status": "active"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.boltcall.org/v1/agents/agent_def456', {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ name: 'After-Hours Agent v2', status: 'active' }),
  });
  const updated = await response.json();
  ```

  ```python Python theme={null}
  import requests

  updated = requests.patch(
      'https://api.boltcall.org/v1/agents/agent_def456',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={'name': 'After-Hours Agent v2', 'status': 'active'},
  ).json()
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "agent_def456",
  "name": "After-Hours Agent v2",
  "status": "active",
  "updated_at": "2025-03-21T10:00:00Z"
}
```

***

## Delete an agent

Permanently deletes an agent. This cannot be undone.

**Path parameter**

<ParamField path="agent_id" type="string" required>
  The ID of the agent to delete.
</ParamField>

<Warning>
  Deleting an agent is irreversible. Any phone numbers assigned to the agent will be unlinked, and call history is retained but the agent can no longer be restored.
</Warning>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.boltcall.org/v1/agents/agent_def456 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  await fetch('https://api.boltcall.org/v1/agents/agent_def456', {
    method: 'DELETE',
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  });
  ```

  ```python Python theme={null}
  import requests

  requests.delete(
      'https://api.boltcall.org/v1/agents/agent_def456',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
  )
  ```
</CodeGroup>

```json Response theme={null}
{ "deleted": true }
```