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

# Create Agent

> Create a new agent.

Optionally include an initial voice configuration and tool attachments
in the same request.



## OpenAPI

````yaml /openapi.json post /agents
openapi: 3.1.0
info:
  title: Kejue Public API
  description: >-
    The Kejue Public API lets you programmatically create calls, manage
    campaigns, and retrieve call results.


    ## Authentication


    All requests require an API key passed in the `X-API-Key` header:


    ```

    X-API-Key: kej_live_...

    ```


    API keys are scoped to a workspace. Create and manage keys from the Kejue
    dashboard under **Settings → API Keys**.


    ## Base URL


    ```

    https://api.kejue.co/api/v1

    ```


    ## Rate Limits


    API requests are rate-limited per workspace. If you exceed the limit you'll
    receive a `429 Too Many Requests` response.


    ## Errors


    All error responses follow a consistent format:


    ```json

    {
      "error": "Human-readable message",
      "code": "ERROR_CODE",
      "details": {}
    }

    ```
  version: 1.0.0
servers:
  - url: https://api.kejue.co/api/v1
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Agents
    description: >-
      Create and manage AI agents (personas). Each agent has a name, prompt,
      voice configuration, and optional tools. Agents are the core building
      block — attach voice configs, tools, and use them to make calls.
  - name: Calls
    description: >-
      Create outbound calls, retrieve call details and transcripts, and list
      calls with filtering. Each call is associated with a contact and
      optionally an agent and campaign.
  - name: Persona Calls
    description: >-
      Create calls with the full agent configuration pre-loaded. Applies the
      complete settings hierarchy (workspace → agent → campaign → overrides)
      with all agent tools, tags, scoring, and webhooks inherited automatically.
  - name: Contacts
    description: >-
      Create and manage contacts. Contacts represent the people your agents
      call. Each contact has a phone number, name, and optional metadata.
      Supports single creation, bulk import, and CSV upload.
  - name: Campaigns
    description: >-
      Create and manage calling campaigns. Campaigns let you batch-call a list
      of contacts with shared settings, scheduling, and retry logic.
  - name: Tools
    description: >-
      Create and manage custom HTTP tools that agents can invoke during calls.
      Tools let agents fetch data, trigger actions, or integrate with external
      systems mid-conversation.


      Each tool supports three parameter types:

      - **Dynamic parameters** — filled by the AI at runtime (visible to the AI)

      - **Static parameters** — fixed values sent with every invocation (hidden
      from the AI)

      - **System parameters** — values injected from the execution context at
      runtime, such as `call_id`, `contact_id`, or `workspace_id` (hidden from
      the AI)
  - name: Voices
    description: List available voices for use in agent voice configurations.
  - name: Phone Numbers
    description: List phone numbers available in your workspace for making outbound calls.
  - name: Webhooks
    description: >-
      Create and manage webhook subscriptions. Receive real-time notifications
      for call events (started, ended, etc.) at your specified URL.
  - name: Models
    description: List available AI models for use in agent voice configurations.
paths:
  /agents:
    post:
      tags:
        - Agents
      summary: Create Agent
      description: |-
        Create a new agent.

        Optionally include an initial voice configuration and tool attachments
        in the same request.
      operationId: create_agent_agents_post
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgent'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '401':
          description: >-
            Missing or invalid API key. Pass a workspace API key in the
            `X-API-Key` header.
          content:
            application/json:
              example:
                error: Invalid or missing API key
                code: UNAUTHORIZED
                details: {}
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The workspace's plan limit on agents has been reached.
          content:
            application/json:
              example:
                error: Agent limit reached for your plan
                code: FORBIDDEN
                details: {}
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Another agent in this workspace already uses this name.
          content:
            application/json:
              example:
                error: An agent with this name already exists
                code: CONFLICT
                details: {}
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request body or query parameters failed validation.
          content:
            application/json:
              example:
                error: Validation failed
                code: VALIDATION_ERROR
                details:
                  errors:
                    - field: body.name
                      message: Field required
                      type: missing
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateAgent:
      properties:
        name:
          type: string
          maxLength: 255
          minLength: 1
          title: Name
          description: Agent name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Agent description
        avatar:
          anyOf:
            - type: string
            - type: 'null'
          title: Avatar
          description: Avatar URL
        memory_enabled:
          type: boolean
          title: Memory Enabled
          description: Enable contact memory across conversations
          default: true
        call_settings:
          anyOf:
            - $ref: '#/components/schemas/CallSettingsInput'
            - type: 'null'
          description: Call settings — call window, retry, scoring, tags, post-call
        voice_config:
          anyOf:
            - $ref: '#/components/schemas/VoiceConfigInput'
            - type: 'null'
          description: Initial voice configuration
        tools:
          anyOf:
            - items:
                $ref: '#/components/schemas/AgentToolAttach'
              type: array
            - type: 'null'
          title: Tools
          description: Tools to attach to this agent
      type: object
      required:
        - name
      title: CreateAgent
      description: Create an agent (persona).
    AgentResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        is_active:
          type: boolean
          title: Is Active
        memory_enabled:
          type: boolean
          title: Memory Enabled
        call_settings:
          anyOf:
            - $ref: '#/components/schemas/CallSettingsInput'
            - type: 'null'
        voice_configs:
          items:
            $ref: '#/components/schemas/VoiceConfigResponse'
          type: array
          title: Voice Configs
        tools:
          items:
            $ref: '#/components/schemas/AgentToolResponse'
          type: array
          title: Tools
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated At
      type: object
      required:
        - id
        - name
        - is_active
        - memory_enabled
      title: AgentResponse
      description: Full agent (persona) response (public-safe).
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
        code:
          type: string
          title: Code
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
      type: object
      required:
        - error
        - code
      title: ErrorResponse
      description: Standard error response.
      example:
        code: NOT_FOUND
        details:
          contact_id: '123'
        error: Contact not found
    CallSettingsInput:
      properties:
        call_start_hour:
          anyOf:
            - type: integer
              maximum: 23
              minimum: 0
            - type: 'null'
          title: Call Start Hour
          description: 'Earliest hour to call (0-23, contact timezone). Default: 9'
        call_start_minute:
          anyOf:
            - type: integer
              maximum: 59
              minimum: 0
            - type: 'null'
          title: Call Start Minute
          description: 'Earliest minute. Default: 0'
        call_end_hour:
          anyOf:
            - type: integer
              maximum: 23
              minimum: 0
            - type: 'null'
          title: Call End Hour
          description: 'Latest hour to call (0-23). Default: 18'
        call_end_minute:
          anyOf:
            - type: integer
              maximum: 59
              minimum: 0
            - type: 'null'
          title: Call End Minute
          description: 'Latest minute. Default: 0'
        allowed_days:
          anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
          title: Allowed Days
          description: >-
            Days of the week to call. 0=Monday, 6=Sunday. Default: [0,1,2,3,4]
            (Mon-Fri)
        auto_retry:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Auto Retry
          description: 'Retry when contact doesn''t answer. Default: true'
        retry_schedule:
          anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
          title: Retry Schedule
          description: >-
            Minutes between retries, e.g. [60, 240] = retry after 1h, then 4h.
            Default: [60, 240]
        phone_assignment_mode:
          anyOf:
            - $ref: '#/components/schemas/PhoneAssignmentMode'
            - type: 'null'
          description: >-
            How to pick the origin phone number. 'local' = match contact's
            country, 'foreign' = use a different country, 'any' = no preference.
            Default: 'any'
        scoring_criteria:
          anyOf:
            - type: string
            - type: 'null'
          title: Scoring Criteria
          description: >-
            Free-text instructions for scoring the call 0-100. Example: 'Score
            based on buying intent and engagement level'
        tags:
          anyOf:
            - items:
                $ref: '#/components/schemas/TagDefinition'
              type: array
            - type: 'null'
          title: Tags
          description: Tag definitions -- AI applies matching tags after the call
        structured_data_schema:
          anyOf:
            - items:
                $ref: '#/components/schemas/StructuredDataField'
              type: array
            - type: 'null'
          title: Structured Data Schema
          description: Fields to extract from the conversation after the call
        server_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Server Url
          description: URL to POST call events to (simple inline webhook)
        server_secret:
          anyOf:
            - type: string
            - type: 'null'
          title: Server Secret
          description: HMAC-SHA256 signing secret for server_url
      type: object
      title: CallSettingsInput
      description: >-
        Unified call settings -- controls call window, retry, scoring, tags, and
        post-call behavior.


        Can be set at agent level or campaign level. Null fields inherit from
        the parent level.

        Hierarchy (lowest -> highest priority): System Defaults -> Workspace ->
        Agent -> Campaign -> API Override.
      example:
        allowed_days:
          - 0
          - 1
          - 2
          - 3
          - 4
        auto_retry: true
        call_end_hour: 17
        call_start_hour: 9
        phone_assignment_mode: local
        retry_schedule:
          - 60
          - 240
        scoring_criteria: Score 0-100 based on buying intent
        structured_data_schema:
          - description: Stated budget range
            key: budget
          - description: Decision timeline
            key: timeline
        tags:
          - description: Contact expressed buying interest
            name: Interested
          - description: Contact requested a follow-up call
            name: Follow-up
    VoiceConfigInput:
      properties:
        language_locale:
          type: string
          title: Language Locale
          description: BCP-47 locale, e.g. 'en-US', 'ar-AE'
        name:
          type: string
          title: Name
          description: Agent display name for this locale
        prompt:
          type: string
          title: Prompt
          description: System prompt / instructions for the agent
        first_speaker:
          $ref: '#/components/schemas/FirstSpeaker'
          description: Who speaks first
          default: agent
        first_message:
          anyOf:
            - type: string
            - type: 'null'
          title: First Message
          description: Agent's opening message
        first_message_uninterruptible:
          type: boolean
          title: First Message Uninterruptible
          description: Prevent user from interrupting the first message
          default: false
        first_message_delay_ms:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: First Message Delay Ms
          description: Delay before first message in ms
        voice_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice Id
          description: Voice ID (from GET /voices)
        model:
          anyOf:
            - $ref: '#/components/schemas/Model'
            - type: 'null'
          description: Voice AI model override
        temperature:
          anyOf:
            - type: number
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Temperature
          description: Model temperature
        recording_enabled:
          type: boolean
          title: Recording Enabled
          description: Record the call
          default: true
        inactivity_messages:
          anyOf:
            - items:
                $ref: '#/components/schemas/InactivityMessage'
              type: array
            - type: 'null'
          title: Inactivity Messages
          description: Messages the agent sends after periods of user silence
        silence_timeout:
          anyOf:
            - type: integer
              maximum: 120
              minimum: 5
            - type: 'null'
          title: Silence Timeout
          description: Silence timeout in seconds
        max_duration:
          anyOf:
            - type: integer
              maximum: 7200
              minimum: 30
            - type: 'null'
          title: Max Duration
          description: Max call duration in seconds
        is_default:
          type: boolean
          title: Is Default
          description: Set as the default voice config for this agent
          default: false
        config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Config
          exclude_from_public: true
      type: object
      required:
        - language_locale
        - name
        - prompt
      title: VoiceConfigInput
      description: Voice configuration for an agent.
    AgentToolAttach:
      properties:
        tool_name:
          type: string
          title: Tool Name
          description: Tool name — custom tool name or builtin name
        tool_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Id
          description: Tool ID — required for custom HTTP tools
        channels:
          items:
            type: string
          type: array
          title: Channels
          description: >-
            Channels where the tool is active: 'voice:in-call',
            'voice:post-call', 'whatsapp'
          default:
            - voice:in-call
        config:
          additionalProperties: true
          type: object
          title: Config
          description: >-
            Tool-specific configuration. The shape depends on the tool — see the
            Tools guide for the full schema of each builtin.


            **Examples for selected builtins:**


            `agent_transfer` — transfer the live call to a different persona:

            ```json

            {
              "targets": [
                {
                  "key": "billing",
                  "persona_id": "<persona-uuid>",
                  "voice_config_id": "<voice-config-uuid>",
                  "when_to_use": "Caller has questions about invoices, refunds, or payments."
                },
                {
                  "key": "tech_support",
                  "persona_id": "<persona-uuid>",
                  "when_to_use": "Caller is reporting a technical issue with the product."
                }
              ]
            }

            ```


            `create_call` — create a new outbound call from inside a
            conversation:

            ```json

            {
              "default_persona_id": "<persona-uuid>",
              "default_context": "Follow-up call about the contact's inquiry.",
              "allow_persona_override": false
            }

            ```
      type: object
      required:
        - tool_name
      title: AgentToolAttach
      description: Attach a tool to an agent.
    VoiceConfigResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        language_locale:
          type: string
          title: Language Locale
        prompt:
          type: string
          title: Prompt
        first_speaker:
          type: string
          title: First Speaker
        first_message:
          anyOf:
            - type: string
            - type: 'null'
          title: First Message
        first_message_uninterruptible:
          type: boolean
          title: First Message Uninterruptible
          default: false
        first_message_delay_ms:
          anyOf:
            - type: integer
            - type: 'null'
          title: First Message Delay Ms
        voice_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice Id
        voice_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Voice Name
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
        temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature
        recording_enabled:
          type: boolean
          title: Recording Enabled
        inactivity_messages:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Inactivity Messages
        silence_timeout:
          type: integer
          title: Silence Timeout
        max_duration:
          type: integer
          title: Max Duration
        corpus_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Corpus Id
        is_default:
          type: boolean
          title: Is Default
        is_active:
          type: boolean
          title: Is Active
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
        updated_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Updated At
      type: object
      required:
        - id
        - name
        - language_locale
        - prompt
        - first_speaker
        - recording_enabled
        - silence_timeout
        - max_duration
        - is_default
        - is_active
      title: VoiceConfigResponse
      description: Voice configuration in API responses (public-safe).
    AgentToolResponse:
      properties:
        tool_name:
          type: string
          title: Tool Name
        tool_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Tool Id
        channels:
          items:
            type: string
          type: array
          title: Channels
        config:
          additionalProperties: true
          type: object
          title: Config
      type: object
      required:
        - tool_name
        - channels
        - config
      title: AgentToolResponse
      description: A tool attached to an agent.
    PhoneAssignmentMode:
      type: string
      enum:
        - local
        - foreign
        - any
      title: PhoneAssignmentMode
      description: How to assign the origin phone number.
    TagDefinition:
      properties:
        name:
          type: string
          title: Name
          description: Tag label, e.g. 'Interested'
        description:
          type: string
          title: Description
          description: When to apply this tag -- the AI uses this to decide
      type: object
      required:
        - name
        - description
      title: TagDefinition
      description: A tag that can be applied to a call based on conversation content.
    StructuredDataField:
      properties:
        key:
          type: string
          title: Key
          description: Output field key, e.g. 'budget'
        description:
          type: string
          title: Description
          description: What to extract from the conversation
      type: object
      required:
        - key
        - description
      title: StructuredDataField
      description: A field to extract from the conversation after the call.
    FirstSpeaker:
      type: string
      enum:
        - agent
        - user
      title: FirstSpeaker
      description: Who speaks first in the call.
    Model:
      type: string
      enum:
        - KJUE-v0
        - KJUE-v0-mini
        - KJUE-v0-large
        - KJUE-v1.0
      title: Model
      description: Available voice AI models.
    InactivityMessage:
      properties:
        message:
          type: string
          title: Message
          description: Text the agent will speak after the delay
        delay_seconds:
          type: integer
          maximum: 120
          minimum: 1
          title: Delay Seconds
          description: Seconds of silence before sending this message
        end_behavior:
          anyOf:
            - type: string
            - type: 'null'
          title: End Behavior
          description: >-
            What to do after speaking this message. One of
            END_BEHAVIOR_UNSPECIFIED, END_BEHAVIOR_HANG_UP_SOFT,
            END_BEHAVIOR_HANG_UP_STRICT. Maps to Ultravox endBehavior.
      type: object
      required:
        - message
        - delay_seconds
      title: InactivityMessage
      description: A message the agent sends after a period of silence from the user.
      example:
        delay_seconds: 15
        end_behavior: END_BEHAVIOR_UNSPECIFIED
        message: Are you still there?
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Workspace API key (e.g. `kej_live_...`)

````