Skip to main content

​
Welcome to the iwy API

The iwy API allows you to programmatically create and manage AI agents with custom capabilities. Build conversational AI experiences, integrate custom tools, and embed interactive avatars in your applications.

​
Authentication

All API endpoints require authentication using a Bearer token. You can find your API key in your account settings. Include your API key in the Authorization header of every request: 
Authorization: Bearer YOUR_API_KEY

​
Base URL

All API requests should be made to: 
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 using our widget libraries: 
<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 altenative components to use at:

​
API Endpoints

​
Agents

Manage your AI 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

Manage custom tool integrations
  • 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

​
Support

Need help? We’re here for you:
  • Documentation: Browse our comprehensive guides
  • Support: Contact us