Create Tool

POST

chat

tools

Create tool

curl --request POST \
  --url https://api.agntix.ai/v1/chat/tools \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data @- <<EOF
{
  "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"
    ]
  }
}
EOF

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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']
    }
  })
};

fetch('https://api.agntix.ai/v1/chat/tools', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agntix.ai/v1/chat/tools"

payload = {
    "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"]
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "GET_ACCOUNT_BALANCE",
  "description": "<string>",
  "ajvPropertiesSchema": {},
  "orgId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "fullName should not be empty",
    "status": 400
  },
  "meta": {
    "requestId": "req_01j3m...",
    "timestamp": "2026-04-29T10:00:00Z"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required.",
    "status": 401
  },
  "meta": {
    "requestId": "req_01j3m...",
    "timestamp": "2026-04-29T10:00:00Z"
  }
}

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 for the full setup.

Code examples

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..."
  }'

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

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"])

Creating a POST API tool with a request body

curl

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

{
  "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"
}

After creating a tool, attach it to an agent by including { "toolId": "<id>" } in the tools array when creating or updating an agent.

Authorizations

x-api-key

string

header

required

Organization API key. Obtain from the dashboard. Format: pk_live_…

Body

application/json

name

string

required

Unique tool name. Alphanumeric with underscores, no leading/trailing underscore.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_]*[a-zA-Z0-9]$

Example:

"GET_ACCOUNT_BALANCE"

description

string

required

Explains to the LLM what this tool does and when to call it.

Example:

"Retrieves the current account balance for the authenticated customer."

type

enum<string>

required

API_TOOL = HTTP webhook call. FUNCTION_TOOL = server-side function.

Available options:

API_TOOL,

FUNCTION_TOOL

ajvPropertiesSchema

object

required

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"]
}

apiTool

object

Required when type is API_TOOL.

Show child attributes

functionTool

object

Required when type is FUNCTION_TOOL.

Show child attributes

preExecutionMessage

string

Message sent to the user before the tool executes (e.g. 'Let me look that up...').

metaData

object

Response

Tool created.

string<uuid>

name

string

Example:

"GET_ACCOUNT_BALANCE"

description

string

type

enum<string>

Available options:

API_TOOL,

FUNCTION_TOOL

ajvPropertiesSchema

object

orgId

string

createdAt

string<date-time>

updatedAt

string<date-time>

Create tool

curl --request POST \
  --url https://api.agntix.ai/v1/chat/tools \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data @- <<EOF
{
  "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"
    ]
  }
}
EOF

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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']
    }
  })
};

fetch('https://api.agntix.ai/v1/chat/tools', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agntix.ai/v1/chat/tools"

payload = {
    "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"]
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "GET_ACCOUNT_BALANCE",
  "description": "<string>",
  "ajvPropertiesSchema": {},
  "orgId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "fullName should not be empty",
    "status": 400
  },
  "meta": {
    "requestId": "req_01j3m...",
    "timestamp": "2026-04-29T10:00:00Z"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required.",
    "status": 401
  },
  "meta": {
    "requestId": "req_01j3m...",
    "timestamp": "2026-04-29T10:00:00Z"
  }
}

Overview

Agents

Chat

Voice

Tools

Phone Numbers

Code examples

Creating a POST API tool with a request body

Sample response

Authorizations

Body

Response

​Code examples

​Creating a POST API tool with a request body

​Sample response

Authorizations

Body

Response

Code examples

Creating a POST API tool with a request body

Sample response