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

# Agents

> Create and manage AI voice agents for your organization.

## Overview

An agent defines the AI persona that handles calls and widget interactions. It holds the system prompt, voice configuration, and language settings. Create one agent per use case and reuse it across calls, widgets, and workflows.

All provider and model identifiers are aliased — you will never see internal provider names. Use the alias values returned by the API when updating agent settings.

**Required scopes:** `agents:read` (read operations), `agents:write` (create/update)

***

## `GET /v1/agents/voices`

Returns available voice providers and their supported models and voices. Use these values when updating an agent's voice configuration.

<CodeGroup>
  ```bash Bash theme={null}
  curl https://api.indigenius.ai/v1/agents/voices \
    -H "X-API-Key: $INDIGENIUS_API_KEY"
  ```

  ```javascript Node theme={null}
  const response = await fetch('https://api.indigenius.ai/v1/agents/voices', {
    headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
  });
  console.log(await response.json());
  ```

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

  response = requests.get(
      "https://api.indigenius.ai/v1/agents/voices",
      headers={"X-API-Key": os.environ["INDIGENIUS_API_KEY"]},
      timeout=30,
  )
  print(response.json())
  ```
</CodeGroup>

**`200 OK`**

```json theme={null}
{
  "success": true,
  "data": {
    "status": true,
    "message": "Voices fetched",
    "data": [
      {
        "name": "Voice Model 1",
        "provider": "indigenius_voice_model_1",
        "models": [
          "multilingual_v2",
          "multilingual_v1",
          "turbo_v2_5",
          "turbo_v2"
        ],
        "voices": [
          {
            "voice_id": "EXAVITQu4vr4xnSDxMaL",
            "name": "Sarah",
            "gender": "female"
          }
        ]
      },
      {
        "name": "Voice Model 2",
        "provider": "indigenius_voice_model_2",
        "models": ["indigenius_v1"],
        "voices": [
          {
            "voice_id": "Pidgin Female",
            "name": "Pidgin Female",
            "gender": "female"
          },
          { "voice_id": "Yoruba Male", "name": "Yoruba Male", "gender": "male" }
        ]
      }
    ]
  }
}
```

**Common errors:** `403` missing `agents:read` scope

***

## `GET /v1/agents`

Returns all agents available to your organization.

<CodeGroup>
  ```bash Bash theme={null}
  curl https://api.indigenius.ai/v1/agents \
    -H "X-API-Key: $INDIGENIUS_API_KEY"
  ```

  ```javascript Node theme={null}
  const response = await fetch('https://api.indigenius.ai/v1/agents', {
    headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
  });
  console.log(await response.json());
  ```

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

  response = requests.get(
      "https://api.indigenius.ai/v1/agents",
      headers={"X-API-Key": os.environ["INDIGENIUS_API_KEY"]},
      timeout=30,
  )
  print(response.json())
  ```
</CodeGroup>

**`200 OK`**

```json theme={null}
{
  "success": true,
  "data": {
    "status": true,
    "message": "Agents fetched",
    "data": [
      {
        "id": "665e4a34c65bb95f2f2d72e1",
        "name": "Sales Agent",
        "language": "English",
        "task_type": "lead_qualification"
      }
    ]
  }
}
```

**Common errors:** `403` missing `agents:read` scope · `404` key or org context not found

***

## `POST /v1/agents`

Creates a new agent.

<CodeGroup>
  ```bash Bash theme={null}
  curl -X POST https://api.indigenius.ai/v1/agents \
    -H "X-API-Key: $INDIGENIUS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Sales Agent",
      "company_name": "Acme Inc",
      "industry": "ecommerce",
      "language": "English",
      "voice": "female",
      "task_type": "lead_qualification"
    }'
  ```

  ```javascript Node theme={null}
  const response = await fetch('https://api.indigenius.ai/v1/agents', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.INDIGENIUS_API_KEY,
    },
    body: JSON.stringify({
      name: 'Sales Agent',
      company_name: 'Acme Inc',
      industry: 'ecommerce',
      language: 'English',
      voice: 'female',
      task_type: 'lead_qualification',
    }),
  });
  console.log(await response.json());
  ```

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

  response = requests.post(
      "https://api.indigenius.ai/v1/agents",
      headers={
          "X-API-Key": os.environ["INDIGENIUS_API_KEY"],
          "Content-Type": "application/json",
      },
      json={
          "name": "Sales Agent",
          "company_name": "Acme Inc",
          "industry": "ecommerce",
          "language": "English",
          "voice": "female",
          "task_type": "lead_qualification",
      },
      timeout=30,
  )
  print(response.json())
  ```
</CodeGroup>

**`201 Created`**

```json theme={null}
{
  "status": true,
  "message": "Agent created successfully"
}
```

**Common errors:** `400` validation error (missing required fields) · `403` missing `agents:write` scope

***

## `GET /v1/agents/{id}`

Returns a single agent by ID.

<CodeGroup>
  ```bash Bash theme={null}
  curl https://api.indigenius.ai/v1/agents/665e4a34c65bb95f2f2d72e1 \
    -H "X-API-Key: $INDIGENIUS_API_KEY"
  ```

  ```javascript Node theme={null}
  const agentId = '665e4a34c65bb95f2f2d72e1';
  const response = await fetch(`https://api.indigenius.ai/v1/agents/${agentId}`, {
    headers: { 'X-API-Key': process.env.INDIGENIUS_API_KEY },
  });
  console.log(await response.json());
  ```

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

  agent_id = "665e4a34c65bb95f2f2d72e1"
  response = requests.get(
      f"https://api.indigenius.ai/v1/agents/{agent_id}",
      headers={"X-API-Key": os.environ["INDIGENIUS_API_KEY"]},
      timeout=30,
  )
  print(response.json())
  ```
</CodeGroup>

**`200 OK`**

```json theme={null}
{
  "success": true,
  "data": {
    "status": true,
    "message": "Agent details fetched",
    "details": {
      "id": "665e4a34c65bb95f2f2d72e1",
      "name": "Sales Agent",
      "language": "English",
      "first_message": "Hello, how can I help you today?",
      "system_prompt": "You are a helpful sales agent.",
      "provider": "indigenius_reasoning_model_1",
      "model": "gpt4o",
      "voice_provider": "indigenius_voice_model_1",
      "voice_model": "multilingual_v2",
      "voice": "Sarah",
      "hipaa": false
    }
  }
}
```

**Common errors:** `403` missing `agents:read` scope · `404` agent not found

***

## `PATCH /v1/agents/{id}`

Updates an agent's settings (prompt, model, voice, etc.).

<Warning>
  This endpoint requires the agent `id` in **both** the URL path and the request
  body. Omitting it from the body will return a `400` validation error.
</Warning>

<CodeGroup>
  ```bash Bash theme={null}
  curl -X PATCH https://api.indigenius.ai/v1/agents/665e4a34c65bb95f2f2d72e1 \
    -H "X-API-Key: $INDIGENIUS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "id": "665e4a34c65bb95f2f2d72e1",
      "name": "Sales Agent",
      "language": "English",
      "first_message": "Hello, I can help with product questions.",
      "system_prompt": "You are a concise, helpful sales agent.",
      "provider": "indigenius_reasoning_model_1",
      "hipaa": false
    }'
  ```

  ```javascript Node theme={null}
  const agentId = '665e4a34c65bb95f2f2d72e1';
  const response = await fetch(`https://api.indigenius.ai/v1/agents/${agentId}`, {
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.INDIGENIUS_API_KEY,
    },
    body: JSON.stringify({
      id: agentId,
      name: 'Sales Agent',
      language: 'English',
      first_message: 'Hello, I can help with product questions.',
      system_prompt: 'You are a concise, helpful sales agent.',
      provider: 'indigenius_reasoning_model_1',
      hipaa: false,
    }),
  });
  console.log(await response.json());
  ```

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

  agent_id = "665e4a34c65bb95f2f2d72e1"
  response = requests.patch(
      f"https://api.indigenius.ai/v1/agents/{agent_id}",
      headers={
          "X-API-Key": os.environ["INDIGENIUS_API_KEY"],
          "Content-Type": "application/json",
      },
      json={
          "id": agent_id,
          "name": "Sales Agent",
          "language": "English",
          "first_message": "Hello, I can help with product questions.",
          "system_prompt": "You are a concise, helpful sales agent.",
          "provider": "indigenius_reasoning_model_1",
          "hipaa": False,
      },
      timeout=30,
  )
  print(response.json())
  ```
</CodeGroup>

**`200 OK`**

```json theme={null}
{
  "status": true,
  "message": "Agent settings saved"
}
```

**Common errors:** `400` validation error (check `id` is in body) · `403` missing `agents:write` scope · `404` agent not found

***

## PATCH field reference

| Field           | Type      | Description                                                                            |
| --------------- | --------- | -------------------------------------------------------------------------------------- |
| `id`            | `string`  | **Required.** Must match the URL path parameter.                                       |
| `name`          | `string`  | Display name for the agent.                                                            |
| `language`      | `string`  | Spoken language (e.g. `"English"`, `"French"`).                                        |
| `first_message` | `string`  | Greeting spoken at the start of each call.                                             |
| `system_prompt` | `string`  | Full persona instructions for the LLM.                                                 |
| `provider`      | `string`  | LLM provider alias from `GET /v1/agents/voices` (e.g. `indigenius_reasoning_model_1`). |
| `model`         | `string`  | Optional model identifier.                                                             |
| `hipaa`         | `boolean` | Enable HIPAA-compliant mode (disables call recording).                                 |

***

## Recommended integration flow

1. Create an agent with your base persona (`POST /v1/agents`).
2. Copy the returned `id`.
3. List available voices with `GET /v1/agents/voices` to get valid provider and model aliases.
4. Use the `id` when creating widgets, calls, or workflows.
5. Update prompts and model settings over time with `PATCH /v1/agents/{id}`.