> ## 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. # Get agent by ID > Returns the complete configuration for a specific agent, including all settings for LLM, STT, TTS, video, and tool integrations. ## OpenAPI ````yaml get /agent/{id} 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: /agent/{id}: get: tags: - Agents summary: Get agent by ID description: | Returns the complete configuration for a specific agent, including all settings for LLM, STT, TTS, video, and tool integrations. operationId: getAgent parameters: - $ref: '#/components/parameters/AgentId' responses: '200': description: Agent retrieved successfully content: application/json: schema: $ref: '#/components/schemas/Agent' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/NotFoundError' '500': $ref: '#/components/responses/InternalServerError' components: parameters: AgentId: name: id in: path required: true description: The unique identifier (UUID) of the agent schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 schemas: Agent: type: object description: Complete agent configuration required: - id - user_id - name - configuration properties: id: type: string format: uuid description: Unique identifier for the agent user_id: type: string format: uuid description: ID of the user who owns this agent name: type: string description: Human-readable name of the agent publish_status: type: string enum: - draft - private - public description: | Visibility and accessibility status: - `draft`: In development, not accessible - `private`: Active but not publicly discoverable - `public`: Fully active and discoverable default: draft configuration: $ref: '#/components/schemas/AgentConfiguration' metadata: type: object description: Additional metadata for internal use additionalProperties: true 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: 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 NotFoundError: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: Not found details: The requested resource does not exist 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 ``` ````