Create Tool

Creates a tool of any type. The body is the canonical tool payload — common fields plus the fields for the chosen toolType (see the Tool Types Reference). New tools default to isActive: true.

POST/v2.0/tools

Plan limit

Creation is gated by max_tools. Hitting the limit returns 403 LIMIT_EXCEEDED.

Request Body

Always required

Parameter	Type	Required	Description
name	string	Required	Lowercase letters/numbers/underscores, starts with a letter. Unique per org.
description	string	Required	When the AI should call this tool.
toolType	string	Required	One of the 8 types. Determines which additional fields are required.

Type-specific fields (e.g. serverUrl + parameters for functions, components for WhatsApp templates, shopifyAction for Shopify) are documented in the Tool Types Reference. Fetch a ready-to-edit example from GET /v2.0/tools/schema?type=….

Examples

curl -X POST https://api.sendiee.com/v2.0/tools \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_order_status",
    "description": "Look up the delivery status of an order by its order number.",
    "toolType": "function",
    "serverUrl": "https://api.yourstore.com/orders/{{order_id}}",
    "requestMethod": "GET",
    "auth": { "type": "bearer", "token": "sk_live_xxx" },
    "parameters": {
      "type": "object",
      "properties": { "order_id": { "type": "string", "description": "Customer order number" } },
      "required": ["order_id"]
    }
  }'

Response

{
  "success": true,
  "data": {
    "toolId": "V1StGXR8Z5jdHi",
    "_id": "663b1f9c2a1f4e0012ab34cd",
    "name": "track_order",
    "description": "Look up the shipping status of a Shopify order by its order number.",
    "toolType": "shopify",
    "isActive": true,
    "shopifyAction": {
      "type": "track_order",
      "defaultLimit": 10
    },
    "tags": [],
    "createdAt": "2026-05-30T10:00:00.000Z",
    "updatedAt": "2026-05-30T10:00:00.000Z"
  }
}

Validation failure (422)

Fix each entry in details[] (use the example where present) and retry.

{
  "error": true,
  "code": "TOOL_VALIDATION_FAILED",
  "message": "Tool payload failed validation. Fix the issues in details[] and retry. Call GET /v2.0/tools/schema?type=<toolType> for the full shape + a valid example.",
  "details": [
    {
      "path": "shopifyAction.type",
      "code": "SHOPIFY_ACTION_TYPE_INVALID",
      "message": "shopifyAction.type must be one of: search_products, get_product, ...",
      "example": "track_order"
    }
  ]
}

Duplicate name (409)

{
  "error": true,
  "code": "TOOL_NAME_EXISTS",
  "message": "A tool named \"track_order\" already exists in this organization."
}

Plan limit (403)

{
  "error": true,
  "code": "LIMIT_EXCEEDED",
  "message": "You have reached your plan's tool limit. Upgrade to add more."
}