Create a tool

POST

https://api.smallest.ai/atoms/v1/tool

POST

/atoms/v1/tool

import requests
url = "https://api.smallest.ai/atoms/v1/tool"
payload = { "definition": {
        "type": "api_call",
        "name": "get_order_status",
        "description": "Look up a customer's order by id and read back its status."
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "status": true,
  "data": {
    "_id": "6a86c89eb3073ea15c328ce0",
    "toolId": "tool_ab12cd34ef56gh78ij90kl12",
    "organizationId": "6a5f9c9fcf10167aad404c40",
    "type": "api_call",
    "definition": {
      "type": "api_call",
      "name": "get_order_status",
      "description": "Look up a customer's order by id and read back its status.",
      "enabled": true,
      "url": "https://api.example.com/orders",
      "method": "GET",
      "timeout": 5000,
      "headers": {
        "Authorization": "Bearer TOKEN",
        "Content-Type": "application/json"
      },
      "headersArray": [
        {
          "key": "Authorization",
          "value": "Bearer TOKEN"
        }
      ],
      "queryParams": [
        {
          "key": "id",
          "value": "{{order_id}}"
        }
      ],
      "requestBody": "{\"customer_id\": \"{{customer_id}}\"}",
      "llmParameters": [
        {
          "name": "string",
          "description": "string",
          "type": "text",
          "values": [
            "string"
          ],
          "required": false
        }
      ],
      "responseVariables": [
        {
          "variableName": "orderStatus",
          "jsonPath": "$.data.status"
        }
      ],
      "auth": {
        "type": "none",
        "token": "ORDER_API_TOKEN",
        "name": "X-API-Key",
        "location": "header",
        "value": "SEARCH_API_KEY",
        "username": "string",
        "password": "string"
      },
      "timeoutMs": 1000,
      "expectsResponse": true,
      "fillerPhrases": [
        "Let me check that for you",
        "One moment please"
      ]
    },
    "createdAt": "2024-01-15T09:30:00Z",
    "updatedAt": "2024-01-15T09:30:00Z"
  }
}

Create a reusable tool in the org Tools library. Two types are supported: api_call and client_tool (system tools like transfer/end-call are configured per-agent, not here). Reference it from an agent by adding its returned toolId to toolRefs on the agent config.

Referencing a tool makes it available; it does not force use. The agent only calls a tool when its prompt tells it to, so describe the tool’s purpose and when to trigger it in the agent’s prompt.

Authentication

AuthorizationBearer

API key from the console ApiKey collection, sent as Bearer token. Also accepts session cookies for browser-based auth.

Request

This endpoint expects an object.

definitionobjectRequired

The tool body — the same shape used inside an agent's tools[] (discriminated on type). api_call is the most common; client_tool and the built-in types are also valid.

Response

Tool created.

statusbooleanOptional

dataobjectOptional

A tool in the org-level Tools library. Referenced from agents by toolId (see toolRefs on the agent config). Editing a library tool propagates to every agent that references it.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

500

Internal Server Error