> ## 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 Tool

> Create a new API webhook tool or server-side function tool.

<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>

## Code examples

<CodeGroup>
  ```bash curl (API tool) theme={null}
  curl -X POST https://api.agntix.ai/v1/chat/tools \
    -H "x-api-key: pk_live_••••" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "GET_ACCOUNT_BALANCE",
      "description": "Retrieves the current account balance for a customer. Call when the user asks about their balance or available credit.",
      "type": "API_TOOL",
      "apiTool": {
        "url": "https://api.acme.com/v1/accounts/{{customerId}}/balance",
        "method": "GET",
        "headers": { "Authorization": "Bearer sk_acme_••••" }
      },
      "ajvPropertiesSchema": {
        "type": "object",
        "properties": {
          "customerId": {
            "type": "string",
            "description": "The customer ID from the session metadata."
          }
        },
        "required": ["customerId"]
      },
      "preExecutionMessage": "Let me check your balance..."
    }'
  ```

  ```javascript Node.js (API tool) theme={null}
  const tool = await fetch('https://api.agntix.ai/v1/chat/tools', {
    method: 'POST',
    headers: {
      'x-api-key': 'pk_live_••••',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'GET_ACCOUNT_BALANCE',
      description: 'Retrieves the current account balance. Call when user asks about balance or available credit.',
      type: 'API_TOOL',
      apiTool: {
        url: 'https://api.acme.com/v1/accounts/{{customerId}}/balance',
        method: 'GET',
        headers: { Authorization: 'Bearer sk_acme_••••' },
      },
      ajvPropertiesSchema: {
        type: 'object',
        properties: {
          customerId: { type: 'string', description: 'Customer ID' },
        },
        required: ['customerId'],
      },
      preExecutionMessage: "Let me check your balance...",
    }),
  }).then(r => r.json());

  console.log('Created tool:', tool.id);
  ```

  ```python Python (API tool) theme={null}
  import httpx

  tool = httpx.post(
      "https://api.agntix.ai/v1/chat/tools",
      headers={"x-api-key": "pk_live_••••"},
      json={
          "name": "GET_ACCOUNT_BALANCE",
          "description": "Retrieves the current account balance. Call when user asks about their balance.",
          "type": "API_TOOL",
          "apiTool": {
              "url": "https://api.acme.com/v1/accounts/{{customerId}}/balance",
              "method": "GET",
              "headers": {"Authorization": "Bearer sk_acme_••••"},
          },
          "ajvPropertiesSchema": {
              "type": "object",
              "properties": {
                  "customerId": {"type": "string", "description": "Customer ID"}
              },
              "required": ["customerId"],
          },
          "preExecutionMessage": "Let me check your balance...",
      },
  ).json()

  print("Created tool:", tool["id"])
  ```
</CodeGroup>

## Creating a POST API tool with a request body

```bash curl theme={null}
curl -X POST https://api.agntix.ai/v1/chat/tools \
  -H "x-api-key: pk_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SUBMIT_SUPPORT_TICKET",
    "description": "Submits a new support ticket. Call when the user wants to raise an issue or complaint.",
    "type": "API_TOOL",
    "apiTool": {
      "url": "https://api.acme.com/v1/tickets",
      "method": "POST",
      "headers": { "Authorization": "Bearer sk_acme_••••", "Content-Type": "application/json" },
      "body": {
        "subject": "{{subject}}",
        "description": "{{description}}",
        "priority": "{{priority}}"
      }
    },
    "ajvPropertiesSchema": {
      "type": "object",
      "properties": {
        "subject": { "type": "string", "description": "Ticket subject" },
        "description": { "type": "string", "description": "Detailed issue description" },
        "priority": { "type": "string", "enum": ["low", "medium", "high"] }
      },
      "required": ["subject", "description"]
    }
  }'
```

## Sample response

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "GET_ACCOUNT_BALANCE",
  "description": "Retrieves the current account balance for a customer.",
  "type": "API_TOOL",
  "orgId": "org_2abc123",
  "createdAt": "2026-04-29T10:00:00Z",
  "updatedAt": "2026-04-29T10:00:00Z"
}
```

<Note>
  After creating a tool, attach it to an agent by including `{ "toolId": "<id>" }` in the `tools` array when [creating](/api-reference/agents/create) or [updating](/api-reference/agents/update) an agent.
</Note>


## OpenAPI

````yaml POST /v1/chat/tools
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:
  /v1/chat/tools:
    post:
      tags:
        - Tools
      summary: Create tool
      description: >-
        Creates a new tool. Provide either `apiTool` (for webhook-based tools)
        or `functionTool` (for server-side logic). The `ajvPropertiesSchema`
        defines the JSON Schema the LLM uses to construct the tool call.
      operationId: createTool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateToolRequest'
            example:
              name: GET_ACCOUNT_BALANCE
              description: >-
                Retrieves the current account balance for the authenticated
                customer.
              type: API_TOOL
              apiTool:
                url: https://api.acme.com/v1/accounts/{{customerId}}/balance
                method: GET
                headers:
                  Authorization: Bearer {{apiKey}}
              ajvPropertiesSchema:
                type: object
                properties:
                  customerId:
                    type: string
                    description: The customer's unique identifier.
                required:
                  - customerId
      responses:
        '201':
          description: Tool created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tool'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    CreateToolRequest:
      type: object
      required:
        - name
        - description
        - type
        - ajvPropertiesSchema
      properties:
        name:
          type: string
          pattern: ^[a-zA-Z0-9][a-zA-Z0-9_]*[a-zA-Z0-9]$
          description: >-
            Unique tool name. Alphanumeric with underscores, no leading/trailing
            underscore.
          example: GET_ACCOUNT_BALANCE
        description:
          type: string
          description: Explains to the LLM what this tool does and when to call it.
          example: >-
            Retrieves the current account balance for the authenticated
            customer.
        type:
          type: string
          enum:
            - API_TOOL
            - FUNCTION_TOOL
          description: >-
            `API_TOOL` = HTTP webhook call. `FUNCTION_TOOL` = server-side
            function.
        apiTool:
          type: object
          description: Required when `type` is `API_TOOL`.
          properties:
            url:
              type: string
              format: uri
            method:
              type: string
              enum:
                - GET
                - POST
                - PUT
                - PATCH
                - DELETE
            headers:
              type: object
              additionalProperties:
                type: string
            body:
              type: object
          required:
            - url
            - method
        functionTool:
          type: object
          description: Required when `type` is `FUNCTION_TOOL`.
          properties:
            functionName:
              type: string
        ajvPropertiesSchema:
          type: object
          description: >-
            JSON Schema for the tool's input parameters. The LLM uses this to
            construct the call.
          example:
            type: object
            properties:
              customerId:
                type: string
                description: Customer ID
            required:
              - customerId
        preExecutionMessage:
          type: string
          description: >-
            Message sent to the user before the tool executes (e.g. 'Let me look
            that up...').
        metaData:
          type: object
    Tool:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          example: GET_ACCOUNT_BALANCE
        description:
          type: string
        type:
          type: string
          enum:
            - API_TOOL
            - FUNCTION_TOOL
        ajvPropertiesSchema:
          type: object
        orgId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    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>`.'

````