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

# Create Agent

> Create a new AI agent for your organization.

<Note>
  Every endpoint on this page requires either a Clerk-issued JWT (`Authorization: Bearer <token>`) or
  an organization API key (`x-api-key: pk_…`). Anonymous calls return `401 Unauthorized`. See
  [Authentication](/authentication) for the full setup.
</Note>

<Note>
  Use [`GET /v1/chat/models`](/api-reference/generated/list-models) to get a valid `modelId` before creating an agent.
</Note>

## Code examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.agntix.ai/v2/chat/agents \
    -H "x-api-key: pk_live_••••" \
    -H "Content-Type: application/json" \
    -d '{
      "fullName": "Customer Support Bot",
      "description": "Handles tier-1 customer queries",
      "role": "You are a helpful, concise support agent for Acme Inc.",
      "language": "en",
      "systemPrompt": "You specialize in billing, returns, and account access. Keep responses under 3 sentences.",
      "modelId": "96f3b0a3-1234-5678-abcd-ef1234567890"
    }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://api.agntix.ai/v2/chat/agents', {
    method: 'POST',
    headers: {
      'x-api-key': 'pk_live_••••',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      fullName: 'Customer Support Bot',
      description: 'Handles tier-1 customer queries',
      role: 'You are a helpful, concise support agent for Acme Inc.',
      language: 'en',
      systemPrompt: 'You specialize in billing, returns, and account access.',
      modelId: '96f3b0a3-1234-5678-abcd-ef1234567890',
      tools: [{ toolId: '550e8400-e29b-41d4-a716-446655440000' }],
    }),
  });
  const agent = await res.json();
  console.log('Created agent:', agent.id);
  ```

  ```python Python theme={null}
  import httpx

  agent = httpx.post(
      "https://api.agntix.ai/v2/chat/agents",
      headers={"x-api-key": "pk_live_••••"},
      json={
          "fullName": "Customer Support Bot",
          "description": "Handles tier-1 customer queries",
          "role": "You are a helpful, concise support agent for Acme Inc.",
          "language": "en",
          "systemPrompt": "You specialize in billing, returns, and account access.",
          "modelId": "96f3b0a3-1234-5678-abcd-ef1234567890",
      },
  ).json()
  print("Created agent:", agent["id"])
  ```
</CodeGroup>

## Creating a voice agent

To create an agent capable of handling phone calls, add `voiceEnabled: true` and pick a `voicePipelineMode`:

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.agntix.ai/v2/chat/agents \
    -H "x-api-key: pk_live_••••" \
    -H "Content-Type: application/json" \
    -d '{
      "fullName": "Inbound Receptionist",
      "description": "Answers inbound calls and routes to the correct department",
      "role": "You are a professional phone receptionist for Acme Inc.",
      "language": "en",
      "modelId": "96f3b0a3-1234-5678-abcd-ef1234567890",
      "voiceEnabled": true,
      "voicePipelineMode": "pipeline",
      "sttModelId": "deepgram-nova-2-uuid",
      "ttsModelId": "eleven-turbo-uuid"
    }'
  ```

  ```javascript Node.js theme={null}
  const agent = await fetch('https://api.agntix.ai/v2/chat/agents', {
    method: 'POST',
    headers: {
      'x-api-key': 'pk_live_••••',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      fullName: 'Inbound Receptionist',
      description: 'Answers inbound calls and routes to the correct department',
      role: 'You are a professional phone receptionist for Acme Inc.',
      language: 'en',
      modelId: '96f3b0a3-1234-5678-abcd-ef1234567890',
      voiceEnabled: true,
      voicePipelineMode: 'pipeline',
      sttModelId: 'deepgram-nova-2-uuid',
      ttsModelId: 'eleven-turbo-uuid',
    }),
  }).then(r => r.json());
  ```
</CodeGroup>

## Sample response

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fullName": "Customer Support Bot",
  "description": "Handles tier-1 customer queries",
  "role": "You are a helpful, concise support agent for Acme Inc.",
  "language": "en",
  "systemPrompt": "You specialize in billing, returns, and account access.",
  "voiceEnabled": false,
  "isActive": true,
  "isPublic": false,
  "orgId": "org_2abc123",
  "modelId": "96f3b0a3-1234-5678-abcd-ef1234567890",
  "createdAt": "2026-04-29T08:00:00Z",
  "updatedAt": "2026-04-29T08:00:00Z"
}
```


## OpenAPI

````yaml POST /v2/chat/agents
openapi: 3.0.3
info:
  title: Agntix API
  version: 1.0.0
  description: >-
    The Agntix API lets you build, deploy, and operate AI chat and voice agents.
    All requests are sent to `https://api.agntix.ai`. Authenticate with an API
    key (`x-api-key`) or a Clerk-issued JWT (`Authorization: Bearer <token>`).


    Base URL: `https://api.agntix.ai`
servers:
  - url: https://api.agntix.ai
    description: Production
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Agents
    description: >-
      Create and manage AI agents — the core building block of Agntix. An agent
      encapsulates a system prompt, LLM, tools, knowledge store, and voice
      configuration.
  - name: Chat
    description: >-
      Open chat sessions with an agent and exchange messages. Supports streaming
      responses over SSE.
  - name: Voice
    description: >-
      List available voices and TTS/STT models, and create real-time voice
      sessions.
  - name: Tools
    description: >-
      Extend agent capabilities with API tools (webhook calls) or function tools
      (server-side logic).
  - name: Phone Numbers
    description: >-
      Provision and manage telephony numbers for inbound and outbound voice
      calls.
  - name: Models
    description: Browse available LLM, STT, and TTS models supported by Agntix.
  - name: Analytics
    description: Query call and agent-level performance metrics.
  - name: API Keys
    description: Create and manage organization-scoped API keys.
  - name: Contacts
    description: Manage customer contacts that can be linked to chat sessions.
  - name: Call Campaigns
    description: Launch and manage outbound call campaigns against a list of contacts.
  - name: Subscriptions
    description: View billing plans, usage quotas, and manage Stripe subscriptions.
paths:
  /v2/chat/agents:
    post:
      tags:
        - Agents
      summary: Create agent
      description: >-
        Creates a new AI agent for your organization. Use `modelId` from `GET
        /v1/chat/models` to select an LLM. Enable voice by setting
        `voiceEnabled: true` and specifying a `voicePipelineMode`.
      operationId: createAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
            example:
              fullName: Customer Support Bot
              description: Handles tier-1 customer queries
              role: >-
                You are a helpful, concise support agent for Acme Inc. Always
                greet the user by name if available.
              language: en
              systemPrompt: You specialize in billing, returns, and account access.
              modelId: 96f3b0a3-1234-5678-abcd-ef1234567890
              tools:
                - toolId: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '201':
          description: Agent created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
              example:
                id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                fullName: Customer Support Bot
                description: Handles tier-1 customer queries
                role: You are a helpful, concise support agent for Acme Inc.
                language: en
                voiceEnabled: false
                isActive: true
                isPublic: false
                orgId: org_2abc123
                createdAt: '2026-04-29T08:00:00Z'
                updatedAt: '2026-04-29T08:00:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    CreateAgentRequest:
      type: object
      required:
        - fullName
        - description
        - role
      properties:
        fullName:
          type: string
          description: Display name for the agent.
          example: Customer Support Bot
        description:
          type: string
          description: Internal description of the agent's purpose.
          example: Handles tier-1 customer queries for Acme Inc.
        role:
          type: string
          description: >-
            The agent's persona and behavioral role. Used as the system prompt
            prefix.
          example: You are a helpful, concise support agent for Acme Inc.
        language:
          type: string
          description: BCP-47 language code. Controls TTS voice language selection.
          example: en
        systemPrompt:
          type: string
          description: Additional system-level instructions appended to the role.
          example: >-
            You specialize in billing, returns, and account access. Keep
            responses under 3 sentences.
        specialInstructions:
          type: string
          description: >-
            Low-priority supplemental instructions (injected after system
            prompt).
        modelId:
          type: string
          format: uuid
          description: UUID of the LLM to use. Get IDs from `GET /v1/chat/models`.
        sttModelId:
          type: string
          format: uuid
          description: UUID of the Speech-to-Text model (voice agents only).
        ttsModelId:
          type: string
          format: uuid
          description: UUID of the Text-to-Speech model (voice agents only).
        voiceEnabled:
          type: boolean
          default: false
          description: Enable voice capability. Requires `voicePipelineMode` when `true`.
        voicePipelineMode:
          type: string
          enum:
            - pipeline
            - sts
            - hybrid
          description: >-
            Voice pipeline mode. `pipeline` = TTS+STT, `sts` = speech-to-speech,
            `hybrid` = adaptive.
        knowledgeStoreId:
          type: string
          description: ID of a knowledge store to attach for RAG-based answers.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/AgentTool'
          description: Tools to attach to the agent at creation time.
        welcomeAllowInterruptions:
          type: boolean
          description: >-
            Whether the welcome prompt can be interrupted by the user (voice
            only).
    Agent:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        fullName:
          type: string
          example: Customer Support Bot
        description:
          type: string
          example: Handles tier-1 customer queries
        role:
          type: string
          example: You are a helpful support agent for Acme Inc.
        language:
          type: string
          example: en
        systemPrompt:
          type: string
        voiceEnabled:
          type: boolean
          example: false
        voicePipelineMode:
          type: string
          nullable: true
        isActive:
          type: boolean
          example: true
        isPublic:
          type: boolean
          example: false
        orgId:
          type: string
          example: org_2abc123
        modelId:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
          example: '2026-04-28T11:42:11Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-04-28T11:42:11Z'
    AgentTool:
      type: object
      properties:
        toolId:
          type: string
          format: uuid
          description: UUID of an existing tool to attach.
          example: 550e8400-e29b-41d4-a716-446655440000
        toolDescription:
          type: string
          description: Optional context-specific description override for this agent.
      required:
        - toolId
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: NOT_FOUND
            message:
              type: string
              example: Resource not found.
            status:
              type: integer
              example: 404
        meta:
          type: object
          properties:
            requestId:
              type: string
            timestamp:
              type: string
              format: date-time
  responses:
    BadRequest:
      description: Invalid request body or parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: VALIDATION_ERROR
              message: fullName should not be empty
              status: 400
            meta:
              requestId: req_01j3m...
              timestamp: '2026-04-29T10:00:00Z'
    Unauthorized:
      description: Missing or invalid authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Authentication required.
              status: 401
            meta:
              requestId: req_01j3m...
              timestamp: '2026-04-29T10:00:00Z'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Organization API key. Obtain from the
        [dashboard](https://app.agntix.ai/settings/api-keys). Format:
        `pk_live_…`
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Clerk-issued JWT. Use `Authorization: Bearer <token>`.'

````