> ## 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. # Create ephemeral agent > Creates a one-time use agent with automatic expiration. Ephemeral agents are more appropiate for use cases where you want to spin up an customized agent without persisting it long-term in the iwy dashboard. Ephemeral agents won't appear in the dashboard. The agent will automatically expire after a specified time to live (TTL). ## OpenAPI ````yaml post /ephemeral-agent openapi: 3.0.3 info: title: iwy API description: > API for managing AI agents and custom tools. Create conversational AI agents with custom capabilities, manage tool integrations, and embed AI avatars in your applications. ## Authentication All endpoints require authentication using a Bearer token (IWY_SERVICE_API_KEY). You can find your API key at [app.iwy.ai/settings](https://app.iwy.ai/settings). ## Base URL ``` https://api.iwy.ai/v1 ``` version: 1.0.0 contact: name: iwy Support url: https://www.iwy.ai/contact servers: - url: https://api.iwy.ai/v1 description: Production server security: - bearerAuth: [] tags: - name: Ephemeral Agents description: Create one-time use agents with automatic expiration - name: Agents description: Manage AI agents and their configurations - name: Tools description: Manage custom tools and functions for agents - name: Sessions description: Start and manage agent video call sessions paths: /ephemeral-agent: post: tags: - Ephemeral Agents summary: Create ephemeral agent description: | Creates a one-time use agent with automatic expiration. Ephemeral agents are more appropiate for use cases where you want to spin up an customized agent without persisting it long-term in the iwy dashboard. Ephemeral agents won't appear in the dashboard. The agent will automatically expire after a specified time to live (TTL). operationId: createEphemeralAgent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateEphemeralAgentRequest' example: configuration: llm: model: gemini-2.0-flash provider: google system_prompt: You are a helpful assistant for a product demo first_message: Welcome to the demo! How can I help you today? tts: provider: elevenlabs voice_id: 21m00Tcm4TlvDq8ikWAM video: provider: binary character_id: '0001' responses: '201': description: Ephemeral agent created successfully content: application/json: schema: $ref: '#/components/schemas/EphemeralAgentResponse' example: agent: id: 550e8400-e29b-41d4-a716-446655440099 expires_at: '2025-01-15T10:30:00.000Z' created_at: '2025-01-15T10:20:00.000Z' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '500': $ref: '#/components/responses/InternalServerError' components: schemas: CreateEphemeralAgentRequest: type: object description: Request to create a one-time use ephemeral agent required: - configuration properties: configuration: $ref: '#/components/schemas/AgentConfiguration' description: Agent configuration (same as regular agents) ttl_seconds: type: integer description: Time-to-live in seconds. The agent will expire after this duration. default: 300 minimum: 60 maximum: 86400 example: 600 metadata: type: object description: Optional metadata for tracking or internal use additionalProperties: true example: purpose: product_demo campaign: summer_2025 EphemeralAgentResponse: type: object description: Response containing the created ephemeral agent details required: - agent properties: agent: type: object description: The created ephemeral agent required: - id - expires_at - created_at properties: id: type: string format: uuid description: >- Unique identifier for the ephemeral agent. Use this ID in your frontend widget. example: 550e8400-e29b-41d4-a716-446655440099 expires_at: type: string format: date-time description: ISO 8601 timestamp when the agent will expire example: '2025-01-15T10:30:00.000Z' created_at: type: string format: date-time description: ISO 8601 timestamp when the agent was created example: '2025-01-15T10:20:00.000Z' AgentConfiguration: type: object description: Agent behavior and capabilities configuration required: - llm - stt - tts - video properties: llm: type: object description: Large Language Model configuration required: - model - provider - system_prompt - first_message properties: model: type: string description: LLM model name example: gemini-2.0-flash provider: type: string description: LLM provider example: google system_prompt: type: string description: Instructions defining the agent's personality and behavior example: You are a helpful customer service assistant first_message: type: string description: Initial greeting message example: Hello! How can I help you today? voice: type: string description: Voice identifier for the LLM (if supported) custom_url: type: string description: Custom API endpoint URL cost_per_minute: type: number format: float description: Cost per minute of LLM usage example: 0.001532 stt: type: object description: Speech-to-Text configuration required: - model - provider properties: model: type: string description: STT model name example: nova-3-general provider: type: string description: STT provider example: deepgram cost_per_minute: type: number format: float description: Cost per minute of STT usage example: 0.01 tts: type: object description: Text-to-Speech configuration required: - provider - voice_id properties: provider: type: string description: TTS provider example: elevenlabs voice_id: type: string description: Voice identifier example: 21m00Tcm4TlvDq8ikWAM cost_per_minute: type: number format: float description: Cost per minute of TTS usage example: 0.03 video: type: object description: Video avatar configuration required: - provider - character_id properties: provider: type: string description: Video provider example: binary character_id: type: string description: Avatar character identifier example: '0001' cost_per_minute: type: number format: float description: Cost per minute of video usage example: 0 tool_calling: type: object description: Tool integration configuration properties: selected_tool_ids: type: array description: Array of tool IDs this agent can use items: type: string format: uuid example: - dcfae097-1b37-4444-bb0c-1a6abb0320fd end_of_conversation: type: object description: Configuration for conversation end events properties: callback_url: type: string format: uri description: URL to send callback when conversation ends send_data_on_end: type: boolean description: Whether to send conversation data on end default: false Error: type: object required: - success - error properties: success: type: boolean example: false error: type: string description: Error message example: Parameter validation failed details: description: Additional error details oneOf: - type: string - type: object execution_time_ms: type: integer description: Execution time before error occurred responses: BadRequestError: description: Invalid request - validation failed content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: Bad request details: 'Missing required field: name' UnauthorizedError: description: Authentication failed - invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: Unauthorized details: Invalid or missing API key InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: Internal server error details: An unexpected error occurred securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Your iwy Service API Key. Find it at [app.iwy.ai/settings](https://app.iwy.ai/settings). Include it in the Authorization header: ``` Authorization: Bearer YOUR_API_KEY ``` ````