Skip to main content
POST
/
v1
/
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
{
  "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"
}
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..."
  }'

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

​
functionTool
object

Required when type is FUNCTION_TOOL.

​
preExecutionMessage
string

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

​
metaData
object

Response

Tool created.

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