> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lehar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create agent

> Creates a draft agent. `id` is client-supplied. Prompt fields support `{{placeholders}}` filled from session `custom_variables`. Scope `sessions:write`.



## OpenAPI

````yaml /api-reference/openapi.json post /agent
openapi: 3.1.0
info:
  title: Lehar API
  version: v0
  description: >-
    Customer-facing REST API for the Lehar voice-AI platform. Platform-admin
    endpoints are intentionally excluded from this reference. Regenerate with
    `npm run sync:openapi`.
servers:
  - url: https://api.lehar.ai/ca/api/v0
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /agent:
    post:
      tags:
        - Agents
      summary: Create agent
      description: >-
        Creates a draft agent. `id` is client-supplied. Prompt fields support
        `{{placeholders}}` filled from session `custom_variables`. Scope
        `sessions:write`.
      operationId: create_agent_ca_api_v0_agent_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: string
                  description: 'Client-supplied agent id (alias: `agent_id`).'
                name:
                  type: string
                  description: Required before the agent can be published.
                objective:
                  type: string
                instruction:
                  type: string
                task:
                  type: string
                faqs:
                  type: string
                sample_conversations:
                  type: string
                channel:
                  type: string
                  enum:
                    - voice
                    - whatsapp
                  default: voice
                custom_variables:
                  type: array
                  items:
                    type: string
                config:
                  type: object
                  description: >-
                    Provider selection and per-agent settings (see Providers &
                    Models).
                tools:
                  type: array
                  items:
                    type: string
                questionnaire:
                  type: object
            example:
              id: agent_sales_hi
              name: Sales Agent
              objective: You are a sales assistant for {{company}}.
              instruction: Be polite, concise, and never invent prices.
              task: Qualify the lead and book a callback.
              custom_variables:
                - callee_name
                - company
              config:
                llm_provider: gemini
                tts_provider: sarvam
                voice: anushka
              tools: []
      responses:
        '201':
          description: Created agent (status `draft`)
          content:
            application/json:
              example:
                id: agent_sales_hi
                name: Sales Agent
                objective: You are a sales assistant for {{company}}.
                instruction: Be polite, concise, and never invent prices.
                task: Qualify the lead and book a callback.
                faqs: null
                sample_conversations: null
                channel: voice
                config:
                  llm_provider: gemini
                  tts_provider: sarvam
                  voice: anushka
                tools: []
                custom_variables:
                  - callee_name
                  - company
                questionnaire: null
                template_agent_id: null
                customer_id: customer_01EXAMPLE
                owner_user_id: user_01EXAMPLE
                created_by_user_id: user_01EXAMPLE
                visibility: private
                status: draft
                published_at: null
                created_at: '2026-05-22T10:00:00Z'
                updated_at: '2026-05-22T10:00:00Z'
        '409':
          description: An agent with this id already exists
          content:
            application/json:
              example:
                error:
                  code: conflict
                  message: Agent already exists
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    BearerAuth:
      type: http
      scheme: bearer

````