# Agents API

## What this covers

An agent is the frozen configuration a call runs against: pipeline, prompt, language, limits and webhook. Sessions record the agent version they ran, so editing an agent never rewrites history.

Every example below runs as written once these are exported:

```bash
export DVAARIK_API_KEY="dvk_..."        # project API key, server side only
export DVAARIK_TOKEN="<account access token>"   # console session, from POST /console/auth/login
export AGENT_ID="<uuid>"
export PROJECT_ID="<uuid>"
```

A `<value>` inside a JSON body is a value you supply. Responses are JSON; every error body is `{ "detail": … }`. Each schema is expanded once per page, where it first appears.

### Machine door errors

Raised by the project-key dependency before any handler on this page runs.

| Status | Cause |
| --- | --- |
| `401` | `Missing API key` or `Invalid API key` — the `X-Api-Key` header is absent, unknown, or revoked. |
| `403` | `API key is not scoped to a project`, `Project unavailable`, or `API key is missing the required scope '<scope>'`. |
| `429` | The project's `api_rpm` ceiling was exceeded. Honour `Retry-After`; `X-RateLimit-*` headers are on every response. |

Scopes used on this page: `voice:read`, `voice:write`. Mint a key with only these.

### Account door errors

| Status | Cause |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. Refresh once, then re-authenticate. |
| `403` | The account is suspended or its email is not verified. |

## Operations — project API key

Call these from your own server with a project key. Never from a browser or a mobile bundle.

### GET `/v2/agents`

List the project's agents.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:read` |
| Operation | `list_agents_v2_agents_get` |
| Success | `200` `V2AgentInfo[]` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |
| `include_inactive` | query | boolean | no |  |

#### `V2AgentInfo`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `ambience_level` | integer or null | yes |  |
| `ambience_sound` | string or null | yes |  |
| `backchannel` | boolean | yes |  |
| `can_send_dtmf` | boolean | yes |  |
| `created_at` | date-time | yes |  |
| `dead_air_seconds` | integer or null | yes |  |
| `display_name` | string or null | yes |  |
| `greeting` | string or null | yes |  |
| `has_webhook_secret` | boolean | no | default false |
| `id` | uuid | yes |  |
| `idle_hangup_seconds` | integer or null | yes |  |
| `idle_warn_seconds` | integer or null | yes |  |
| `insight_config` | InsightConfigBody or null | no |  |
| `is_active` | boolean | yes |  |
| `language` | string | yes |  |
| `max_chars_per_min` | integer or null | yes |  |
| `max_duration_seconds` | integer or null | yes |  |
| `name` | string | yes |  |
| `pipeline_config` | object | yes |  |
| `pipeline_mode` | string | yes |  |
| `project_id` | uuid | yes |  |
| `prompt` | string | yes |  |
| `record_calls` | boolean | yes |  |
| `retention_days` | integer or null | yes |  |
| `store_transcript` | boolean | yes |  |
| `tool_webhook_url` | string or null | yes |  |
| `tools` | any[] | yes |  |
| `updated_at` | date-time | yes |  |
| `variables` | any[] | yes |  |
| `version` | integer | yes |  |
| `webhook_include_recording_url` | boolean | yes |  |
| `webhook_include_transcript` | boolean | yes |  |
| `webhook_url` | string or null | yes |  |

| Error | When |
| --- | --- |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/v2/agents?limit=20" \
  -H "X-Api-Key: $DVAARIK_API_KEY"
```

### POST `/v2/agents`

Create an agent. The response carries its webhook signing secret once.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:write` |
| Operation | `create_agent_v2_agents_post` |
| Success | `201` `V2CreatedAgentResponse` |

Request body: `V2AgentCreate`.

#### `V2AgentCreate`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `ambience_level` | integer or null | no |  |
| `ambience_sound` | string or null | no |  |
| `backchannel` | boolean | no | default true |
| `can_send_dtmf` | boolean | no | default false |
| `dead_air_seconds` | integer or null | no |  |
| `display_name` | string or null | no |  |
| `greeting` | string or null | no |  |
| `idle_hangup_seconds` | integer or null | no |  |
| `idle_warn_seconds` | integer or null | no |  |
| `insight_config` | InsightConfigBody or null | no |  |
| `language` | string | no | default "en-IN" |
| `max_chars_per_min` | integer or null | no |  |
| `max_duration_seconds` | integer or null | no |  |
| `name` | string | yes |  |
| `pipeline_config` | object | yes |  |
| `pipeline_mode` | string | yes |  |
| `prompt` | string | yes |  |
| `record_calls` | boolean | no | default false |
| `retention_days` | integer or null | no |  |
| `store_transcript` | boolean | no | default false |
| `tool_webhook_url` | string or null | no |  |
| `tools` | object[] | no |  |
| `variables` | object[] | no |  |
| `webhook_include_recording_url` | boolean | no | default false |
| `webhook_include_transcript` | boolean | no | default false |
| `webhook_url` | string or null | no |  |

#### `V2CreatedAgentResponse`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `agent` | V2AgentInfo | yes |  |
| `webhook_secret` | string | yes |  |

| Error | When |
| --- | --- |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/v2/agents" \
  -H "X-Api-Key: $DVAARIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support",
    "pipeline_config": {
      "stt": {
        "account_id": "<provider account uuid>",
        "model": "<model id from the catalogue>"
      },
      "llm": {
        "account_id": "<provider account uuid>",
        "model": "<model id from the catalogue>"
      },
      "tts": {
        "account_id": "<provider account uuid>",
        "model": "<model id from the catalogue>",
        "voice": "<provider voice id>"
      }
    },
    "pipeline_mode": "cascade",
    "prompt": "You are the receptionist for {{company}}. Answer questions and book visits.",
    "greeting": "Hello, this is support.",
    "language": "en-IN"
  }'
```

### DELETE `/v2/agents/{agent_id}`

Deactivate the agent. Past sessions keep the agent id and version they ran; numbers bound to it stop answering.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:write` |
| Operation | `delete_agent_v2_agents__agent_id__delete` |
| Success | `200` `V2AgentDeleted` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `agent_id` | path | uuid | yes |  |

#### `V2AgentDeleted`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `calls` | integer | yes |  |
| `deleted` | boolean | yes |  |
| `id` | uuid | yes |  |
| `name` | string | yes |  |

| Error | When |
| --- | --- |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X DELETE "https://api.developers.dvaarik.com/v2/agents/$AGENT_ID" \
  -H "X-Api-Key: $DVAARIK_API_KEY"
```

### GET `/v2/agents/{agent_id}`

Read one agent, including the pipeline it will run.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:read` |
| Operation | `get_agent_v2_agents__agent_id__get` |
| Success | `200` `V2AgentInfo` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `agent_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/v2/agents/$AGENT_ID" \
  -H "X-Api-Key: $DVAARIK_API_KEY"
```

### PATCH `/v2/agents/{agent_id}`

Update an agent. Only the fields you send change, and the version increments.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:write` |
| Operation | `update_agent_v2_agents__agent_id__patch` |
| Success | `200` `V2AgentInfo` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `agent_id` | path | uuid | yes |  |

Request body: `V2AgentUpdate`.

#### `V2AgentUpdate`

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `ambience_level` | integer or null | no |  |
| `ambience_sound` | string or null | no |  |
| `backchannel` | boolean or null | no |  |
| `can_send_dtmf` | boolean or null | no |  |
| `dead_air_seconds` | integer or null | no |  |
| `display_name` | string or null | no |  |
| `greeting` | string or null | no |  |
| `idle_hangup_seconds` | integer or null | no |  |
| `idle_warn_seconds` | integer or null | no |  |
| `insight_config` | InsightConfigBody or null | no |  |
| `is_active` | boolean or null | no |  |
| `language` | string or null | no |  |
| `max_chars_per_min` | integer or null | no |  |
| `max_duration_seconds` | integer or null | no |  |
| `name` | string or null | no |  |
| `pipeline_config` | object or null | no |  |
| `pipeline_mode` | string or null | no |  |
| `prompt` | string or null | no |  |
| `record_calls` | boolean or null | no |  |
| `retention_days` | integer or null | no |  |
| `store_transcript` | boolean or null | no |  |
| `tool_webhook_url` | string or null | no |  |
| `tools` | object[] or null | no |  |
| `variables` | object[] or null | no |  |
| `webhook_include_recording_url` | boolean or null | no |  |
| `webhook_include_transcript` | boolean or null | no |  |
| `webhook_url` | string or null | no |  |

| Error | When |
| --- | --- |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X PATCH "https://api.developers.dvaarik.com/v2/agents/$AGENT_ID" \
  -H "X-Api-Key: $DVAARIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "greeting": "Hello, this is support. How can I help?",
    "is_active": true
  }'
```

### POST `/v2/agents/{agent_id}/rotate-secret`

Issue a new webhook signing secret for this agent and return it once.

| Detail | Value |
| --- | --- |
| Door | Project API key — `X-Api-Key: $DVAARIK_API_KEY` |
| Scope | `voice:write` |
| Operation | `rotate_secret_v2_agents__agent_id__rotate_secret_post` |
| Success | `200` `V2CreatedAgentResponse` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `agent_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the machine-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/v2/agents/$AGENT_ID/rotate-secret" \
  -H "X-Api-Key: $DVAARIK_API_KEY"
```

## Operations — account session

The same resource through the console door. These are what the web console calls; both doors return the same shapes.

### GET `/console/v2/projects/{project_id}/agents`

List the project's agents.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleListAgents` |
| Success | `200` `V2AgentInfo[]` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `project_id` | path | uuid | yes |  |
| `limit` | query | integer | no |  |
| `offset` | query | integer | no |  |
| `include_inactive` | query | boolean | no |  |

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/agents?limit=20" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"
```

### POST `/console/v2/projects/{project_id}/agents`

Create an agent. The response carries its webhook signing secret once.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleCreateAgent` |
| Success | `201` `V2CreatedAgentResponse` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `project_id` | path | uuid | yes |  |

Request body: `V2AgentCreate`.

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `409` | The project or resource is in a state that refuses this change. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/agents" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support",
    "pipeline_config": {
      "stt": {
        "account_id": "<provider account uuid>",
        "model": "<model id from the catalogue>"
      },
      "llm": {
        "account_id": "<provider account uuid>",
        "model": "<model id from the catalogue>"
      },
      "tts": {
        "account_id": "<provider account uuid>",
        "model": "<model id from the catalogue>",
        "voice": "<provider voice id>"
      }
    },
    "pipeline_mode": "cascade",
    "prompt": "You are the receptionist for {{company}}. Answer questions and book visits.",
    "greeting": "Hello, this is support.",
    "language": "en-IN"
  }'
```

### DELETE `/console/v2/projects/{project_id}/agents/{agent_id}`

Deactivate the agent. Past sessions keep the agent id and version they ran; numbers bound to it stop answering.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleDeleteAgent` |
| Success | `200` `V2AgentDeleted` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `agent_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `409` | The project or resource is in a state that refuses this change. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X DELETE "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/agents/$AGENT_ID" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"
```

### GET `/console/v2/projects/{project_id}/agents/{agent_id}`

Read one agent, including the pipeline it will run.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleGetAgent` |
| Success | `200` `V2AgentInfo` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `agent_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/agents/$AGENT_ID" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"
```

### PATCH `/console/v2/projects/{project_id}/agents/{agent_id}`

Update an agent. Only the fields you send change, and the version increments.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleUpdateAgent` |
| Success | `200` `V2AgentInfo` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `agent_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |

Request body: `V2AgentUpdate`.

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `409` | The project or resource is in a state that refuses this change. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X PATCH "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/agents/$AGENT_ID" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "greeting": "Hello, this is support. How can I help?",
    "is_active": true
  }'
```

### POST `/console/v2/projects/{project_id}/agents/{agent_id}/rotate-secret`

Issue a new webhook signing secret for this agent and return it once.

| Detail | Value |
| --- | --- |
| Door | Account session — `Authorization: Bearer $DVAARIK_TOKEN` |
| Operation | `consoleRotateAgentSecret` |
| Success | `200` `V2CreatedAgentResponse` |

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `agent_id` | path | uuid | yes |  |
| `project_id` | path | uuid | yes |  |

| Error | When |
| --- | --- |
| `401` | No account session was presented, or it is invalid or expired. |
| `403` | The account is suspended or its email is not verified. |
| `404` | The project or the addressed resource does not exist for this owner. A resource owned by another developer is deliberately indistinguishable from one that never existed. |
| `409` | The project or resource is in a state that refuses this change. |
| `422` | The request body or query is not valid. `detail` is an array of `{loc, msg, type}` and `loc` names the offending field. |

Plus the account-door errors above. Full list on the [errors page](/docs/errors).

```bash
curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/agents/$AGENT_ID/rotate-secret" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"
```

---

Source: https://developers.dvaarik.com/docs/api/agents · every page as one file: https://developers.dvaarik.com/docs.md