Skip to main content

​
Choosing the Right Agent Type

iwy offers two types of agents:
TypeBest ForSessions per AgentVisible in Dashboard
Single-UsePersonalized, per-session experiences1No
Permanent (you are here)Reusable agents with dashboard managementUnlimitedYes
Not sure which to use? See the full comparison. Both are production-ready.

​
Overview

Permanent agents persist in your account forever and can be used for unlimited sessions. Configure them anytime at dashboard.iwy.ai or via the API. This is ideal for:
  • Reusable agents: Use the same agent ID across unlimited sessions
  • Visual configuration: Edit agents through the dashboard UI
  • Team collaboration: Multiple team members can manage agents
  • CI/CD automation: Programmatically update agents via scripts

​
How It Works

Resources created through this API appear in and can be managed from the iwy dashboard. This gives you the best of both worlds:
  1. Visual editing - Use the dashboard for quick changes and testing
  2. Programmatic control - Use the API for automation and integration
  3. Persistent storage - Agents and tools are stored long-term in your account

​
Authentication

All API endpoints require authentication using a Bearer token. You can find your API key in your account settings. 
Authorization: Bearer YOUR_API_KEY

​
Base URL

https://api.iwy.ai/v1

​
Core Concepts

​
Agents

Agents are conversational AI entities that can interact with users through text and voice. Each agent has:
  • LLM Configuration: The language model, system prompt, and personality
  • STT/TTS Settings: Speech-to-text and text-to-speech providers
  • Video Avatar: Visual representation for video calls
  • Tool Integration: Custom functions the agent can call
  • Publish Status: Control visibility (draft, private, or public)

​
Tools

Tools are custom functions that extend your agent’s capabilities by connecting to external services via webhooks. Each tool defines:
  • Parameters Schema: JSON Schema describing expected inputs
  • Webhook URL: Your API endpoint to call
  • Authentication: Headers and auth configuration
  • Timeout Settings: Maximum execution time

​
Quick Start

​
1. Create a Tool

First, create a custom tool that your agent can use: 
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 current weather for a city",
    "server_url": "https://your-api.com/weather",
    "parameters_schema": {
      "type": "object",
      "required": ["city"],
      "properties": {
        "city": {
          "type": "string",
          "description": "City name"
        }
      }
    }
  }'

​
2. Create an Agent

Create an agent with your tool: 
curl -X POST https://api.iwy.ai/v1/agent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weather Assistant",
    "publish_status": "private",
    "configuration": {
      "llm": {
        "model": "gemini-2.0-flash",
        "provider": "google",
        "system_prompt": "You are a helpful weather assistant",
        "first_message": "Hello! Ask me about the weather."
      },
      "tool_calling": {
        "selected_tool_ids": ["YOUR_TOOL_ID"]
      }
    }
  }'

​
3. Embed in Your App

Use the agent in your application: 
<live-avatar agentid="YOUR_AGENT_ID"></live-avatar>
<script src="https://unpkg.com/@iwy/live-widgets@latest/dist/live-avatar.min.js"></script>
Or find other components at:

​
API Endpoints

​
Agents

  • List Agents: Get all agents in your account
  • Create Agent: Create a new agent
  • Get Agent: Retrieve agent configuration
  • Update Agent: Modify agent settings
  • Delete Agent: Remove an agent

​
Tools

  • List Tools: Get all tools in your account
  • Create Tool: Create a new tool
  • Get Tool: Retrieve tool configuration
  • Update Tool: Modify tool settings
  • Delete Tool: Remove a tool
  • Test Tool: Test tool execution with sample parameters

​
Sessions

  • Start Agent Session: Start a video call session with an agent

​
Support

Need help? Contact us