> ## Documentation Index > Fetch the complete documentation index at: https://docs.eclatira.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an agent > Creates an agent. Telephony credentials (twilio_config.auth_token, telnyx_config.api_key/public_key) are write-only: never returned by this or any other v1 agent response. No live Twilio/Telnyx verification or inbound-routing registration happens here: an agent created this way can place outbound calls immediately, but won't receive inbound calls until it's also verified via the dashboard. Pass an `Idempotency-Key` header to safely retry this request. ## OpenAPI ````yaml /openapi.json post /api/v1/agents openapi: 3.1.0 info: title: Eclatira API description: >- Programmatically create calls and batches, manage agents/tools/knowledge, and retrieve conversation analytics. contact: name: Eclatira Support email: contact@eclatira.com version: 1.0.0 servers: - url: https://app.eclatira.com description: API Server security: [] tags: - name: developer-api description: >- The API-key-authenticated developer surface: calls, batches, and agents. Authenticate with `Authorization: Bearer ek_...`. - name: Calls description: Place outbound calls with an agent, check status, list history. - name: Batches description: 'Outbound call campaigns: create, list, inspect, cancel, retry.' - name: Agents description: Create and manage the agents that place and receive calls. - name: Tools description: Custom actions an agent can call mid-call, attached per-agent. - name: MCP Servers description: >- Connect an agent to an external MCP (Model Context Protocol) server so it can call that server's tools, with static or OAuth auth. - name: Knowledge Base description: Upload files and index them into an agent's knowledge base. - name: Realtime description: >- Mint a short-lived session token to open a live voice/video WebSocket connection: the only supported way for an API-key holder to authenticate into /ws/{user_id}. - name: Webhooks description: >- Register a durable callback URL to receive call.completed and batch.completed events for every matching workspace event, and fetch the tenant signing secret used to verify X-Webhook-Signature. - name: developer-api-keys description: >- Account-management routes (create/list/revoke API keys), authenticated via dashboard login, not an API key, since they mint the credentials the rest of the developer API uses. paths: /api/v1/agents: post: tags: - Agents - developer-api summary: Create an agent description: |- Creates an agent. Telephony credentials (twilio_config.auth_token, telnyx_config.api_key/public_key) are write-only: never returned by this or any other v1 agent response. No live Twilio/Telnyx verification or inbound-routing registration happens here: an agent created this way can place outbound calls immediately, but won't receive inbound calls until it's also verified via the dashboard. Pass an `Idempotency-Key` header to safely retry this request. operationId: createAgent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/V1CreateAgentRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/V1AgentResponse' '402': description: >- The tenant's billing status blocks new agent creation (e.g. a past_due/unpaid subscription), or the tenant has reached its plan's agent limit. content: application/json: schema: $ref: '#/components/schemas/V1ErrorResponse' '422': content: application/json: schema: $ref: '#/components/schemas/V1ErrorResponse' description: Unprocessable Content security: - ApiKeyAuth: [] components: schemas: V1CreateAgentRequest: properties: name: type: string title: Name description: type: string title: Description instruction: type: string title: Instruction first_message: type: string title: First Message voice_id: anyOf: - type: string - type: 'null' title: Voice Id language: anyOf: - type: string - type: 'null' title: Language language_code: anyOf: - type: string - type: 'null' title: Language Code accent: anyOf: - type: string - type: 'null' title: Accent can_end_conversation: type: boolean title: Can End Conversation default: false transfer_phone_number: anyOf: - type: string - type: 'null' title: Transfer Phone Number transfer_criteria: anyOf: - type: string - type: 'null' title: Transfer Criteria variable_placeholders: additionalProperties: type: string type: object title: Variable Placeholders default: {} voicemail_config: anyOf: - $ref: '#/components/schemas/VoicemailConfig' - type: 'null' twilio_config: anyOf: - $ref: '#/components/schemas/V1AgentTwilioInput' - type: 'null' telnyx_config: anyOf: - $ref: '#/components/schemas/V1AgentTelnyxInput' - type: 'null' realtime: anyOf: - $ref: '#/components/schemas/V1AgentRealtimeInput' - type: 'null' additionalProperties: false type: object required: - name - description - instruction - first_message title: V1CreateAgentRequest V1AgentResponse: properties: agent_id: type: string title: Agent Id name: type: string title: Name description: type: string title: Description instruction: type: string title: Instruction first_message: type: string title: First Message voice_id: anyOf: - type: string - type: 'null' title: Voice Id language: anyOf: - type: string - type: 'null' title: Language language_code: anyOf: - type: string - type: 'null' title: Language Code accent: anyOf: - type: string - type: 'null' title: Accent can_end_conversation: type: boolean title: Can End Conversation default: false transfer_phone_number: anyOf: - type: string - type: 'null' title: Transfer Phone Number transfer_criteria: anyOf: - type: string - type: 'null' title: Transfer Criteria variable_placeholders: additionalProperties: type: string type: object title: Variable Placeholders default: {} voicemail_config: anyOf: - $ref: '#/components/schemas/VoicemailConfig' - type: 'null' telephony: $ref: '#/components/schemas/V1AgentTelephonyStatus' realtime: $ref: '#/components/schemas/V1AgentRealtimeStatus' created_at: anyOf: - type: string - type: 'null' title: Created At type: object required: - agent_id - name - description - instruction - first_message - telephony - realtime title: V1AgentResponse V1ErrorResponse: properties: error: $ref: '#/components/schemas/V1ErrorDetail' type: object required: - error title: V1ErrorResponse description: |- The error envelope every `developer-api`-tagged route returns for non-2xx responses, including `422`; this overrides FastAPI's default validation-error shape. VoicemailConfig: properties: enabled: type: boolean title: Enabled default: false message: anyOf: - type: string - type: 'null' title: Message detection_timeout_seconds: anyOf: - type: integer - type: 'null' title: Detection Timeout Seconds retry_on_voicemail: type: boolean title: Retry On Voicemail default: true type: object title: VoicemailConfig V1AgentTwilioInput: properties: account_sid: anyOf: - type: string - type: 'null' title: Account Sid auth_token: anyOf: - type: string format: password writeOnly: true - type: 'null' title: Auth Token phone_number: anyOf: - type: string - type: 'null' title: Phone Number additionalProperties: false type: object title: V1AgentTwilioInput V1AgentTelnyxInput: properties: api_key: anyOf: - type: string format: password writeOnly: true - type: 'null' title: Api Key phone_number: anyOf: - type: string - type: 'null' title: Phone Number connection_id: anyOf: - type: string - type: 'null' title: Connection Id account_sid: anyOf: - type: string - type: 'null' title: Account Sid public_key: anyOf: - type: string format: password writeOnly: true - type: 'null' title: Public Key additionalProperties: false type: object title: V1AgentTelnyxInput V1AgentRealtimeInput: properties: enable_webcam: anyOf: - type: boolean - type: 'null' title: Enable Webcam description: 'Allow `source: "camera"` realtime sessions. Omit to leave unchanged.' enable_screen_share: anyOf: - type: boolean - type: 'null' title: Enable Screen Share description: 'Allow `source: "screen"` realtime sessions. Omit to leave unchanged.' additionalProperties: false type: object title: V1AgentRealtimeInput description: |- Which realtime session sources this agent accepts. Both default to enabled. They gate `POST /api/v1/realtime/sessions` for `source: "camera"` and `source: "screen"`, and the embed widget's own controls, from the same stored setting — so turning one off here also removes the corresponding button from the widget. V1AgentTelephonyStatus: properties: twilio: $ref: '#/components/schemas/V1AgentTelephonyProviderStatus' telnyx: $ref: '#/components/schemas/V1AgentTelephonyProviderStatus' type: object required: - twilio - telnyx title: V1AgentTelephonyStatus V1AgentRealtimeStatus: properties: enable_webcam: type: boolean title: Enable Webcam description: 'Whether `source: "camera"` sessions are permitted.' enable_screen_share: type: boolean title: Enable Screen Share description: 'Whether `source: "screen"` sessions are permitted.' type: object required: - enable_webcam - enable_screen_share title: V1AgentRealtimeStatus description: The effective realtime capabilities of this agent. V1ErrorDetail: properties: type: type: string title: Type code: type: string title: Code message: type: string title: Message param: anyOf: - type: string - type: 'null' title: Param request_id: anyOf: - type: string - type: 'null' title: Request Id type: object required: - type - code - message title: V1ErrorDetail V1AgentTelephonyProviderStatus: properties: configured: type: boolean title: Configured phone_number: anyOf: - type: string - type: 'null' title: Phone Number inbound_enabled: type: boolean title: Inbound Enabled default: false type: object required: - configured title: V1AgentTelephonyProviderStatus securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- A long-lived, privileged API key (`ek_...` prefix), minted once from the dashboard. Intended for trusted server-side use only; never expose it in client-side code. Send as `Authorization: Bearer ek_...`. Required by every Calls, Batches, Agents, Tools, MCP Servers, Documents, and Realtime route. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.