Tools API - Ansa

Tools let your agent perform actions like calling APIs, displaying data, and collecting information through forms.

Endpoints

Method	Endpoint	Description
`GET`	`/tools`	List all tools for an agent
`GET`	`/tools/:id`	Get a specific tool
`GET`	`/tools/limits`	Get tool limits for current plan
`POST`	`/tools`	Create a new tool
`PUT`	`/tools/:id`	Update a tool
`DELETE`	`/tools/:id`	Delete a tool

List Tools

GET /tools?agentId={agentId}

Query Parameters

Parameter	Type	Required	Description
`agentId`	`string`	Yes	The agent ID to list tools for

Response

[
  {
    "id": "tool_abc123",
    "agentId": "agent_xyz789",
    "name": "get_order_status",
    "description": "Look up the status of a customer order",
    "executionType": "http",
    "inputSchema": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string",
          "description": "The order ID to look up"
        }
      },
      "required": ["order_id"]
    },
    "httpUrl": "https://api.example.com/orders/{order_id}",
    "httpMethod": "GET",
    "isEnabled": true,
    "createdAt": "2024-12-20T10:00:00.000Z",
    "updatedAt": "2024-12-20T10:00:00.000Z"
  }
]

Get Tool

GET /tools/{id}

Response

Returns the full tool object.

Get Tool Limits

GET /tools/limits?agentId={agentId}

Check how many tools you can create based on your plan.

Response

{
  "current": 3,
  "limit": 10,
  "planId": "starter",
  "canCreate": true
}

Field	Description
`current`	Number of tools currently created
`limit`	Maximum tools allowed (`null` = unlimited)
`planId`	Your current plan
`canCreate`	Whether you can create more tools

Create Tool

POST /tools

Request Body

{
  "agentId": "agent_xyz789",
  "name": "get_order_status",
  "description": "Look up the status of a customer order by order ID",
  "executionType": "http",
  "inputSchema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order ID to look up"
      }
    },
    "required": ["order_id"]
  },
  "httpUrl": "https://api.example.com/orders/{order_id}",
  "httpMethod": "GET",
  "httpHeaders": {
    "Authorization": "Bearer {{API_KEY}}"
  },
  "isEnabled": true
}

Parameters

Field	Type	Required	Description
`agentId`	`string`	Yes	Agent to add the tool to
`name`	`string`	Yes	Unique name (lowercase, underscores)
`description`	`string`	Yes	What the tool does (shown to AI)
`executionType`	`string`	Yes	`mock`, `http`, or `form`
`inputSchema`	`object`	Yes	JSON Schema for tool parameters
`isEnabled`	`boolean`	No	Whether tool is active (default: true)

HTTP Tool Fields

Field	Type	Description
`httpUrl`	`string`	URL to call (supports `{param}` placeholders)
`httpMethod`	`string`	`GET`, `POST`, `PUT`, or `DELETE`
`httpHeaders`	`object`	Headers to include in request

Form Tool Fields

Field	Type	Description
`formSchema`	`object`	Form field definitions
`formExecutionMode`	`string`	`webhook`, `client`, or `both`
`formWebhookUrl`	`string`	URL to send submissions
`formClientHandler`	`string`	Client-side handler name
`formPostActions`	`array`	Additional actions (Slack, email)

Mock Tool Fields

Field	Type	Description
`mockResponse`	`string`	Static response to return

Display Configuration

Field	Type	Description
`displayConfig`	`object`	How to render the tool result

Response

{
  "id": "tool_abc123",
  "agentId": "agent_xyz789",
  "name": "get_order_status",
  "description": "Look up the status of a customer order",
  "executionType": "http",
  "inputSchema": { ... },
  "httpUrl": "https://api.example.com/orders/{order_id}",
  "httpMethod": "GET",
  "httpHeaders": { ... },
  "isEnabled": true,
  "createdAt": "2024-12-20T10:00:00.000Z",
  "updatedAt": "2024-12-20T10:00:00.000Z"
}

Errors

Status	Code	Description
400	-	Invalid request body or duplicate name
403	`TOOL_LIMIT_REACHED`	Plan tool limit exceeded
404	-	Agent not found

Update Tool

PUT /tools/{id}

Request Body

Only include fields you want to update:

{
  "description": "Updated description",
  "httpUrl": "https://api.example.com/v2/orders/{order_id}",
  "isEnabled": false
}

Response

Returns the updated tool object.

Delete Tool

DELETE /tools/{id}

Response

{
  "success": true
}

Input Schema

The inputSchema defines what parameters the tool accepts. It follows JSON Schema format:

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "The order ID to look up"
    },
    "include_items": {
      "type": "boolean",
      "description": "Whether to include line items"
    }
  },
  "required": ["order_id"]
}

Property Types

Type	Description
`string`	Text input
`number`	Numeric value
`boolean`	True/false
`array`	List of values
`object`	Nested object

Enum Values

Restrict to specific values:

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Order status filter",
      "enum": ["pending", "shipped", "delivered"]
    }
  }
}

Display Config

Control how tool results are rendered in the widget:

{
  "displayConfig": {
    "type": "product_card",
    "fieldMappings": {
      "title": "name",
      "price": "price",
      "image": "imageUrl",
      "description": "description"
    },
    "options": {
      "showPrice": true,
      "showImage": true,
      "showAddToCart": true
    }
  }
}

Display Types

Type	Description
`text`	Plain text (default)
`product_card`	Single product card
`product_carousel`	Multiple products
`image`	Image display
`table`	Tabular data
`buttons`	Action buttons
`form`	Form display
`custom`	Custom template

Form Schema

For form tools, define fields with formSchema:

{
  "formSchema": {
    "fields": [
      {
        "name": "email",
        "label": "Email Address",
        "type": "email",
        "validation": {
          "required": { "value": true, "message": "Email is required" }
        }
      },
      {
        "name": "priority",
        "label": "Priority",
        "type": "select",
        "options": [
          { "label": "Low", "value": "low" },
          { "label": "Medium", "value": "medium" },
          { "label": "High", "value": "high" }
        ]
      }
    ],
    "submitLabel": "Submit",
    "successMessage": "Thanks for your submission!"
  }
}

Field Types

Type	Description
`text`	Single-line text
`email`	Email with validation
`tel`	Phone number
`number`	Numeric input
`textarea`	Multi-line text
`select`	Dropdown
`multiselect`	Multi-select dropdown
`date`	Date picker
`datetime`	Date and time
`file`	File upload
`image`	Image upload

Post Actions

Configure actions after form submission:

{
  "formPostActions": [
    {
      "type": "webhook",
      "url": "https://your-server.com/api/leads",
      "headers": {
        "Authorization": "Bearer xxx"
      }
    },
    {
      "type": "slack",
      "webhookUrl": "https://hooks.slack.com/services/xxx",
      "messageTemplate": "New lead: {{email}}"
    },
    {
      "type": "email",
      "recipientIds": ["user_123", "user_456"]
    }
  ]
}

Examples

HTTP Tool - Order Lookup

curl -X POST https://api.ansa.so/tools \
  -H "Authorization: Bearer $ANSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_xyz789",
    "name": "lookup_order",
    "description": "Look up order details by order number",
    "executionType": "http",
    "inputSchema": {
      "type": "object",
      "properties": {
        "order_number": {
          "type": "string",
          "description": "The order number (e.g., ORD-12345)"
        }
      },
      "required": ["order_number"]
    },
    "httpUrl": "https://api.mystore.com/orders/{order_number}",
    "httpMethod": "GET",
    "httpHeaders": {
      "X-API-Key": "your-api-key"
    }
  }'

Form Tool - Contact Form

curl -X POST https://api.ansa.so/tools \
  -H "Authorization: Bearer $ANSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_xyz789",
    "name": "contact_form",
    "description": "Collect contact information from visitors",
    "executionType": "form",
    "inputSchema": {
      "type": "object",
      "properties": {},
      "required": []
    },
    "formSchema": {
      "fields": [
        { "name": "name", "label": "Name", "type": "text" },
        { "name": "email", "label": "Email", "type": "email" },
        { "name": "message", "label": "Message", "type": "textarea" }
      ],
      "submitLabel": "Send Message"
    },
    "formExecutionMode": "webhook",
    "formWebhookUrl": "https://your-server.com/api/contacts"
  }'

​Endpoints

​List Tools

​Query Parameters

​Response

​Get Tool

​Response

​Get Tool Limits

​Response

​Create Tool

​Request Body

​Parameters

​HTTP Tool Fields

​Form Tool Fields

​Mock Tool Fields

​Display Configuration

​Response

​Errors

​Update Tool

​Request Body

​Response

​Delete Tool

​Response

​Input Schema

​Property Types

​Enum Values

​Display Config

​Display Types

​Form Schema

​Field Types

​Post Actions

​Examples

​HTTP Tool - Order Lookup

​Form Tool - Contact Form

Endpoints

List Tools

Query Parameters

Response

Get Tool

Response

Get Tool Limits

Response

Create Tool

Request Body

Parameters

HTTP Tool Fields

Form Tool Fields

Mock Tool Fields

Display Configuration

Response

Errors

Update Tool

Request Body

Response

Delete Tool

Response

Input Schema

Property Types

Enum Values

Display Config

Display Types

Form Schema

Field Types

Post Actions

Examples

HTTP Tool - Order Lookup

Form Tool - Contact Form