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

# Create Agent

> Create a new voice agent with specified configuration

## Overview

Create a new voice agent within your organization. The agent is initialized with sensible defaults that match the configuration applied when creating an agent through the Inya dashboard. You can then update any setting via the **Update Agent** endpoint.

## Required Permission

`agents`

## Request Body

| Field         | Type   | Required | Default          | Description                                                                                             |
| ------------- | ------ | -------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
| `botName`     | string | Yes      | —                | Unique agent name within your organization.                                                             |
| `description` | string | No       | `""`             | A brief description of the agent's purpose.                                                             |
| `region`      | string | No       | `"asia"`         | Deployment region. Valid values: `asia`, `america`, `europe`. See [Get Regions](/Platform/Get_Regions). |
| `timeZone`    | string | No       | `"Asia/Kolkata"` | IANA timezone string. See **Get Timezones** for valid values.                                           |

## Default Configuration

<Note>
  The created agent inherits the following default configuration: barge-in enabled, TTS caching enabled, LLM temperature `0.5`, max tokens `300`, and language derived from the selected region.
</Note>

## Example cURL

```bash theme={null}
curl -X POST "https://api.inya.ai/platform/v1/agents" \
  -H "x-api-key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "botName": "Support Agent",
    "description": "Handles inbound customer support calls.",
    "region": "asia",
    "timeZone": "Asia/Kolkata"
  }'
```

## Response

### Success (201)

```json theme={null}
{
  "status": "success",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Agent created successfully.",
  "response": {
    "botId": "fb79920229d144608ebf665a10e50275",
    "botName": "Support Agent"
  }
}
```

### Error Responses

**403 Forbidden** - Insufficient permissions (QA role)

```json theme={null}
{
  "status": "failure",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "QA role does not have permission to create/update agents"
}
```

**409 Conflict** - Agent name already exists

```json theme={null}
{
  "status": "failure",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "An agent named 'Support Agent' already exists in your organization"
}
```

## Use Cases

* Setting up a new customer support agent
* Creating region-specific agents for different markets
* Deploying separate agents for different departments or products

<Tip>
  Use the **Get Regions**, **Get Timezones**, and **Get Languages** config endpoints to discover valid values for `region` and `timeZone` before creating an agent.
</Tip>

<Note>
  Save the `requestId` from every response. You will need it if you contact Inya support to trace a specific request.
</Note>


## OpenAPI

````yaml POST /v1/agents
openapi: 3.0.3
info:
  title: Platform Agents API
  description: API endpoints for creating, managing, and interacting with voice agents
  version: 2.1.0
servers:
  - url: https://api.inya.ai/platform
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Agents
    description: Agent management operations
  - name: AgentFAQ
    description: Agent FAQ management
  - name: AgentCallTriggers
    description: Outbound call triggers
  - name: ChatSDK
    description: Chat Widget configuration
  - name: Conversations
    description: Conversation logs, statistics, and audio
paths:
  /v1/agents:
    post:
      tags:
        - Agents
      summary: Create a new agent
      description: >-
        Create a new voice agent. All configuration fields default to the same
        values used when creating an agent through the Inya dashboard.
      operationId: createAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
            examples:
              asiaAgent:
                summary: Asia region agent
                value:
                  botName: Support Agent
                  description: Handles inbound customer support calls.
                  region: asia
                  timeZone: Asia/Kolkata
      responses:
        '201':
          description: Agent created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  value:
                    status: success
                    requestId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: Agent created successfully.
                    response:
                      botId: fb79920229d144608ebf665a10e50275
                      botName: Support Agent
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Agent name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                conflict:
                  value:
                    status: failure
                    requestId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    message: >-
                      An agent named 'Support Agent' already exists in your
                      organization
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    CreateAgentRequest:
      type: object
      required:
        - botName
      properties:
        botName:
          type: string
          example: Support Agent
        description:
          type: string
          example: Handles inbound customer support calls.
        region:
          type: string
          enum:
            - asia
            - america
            - europe
          default: asia
          example: asia
        timeZone:
          type: string
          default: Asia/Kolkata
          example: Asia/Kolkata
    StandardResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        requestId:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        message:
          type: string
        response:
          type: object
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: error
        requestId:
          type: string
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        message:
          type: string
  responses:
    Forbidden:
      description: Permission denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key with 'agents' permission

````