Vantax AIDocs
POST

Create Custom Tool

Defines a new custom tool the Agent can call to reach one of your HTTP endpoints.

POSThttps://api.vantaxai.com/v1/custom-tools

A custom tool teaches the Agent how to call your API. The `schema` is a JSON Schema describing the input parameters the Agent must collect from the conversation — its `properties` become the tool's arguments and `required` lists the ones that must be present. When the Agent decides to use the tool, it gathers those arguments, then issues an `http_method` request to your `endpoint_url` with the arguments as the JSON body (or query string for GET). Any `headers` you define (such as an API key for your backend) are sent on every request. Your endpoint's JSON response is fed back to the Agent, which uses it to continue the conversation. See the execution example below for the exact payload shape.

Tool execution example

When the Agent decides to use this tool mid-conversation it emits a tool call, VantaX issues the request to your endpoint_url, and your response is returned to the Agent. Example tool call: { "tool_call_id": "call_4f8a21", "name": "check_order_status", "arguments": { "order_number": "ORD-10482", "email": "sam@acme.com" } } VantaX POSTs {"order_number":"ORD-10482","email":"sam@acme.com"} (plus your configured headers) to https://api.acme-store.com/orders/lookup. Your endpoint replies, e.g. {"status":"shipped","carrier":"UPS","eta":"2026-01-16"}, and that result is fed back to the Agent so it can tell the caller the order has shipped via UPS, arriving Jan 16.

Attaching the tool to an Agent

Creating a tool only defines it. Attach it to an Agent with the Agent Tools API for the Agent to actually be able to call it during calls and conversations.

Headers

  • Authorizationstringrequired

    Bearer authentication with your secret API key.

    example: Bearer vx_live_3fa9c2…

  • Content-Typestringrequired

    Must be application/json for requests with a body.

    example: application/json

Body Parameters

  • namestringrequired

    Machine-friendly tool name the Agent uses to invoke it (snake_case recommended).

    example: check_order_status

  • schemaobjectrequired

    JSON Schema describing the tool's input parameters. Must be type `object` with `properties` and an optional `required` array. Each property's `description` guides the Agent on what value to extract from the conversation.

  • endpoint_urlstringrequired

    The HTTPS URL the Agent calls when it invokes this tool.

    example: https://api.acme-store.com/orders/lookup

  • sub_account_idstringrequired

    Sub-account that will own the tool.

    example: sub_8a1f4c2e

  • descriptionstringoptional

    Natural-language explanation of what the tool does and when to use it. The Agent reads this to decide whether to call the tool.

    example: Look up the current status of a customer order by order number.

  • http_methodstringoptional

    HTTP method used to call the endpoint. Defaults to POST.

    GETPOSTPATCHPUTDELETE

    example: POST

  • headersobjectoptional

    Static headers sent with every call to your endpoint — e.g. an authorization header for your own backend.

Request

curl -X POST https://api.vantaxai.com/v1/custom-tools \
  -H "Authorization: Bearer vx_live_3fa9c2..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "check_order_status",
    "description": "Look up the current status of a customer order by order number.",
    "endpoint_url": "https://api.acme-store.com/orders/lookup",
    "http_method": "POST",
    "headers": { "X-Api-Key": "acme_sk_9f2a..." },
    "sub_account_id": "sub_8a1f4c2e",
    "schema": {
      "type": "object",
      "properties": {
        "order_number": {
          "type": "string",
          "description": "The customer'\''s order number, e.g. ORD-10482."
        },
        "email": {
          "type": "string",
          "description": "Email on file for verification."
        }
      },
      "required": ["order_number"]
    }
  }'

Response

{
  "success": true,
  "message": "Custom tool created successfully",
  "data": {
    "id": "tool_7b2e91",
    "name": "check_order_status",
    "description": "Look up the current status of a customer order by order number.",
    "schema": {
      "type": "object",
      "properties": {
        "order_number": {
          "type": "string",
          "description": "The customer's order number, e.g. ORD-10482."
        },
        "email": {
          "type": "string",
          "description": "Email on file for verification."
        }
      },
      "required": ["order_number"]
    },
    "endpoint_url": "https://api.acme-store.com/orders/lookup",
    "http_method": "POST",
    "sub_account_id": "sub_8a1f4c2e",
    "created_at": "2026-01-14T10:30:00Z"
  }
}