API Reference - iwy.ai Documentation

Overview

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

Single-Use Agents

Created via API, activated once, then expires. Perfect for personalized, per-session experiences.

Permanent Agents

Created via API or dashboard, reusable forever. Configure anytime at dashboard.iwy.ai.

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.

Authentication

All API endpoints require a Bearer token.

Authorization: Bearer YOUR_API_KEY

Get your API key from 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

Using iwy widgets? The <live-avatar> widget and 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.

Single-Use vs Permanent Agents

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

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.

Can I use them interchangeably?

Yes! Both agent types work identically with:

All iwy widgets (<live-avatar>, etc.)
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.

What happens after a single-use agent is activated?

Once a session starts with a single-use agent:

The agent becomes “active” for that session
When the session ends, the agent expires immediately
Any further attempts to use that agent ID will fail

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

How do I convert between types?

You can’t convert directly, but you can reuse configurations:

Single-Use → Permanent: Use the same configuration object with POST /agent
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.

Single-Use Agents

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

Create Single-Use Agent

/ephemeral-agent

Creates an agent that can be activated once, then expires.

Request Body

object

required

Agent configuration including LLM, TTS, and video settings.

Show configuration properties

object

required

string

required

LLM model name (e.g., "gemini-2.0-flash")

string

required

LLM provider (e.g., "google", "openai")

string

required

Instructions defining the agent’s personality and behavior

string

required

Initial greeting message

object

string

required

TTS provider (e.g., "elevenlabs")

string

Voice identifier

object

string

required

Video provider (e.g., "binary")

string

Avatar character identifier

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

Example Request

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

{
  "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

<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 or via the API.

Create Permanent Agent

/agent

Creates a reusable agent that persists in your account.

Request Body

string

required

Human-readable name for the agent (visible in dashboard)

string

default:"draft"

Visibility status: draft, private, or public

object

required

Agent configuration (same structure as single-use agents, plus additional options)

Show configuration properties

object

required

string

required

LLM model name

string

required

LLM provider

string

required

Agent personality and behavior instructions

string

required

Initial greeting

number

Cost tracking per minute

object

string

STT model name (e.g., "nova-3-general")

string

STT provider (e.g., "deepgram")

object

string

required

TTS provider

string

Voice identifier

object

string

required

Video provider

string

Avatar character ID

object

array

Array of tool IDs this agent can use

object

string

Webhook URL for conversation end events

boolean

Whether to send conversation data

Example Request

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

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

You probably don’t need this endpoint directly. The <live-avatar> widget and meet.iwy.ai call this automatically. Only use this if you’re building a custom integration with the Daily.co SDK.

Start Agent Session

/start-agent-session

Starts a video call session with an agent. Returns Daily.co connection details.

Request Body

string

required

Agent UUID (works with both single-use and permanent agents), or "demo" for a demo session

Example Request

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

{
  "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 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

List All Agents

curl https://api.iwy.ai/v1/agent \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  { "id": "550e8400-...", "name": "Customer Service Bot" },
  { "id": "550e8400-...", "name": "Sales Assistant" }
]

Get Agent Details

curl https://api.iwy.ai/v1/agent/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Agent

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

Delete Agent

curl -X DELETE https://api.iwy.ai/v1/agent/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

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

Create Tool

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

Test Tool

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

{
  "success": true,
  "execution_time_ms": 1234,
  "response_received": {
    "status": 200,
    "body": { "temperature": 18, "conditions": "Partly cloudy" }
  }
}

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

{
  "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

​Overview

Single-Use Agents

Permanent Agents

​Authentication

​Base URL

​Core Endpoints

​Single-Use vs Permanent Agents

​Single-Use Agents

​Create Single-Use Agent

​Permanent Agents

​Create Permanent Agent

​Sessions

​Start Agent Session

​Advanced Endpoints

​Permanent Agent Management

​Tools

​Error Responses

​Quick Reference

​Core Endpoints

​Management Endpoints

​Support

Overview

Authentication

Base URL

Core Endpoints

Single-Use vs Permanent Agents

Single-Use Agents

Create Single-Use Agent

Permanent Agents

Create Permanent Agent

Sessions

Start Agent Session

Advanced Endpoints

Permanent Agent Management

Tools

Error Responses

Quick Reference

Core Endpoints

Management Endpoints

Support