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

# Single-Use Agents

> Create agents that activate once and then expire

## Choosing the Right Agent Type

iwy offers two types of agents:

| Type                                           | Best For                                  | Sessions per Agent | Visible in Dashboard |
| ---------------------------------------------- | ----------------------------------------- | ------------------ | -------------------- |
| **Single-Use** (you are here)                  | Personalized, per-session experiences     | 1                  | No                   |
| [Permanent](/api-reference/dashboard/overview) | Reusable agents with dashboard management | Unlimited          | Yes                  |

**Not sure which to use?** See the [full comparison](/api-reference/api-reference#single-use-vs-permanent-agents). Both are production-ready.

***

## Overview

Single-Use agents are created via API and can only be activated once. After the session ends (or TTL expires), the agent ID becomes invalid. This is ideal for:

* **Personalized experiences**: Create a unique agent for each user or session
* **Dynamic configuration**: Generate agent settings from your database or user context
* **Auto-cleanup**: No manual deletion needed—agents expire automatically
* **White-label solutions**: Build products where end-users don't see the iwy dashboard

## How It Works

1. **Define your agent in code** - Specify LLM, voice, avatar, and behavior via API
2. **Receive an agent ID** - Use this ID in your frontend widget
3. **Agent auto-expires** - No cleanup needed, agents expire after the TTL

## Authentication

All API endpoints require authentication using a Bearer token. You can find your API key in your [account settings](https://app.iwy.ai/settings).

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

## Base URL

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

## Quick Start

Create an ephemeral agent and embed it in your app:

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

Then embed the agent in your frontend:

```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>
```

## When to Use Single-Use vs Permanent

| Use Case                            | Recommended |
| ----------------------------------- | ----------- |
| Prototyping and testing             | Permanent   |
| Same agent for all users            | Permanent   |
| Personalized agent per user/session | Single-Use  |
| Config generated from your database | Single-Use  |
| Production systems                  | Both        |

## Support

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