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

# API Reference

> Complete API reference for creating and managing AI agents

## Overview

The iwy API provides everything you need to create and deploy conversational AI agents. There are two types of agents you can create:

<CardGroup cols={2}>
  <Card title="Single-Use Agents" icon="clock" href="#single-use-agents">
    Created via API, activated once, then expires. Perfect for personalized, per-session experiences.
  </Card>

  <Card title="Permanent Agents" icon="database" href="#permanent-agents">
    Created via API or dashboard, reusable forever. Configure anytime at [dashboard.iwy.ai](https://app.iwy.ai).
  </Card>
</CardGroup>

<Info>
  **Both types are production-ready and interchangeable.** Use the same widgets and session APIs with either type. Choose based on your use case—many production systems use both.
</Info>

***

## Authentication

All API endpoints require a Bearer token.

```bash theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```

Get your API key from [app.iwy.ai/settings](https://app.iwy.ai/settings).

## Base URL

```
https://api.iwy.ai/v1
```

***

## Core Endpoints

These are the three endpoints you'll use most often:

| Endpoint                    | Purpose                    |
| --------------------------- | -------------------------- |
| `POST /ephemeral-agent`     | Create a single-use agent  |
| `POST /agent`               | Create a permanent agent   |
| `POST /start-agent-session` | Start a video call session |

<Note>
  **Using iwy widgets?** The `<live-avatar>` widget and [meet.iwy.ai](https://meet.iwy.ai) already call `/start-agent-session` for you automatically. You only need this endpoint if you're building a custom integration with the [Daily.co SDK](https://docs.daily.co/reference).
</Note>

***

## Single-Use vs Permanent Agents

<AccordionGroup>
  <Accordion title="What's the difference?">
    **Single-Use Agents** are created through the API and can only be activated once. After their first session ends (or the TTL expires), the agent ID becomes invalid. They don't appear in your dashboard.

    **Permanent Agents** persist in your account forever. The same agent ID can be used for unlimited sessions. You can edit them anytime at [dashboard.iwy.ai](https://app.iwy.ai) or via the API.

    | Feature                 | Single-Use | Permanent |
    | ----------------------- | ---------- | --------- |
    | Sessions per agent      | 1          | Unlimited |
    | Visible in dashboard    | No         | Yes       |
    | Editable after creation | No         | Yes       |
    | Auto-expires            | Yes (TTL)  | No        |
  </Accordion>

  <Accordion title="Which should I use?">
    **Both are production-ready.** Choose based on your architecture:

    | Use Case                            | Recommended |
    | ----------------------------------- | ----------- |
    | Same agent for all users            | Permanent   |
    | Personalized agent per user/session | Single-Use  |
    | Want to edit config in dashboard    | Permanent   |
    | Config generated from your database | Single-Use  |
    | White-label / multi-tenant apps     | Single-Use  |
    | Quick prototyping and testing       | Permanent   |

    Many production systems use **both**: permanent agents for core experiences, single-use agents for personalization.
  </Accordion>

  <Accordion title="Can I use them interchangeably?">
    Yes! Both agent types work identically with:

    * All iwy widgets (`<live-avatar>`, etc.)
    * [meet.iwy.ai](https://meet.iwy.ai) hosted pages
    * The `/start-agent-session` API
    * Tool integrations

    The only difference is lifecycle management—single-use agents expire, permanent agents persist.
  </Accordion>

  <Accordion title="What happens after a single-use agent is activated?">
    Once a session starts with a single-use agent:

    1. The agent becomes "active" for that session
    2. When the session ends, the agent expires immediately
    3. Any further attempts to use that agent ID will fail

    If no session ever starts, the agent expires after its TTL (time-to-live).
  </Accordion>

  <Accordion title="How do I convert between types?">
    You can't convert directly, but you can reuse configurations:

    1. **Single-Use → Permanent**: Use the same `configuration` object with `POST /agent`
    2. **Permanent → Single-Use**: Fetch config with `GET /agent/{id}`, then use it with `POST /ephemeral-agent`

    This is useful for prototyping in the dashboard, then deploying as single-use agents.
  </Accordion>
</AccordionGroup>

***

## Single-Use Agents

Create dynamic agents that activate once and then expire. Ideal for personalized, per-session experiences.

### Create Single-Use Agent

<ParamField path="POST" type="/ephemeral-agent">
  Creates an agent that can be activated once, then expires.
</ParamField>

**Request Body**

<ParamField body="configuration" type="object" required>
  Agent configuration including LLM, TTS, and video settings.

  <Expandable title="configuration properties">
    <ParamField body="llm" type="object" required>
      <ParamField body="model" type="string" required>
        LLM model name (e.g., `"gemini-2.0-flash"`)
      </ParamField>

      <ParamField body="provider" type="string" required>
        LLM provider (e.g., `"google"`, `"openai"`)
      </ParamField>

      <ParamField body="system_prompt" type="string" required>
        Instructions defining the agent's personality and behavior
      </ParamField>

      <ParamField body="first_message" type="string" required>
        Initial greeting message
      </ParamField>
    </ParamField>

    <ParamField body="tts" type="object">
      <ParamField body="provider" type="string" required>
        TTS provider (e.g., `"elevenlabs"`)
      </ParamField>

      <ParamField body="voice_id" type="string">
        Voice identifier
      </ParamField>
    </ParamField>

    <ParamField body="video" type="object">
      <ParamField body="provider" type="string" required>
        Video provider (e.g., `"binary"`)
      </ParamField>

      <ParamField body="character_id" type="string">
        Avatar character identifier
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="ttl_seconds" type="integer" default="600">
  Maximum time (in seconds) before the agent expires if not activated. Common values: 600 (10 min), 3600 (1 hour), 86400 (24 hours).
</ParamField>

**Example Request**

```bash theme={"dark"}
curl -X POST https://api.iwy.ai/v1/ephemeral-agent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "configuration": {
      "llm": {
        "model": "gemini-2.0-flash",
        "provider": "google",
        "system_prompt": "You are a helpful assistant for a product demo",
        "first_message": "Welcome! How can I help you today?"
      },
      "tts": {
        "provider": "elevenlabs",
        "voice_id": "21m00Tcm4TlvDq8ikWAM"
      },
      "video": {
        "provider": "binary",
        "character_id": "0001"
      }
    },
    "ttl_seconds": 600
  }'
```

**Response**

```json theme={"dark"}
{
  "agent": {
    "id": "550e8400-e29b-41d4-a716-446655440099",
    "expires_at": "2025-01-15T10:30:00.000Z",
    "created_at": "2025-01-15T10:20:00.000Z"
  }
}
```

**Using the Agent**

```html theme={"dark"}
<live-avatar agentid="550e8400-e29b-41d4-a716-446655440099"></live-avatar>
<script src="https://unpkg.com/@iwy/live-widgets@latest/dist/live-avatar.min.js"></script>
```

***

## Permanent Agents

Create reusable agents that persist in your account. Configure them anytime at [dashboard.iwy.ai](https://app.iwy.ai) or via the API.

### Create Permanent Agent

<ParamField path="POST" type="/agent">
  Creates a reusable agent that persists in your account.
</ParamField>

**Request Body**

<ParamField body="name" type="string" required>
  Human-readable name for the agent (visible in dashboard)
</ParamField>

<ParamField body="publish_status" type="string" default="draft">
  Visibility status: `draft`, `private`, or `public`
</ParamField>

<ParamField body="configuration" type="object" required>
  Agent configuration (same structure as single-use agents, plus additional options)

  <Expandable title="configuration properties">
    <ParamField body="llm" type="object" required>
      <ParamField body="model" type="string" required>
        LLM model name
      </ParamField>

      <ParamField body="provider" type="string" required>
        LLM provider
      </ParamField>

      <ParamField body="system_prompt" type="string" required>
        Agent personality and behavior instructions
      </ParamField>

      <ParamField body="first_message" type="string" required>
        Initial greeting
      </ParamField>

      <ParamField body="cost_per_minute" type="number">
        Cost tracking per minute
      </ParamField>
    </ParamField>

    <ParamField body="stt" type="object">
      <ParamField body="model" type="string">
        STT model name (e.g., `"nova-3-general"`)
      </ParamField>

      <ParamField body="provider" type="string">
        STT provider (e.g., `"deepgram"`)
      </ParamField>
    </ParamField>

    <ParamField body="tts" type="object">
      <ParamField body="provider" type="string" required>
        TTS provider
      </ParamField>

      <ParamField body="voice_id" type="string">
        Voice identifier
      </ParamField>
    </ParamField>

    <ParamField body="video" type="object">
      <ParamField body="provider" type="string" required>
        Video provider
      </ParamField>

      <ParamField body="character_id" type="string">
        Avatar character ID
      </ParamField>
    </ParamField>

    <ParamField body="tool_calling" type="object">
      <ParamField body="selected_tool_ids" type="array">
        Array of tool IDs this agent can use
      </ParamField>
    </ParamField>

    <ParamField body="end_of_conversation" type="object">
      <ParamField body="callback_url" type="string">
        Webhook URL for conversation end events
      </ParamField>

      <ParamField body="send_data_on_end" type="boolean">
        Whether to send conversation data
      </ParamField>
    </ParamField>
  </Expandable>
</ParamField>

**Example Request**

```bash theme={"dark"}
curl -X POST https://api.iwy.ai/v1/agent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Service Bot",
    "publish_status": "private",
    "configuration": {
      "llm": {
        "model": "gemini-2.0-flash",
        "provider": "google",
        "system_prompt": "You are a helpful customer service assistant",
        "first_message": "Hello! How can I help you today?"
      },
      "stt": {
        "model": "nova-3-general",
        "provider": "deepgram"
      },
      "tts": {
        "provider": "elevenlabs",
        "voice_id": "21m00Tcm4TlvDq8ikWAM"
      },
      "video": {
        "provider": "binary",
        "character_id": "0001"
      },
      "version": "1.0"
    }
  }'
```

**Using the Agent**

```html theme={"dark"}
<live-avatar agentid="YOUR_AGENT_ID"></live-avatar>
<script src="https://unpkg.com/@iwy/live-widgets@latest/dist/live-avatar.min.js"></script>
```

Or share directly: `https://meet.iwy.ai/YOUR_AGENT_ID`

***

## Sessions

Start video call sessions with your agents.

<Warning>
  **You probably don't need this endpoint directly.** The `<live-avatar>` widget and [meet.iwy.ai](https://meet.iwy.ai) call this automatically. Only use this if you're building a custom integration with the [Daily.co SDK](https://docs.daily.co/reference).
</Warning>

### Start Agent Session

<ParamField path="POST" type="/start-agent-session">
  Starts a video call session with an agent. Returns Daily.co connection details.
</ParamField>

**Request Body**

<ParamField body="agentId" type="string" required>
  Agent UUID (works with both single-use and permanent agents), or `"demo"` for a demo session
</ParamField>

**Example Request**

```bash theme={"dark"}
curl -X POST https://api.iwy.ai/v1/start-agent-session \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "550e8400-e29b-41d4-a716-446655440000"
  }'
```

**Response**

```json theme={"dark"}
{
  "roomUrl": "https://iwy.daily.co/room-abc123",
  "dailyToken": "eyJ...",
  "webLink": "https://app.iwy.ai/call/room-abc123"
}
```

**Usage Options**

| Method                                     | When to use                       |
| ------------------------------------------ | --------------------------------- |
| `<live-avatar>` widget                     | Recommended for most integrations |
| [meet.iwy.ai](https://meet.iwy.ai) link    | Share a direct link to your agent |
| Daily.co SDK with `roomUrl` + `dailyToken` | Custom video UI implementations   |
| `webLink`                                  | Browser-based access without SDK  |

***

## Advanced Endpoints

These endpoints provide additional management capabilities for permanent agents and tools.

### Permanent Agent Management

| Endpoint      | Method | Description               |
| ------------- | ------ | ------------------------- |
| `/agent`      | GET    | List all permanent agents |
| `/agent/{id}` | GET    | Get agent configuration   |
| `/agent/{id}` | PATCH  | Update agent settings     |
| `/agent/{id}` | DELETE | Delete agent permanently  |

<Accordion title="List All Agents">
  ```bash theme={"dark"}
  curl https://api.iwy.ai/v1/agent \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  **Response**

  ```json theme={"dark"}
  [
    { "id": "550e8400-...", "name": "Customer Service Bot" },
    { "id": "550e8400-...", "name": "Sales Assistant" }
  ]
  ```
</Accordion>

<Accordion title="Get Agent Details">
  ```bash theme={"dark"}
  curl https://api.iwy.ai/v1/agent/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</Accordion>

<Accordion title="Update Agent">
  ```bash theme={"dark"}
  curl -X PATCH https://api.iwy.ai/v1/agent/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "configuration": {
        "llm": {
          "system_prompt": "You are an expert sales assistant",
          "first_message": "Welcome! Ready to explore our products?"
        }
      }
    }'
  ```
</Accordion>

<Accordion title="Delete Agent">
  ```bash theme={"dark"}
  curl -X DELETE https://api.iwy.ai/v1/agent/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</Accordion>

***

### Tools

Tools are custom functions that extend your agent's capabilities via webhooks.

| Endpoint          | Method | Description            |
| ----------------- | ------ | ---------------------- |
| `/tool`           | GET    | List all tools         |
| `/tool`           | POST   | Create a new tool      |
| `/tool/{id}`      | GET    | Get tool configuration |
| `/tool/{id}`      | PATCH  | Update tool settings   |
| `/tool/{id}`      | DELETE | Delete tool            |
| `/tool/{id}/test` | POST   | Test tool execution    |

<Accordion title="Create Tool">
  ```bash theme={"dark"}
  curl -X POST https://api.iwy.ai/v1/tool \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "get_weather",
      "description": "Fetches the current weather for a given city",
      "server_url": "https://your-api.com/weather",
      "parameters_schema": {
        "type": "object",
        "required": ["city"],
        "properties": {
          "city": {
            "type": "string",
            "description": "City name (e.g., Paris, New York)"
          }
        }
      },
      "method": "POST",
      "headers": {
        "x-api-key": "your-webhook-api-key"
      }
    }'
  ```
</Accordion>

<Accordion title="Test Tool">
  ```bash theme={"dark"}
  curl -X POST https://api.iwy.ai/v1/tool/dcfae097-1b37-4444-bb0c-1a6abb0320fd/test \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "parameters": { "city": "Paris" }
    }'
  ```

  **Response**

  ```json theme={"dark"}
  {
    "success": true,
    "execution_time_ms": 1234,
    "response_received": {
      "status": 200,
      "body": { "temperature": 18, "conditions": "Partly cloudy" }
    }
  }
  ```
</Accordion>

***

## Error Responses

All endpoints return consistent error responses:

| Status | Description                               |
| ------ | ----------------------------------------- |
| `400`  | Bad request - validation failed           |
| `401`  | Unauthorized - invalid or missing API key |
| `404`  | Not found - resource doesn't exist        |
| `408`  | Request timeout                           |
| `500`  | Internal server error                     |

```json theme={"dark"}
{
  "success": false,
  "error": "Error message",
  "details": "Additional context"
}
```

***

## Quick Reference

### Core Endpoints

| Endpoint               | Method | Description                                           |
| ---------------------- | ------ | ----------------------------------------------------- |
| `/ephemeral-agent`     | POST   | Create single-use agent                               |
| `/agent`               | POST   | Create permanent agent                                |
| `/start-agent-session` | POST   | Start video session (called automatically by widgets) |

### Management Endpoints

| Endpoint          | Method | Description           |
| ----------------- | ------ | --------------------- |
| `/agent`          | GET    | List permanent agents |
| `/agent/{id}`     | GET    | Get agent details     |
| `/agent/{id}`     | PATCH  | Update agent          |
| `/agent/{id}`     | DELETE | Delete agent          |
| `/tool`           | GET    | List tools            |
| `/tool`           | POST   | Create tool           |
| `/tool/{id}`      | GET    | Get tool details      |
| `/tool/{id}`      | PATCH  | Update tool           |
| `/tool/{id}`      | DELETE | Delete tool           |
| `/tool/{id}/test` | POST   | Test tool             |

***

## Support

Need help? [Contact us](https://www.iwy.ai/contact)