> ## 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.

# Introduction – Agent Builder Platform API

> Create and manage voice agents, FAQs, conversations, and the chat widget over REST.

The Agent Builder Platform API gives you programmatic control over agents you build in [Inya Agent Builder](/introduction): create and update configuration, manage FAQs, read conversation logs, and configure the embeddable chat widget.

For speech processing in your own stack, use [Gnani Speech APIs](/api/introduction/introduction) instead.

## Base URL

```text theme={null}
https://api.inya.ai/platform
```

All paths below are relative to this URL. Requests must use HTTPS.

## Authentication

Include your API key on every request:

```bash theme={null}
x-api-key: <your_api_key>
```

Keys are scoped by permission:

| Permission      | Endpoints             |
| --------------- | --------------------- |
| `agents`        | `/v1/agents/*`        |
| `conversations` | `/v1/conversations/*` |

Invalid keys return `401`. Valid keys without the required permission return `403`.

<Tip>
  Save the `requestId` from each response. You will need it when contacting support.
</Tip>

## Response format

Successful responses use this envelope:

```json theme={null}
{
  "status": "success",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Human-readable description.",
  "response": {}
}
```

Paginated lists also include `pageNo`, `pageSize`, `totalCount`, and `totalPages` inside `response`.

## API groups

| Group         | Path                                 | Guide                                                    |
| ------------- | ------------------------------------ | -------------------------------------------------------- |
| Agents        | `/v1/agents`                         | [Create Agent](/Platform/Create_Agent)                   |
| Agent config  | `/v1/agents/config`                  | [Get Languages](/Platform/Get_Languages)                 |
| Agent FAQ     | `/v1/agents/{botId}/faqs`            | [Add FAQs](/Platform/Add_FAQs)                           |
| Conversations | `/v1/conversations`                  | [Get Conversation Logs](/Platform/Get_Conversation_Logs) |
| Chat SDK      | `/v1/agents/{botId}/chat-sdk-config` | [Get Chat SDK Config](/Platform/Get_Chat_SDK_Config)     |

## Quick start

Create an agent with one request:

```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"
  }'
```

Example response:

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

Use the returned `botId` to configure the agent, attach FAQs, and trigger calls.

## Concepts

**System prompts** — Use Jinja2 variables such as `{{ customer_name }}`. Validate syntax with [Validate Prompt](/Platform/Validate_Prompt) before saving.

**Multi-language agents** — Up to three languages per agent. Call [Get Transcriber Config](/Platform/Get_Transcriber_Config) and [Get TTS Config](/Platform/Get_TTS_Config) before [Update Agent](/Platform/Update_Agent).

**Pre-call variables** — Inject caller-specific fields into the prompt at call time.

**FAQ knowledge base** — Up to 100 Q\&A pairs per agent; matched before the LLM generates an answer.

**Outbound calls** — Use [Trigger Call](/Platform/Trigger_Call) with `clientReferenceId` to link calls to your CRM.

## HTTP status codes

| Code | Meaning                                   |
| ---- | ----------------------------------------- |
| 200  | Success                                   |
| 201  | Created                                   |
| 400  | Invalid request                           |
| 401  | Authentication failed                     |
| 403  | Permission denied or inaccessible `botId` |
| 404  | Resource not found                        |
| 409  | Conflict (e.g. duplicate agent name)      |
| 429  | Rate limit exceeded                       |
| 500  | Server error                              |

## Best practices

* Call the Config API before creating or updating agents so ASR and TTS choices support every configured language.
* Validate prompts before saving.
* Test in development first; pass `?environment=development` when required.
* Log every `requestId` for support escalations.
* Keep API keys out of source control.

## Next steps

* [Create Agent](/Platform/Create_Agent)
* [Get Languages](/Platform/Get_Languages)
* [Validate Prompt](/Platform/Validate_Prompt)
* [Error Reference](/Platform/Error_Reference)

***

## Docs feedback

Docs feedback: [Agent Builder Platform docs feedback](https://discord.com/channels/1511338519899930634/1515991436229611571)

**Last verified:** 5 August 2026