Tools API

Tools are the capabilities you give an AI assistant — calling your API, replying with a fixed message, sending media or interactive WhatsApp / Instagram / Messenger templates, or running built-in Catalog and Shopify actions. This API lets you create and manage all of them programmatically, with the same validation the dashboard uses.

The 8 tool types

Every tool has a toolType, which is immutable after creation:

• function — calls an external HTTP endpoint with AI-supplied arguments.
• static_tool — returns a fixed message (supports {{current_date}} etc.).
• media_attachments — sends 1–5 media files from your Sendiee library.
• message_templates — a WhatsApp interactive message (buttons, list, CTA, product, carousel…).
• instagram_templates — an Instagram message (quick replies, button card, carousel).
• messenger_templates — a Messenger message (quick replies, buttons, generic template, media).
• sendiee_catalog — built-in Sendiee Catalog actions (search products, list collections…).
• shopify — built-in Shopify actions (track order, search products, create draft order…).

See the Tool Types Reference for the exact payload of each type, or fetch it live from GET /v2.0/tools/schema.

Endpoints

Validation & the self-correction loop

Every create and update is validated server-side against the same rules the dashboard enforces — including Meta’s WhatsApp/Instagram/Messenger limits. When a payload is invalid the API responds 422 TOOL_VALIDATION_FAILED with a details[] array. Each entry has a path, a stable code, a human message, and often an example of a correct value.

{
  "error": true,
  "code": "TOOL_VALIDATION_FAILED",
  "message": "Tool payload failed validation. Fix the issues in details[] and retry...",
  "details": [
    {
      "path": "components.action.buttons",
      "code": "BUTTONS_MAX",
      "message": "A maximum of 3 buttons is allowed."
    },
    {
      "path": "name",
      "code": "NAME_INVALID",
      "message": "name must be lowercase letters, numbers and underscores, starting with a letter.",
      "example": "track_order"
    }
  ]
}

Attaching tools to an assistant

Tools are attached by passing their _id values in the tools[]array when you create or update an assistant — there is no separate attach endpoint. Get a tool’s _id from any tools response.

curl -X PATCH https://api.sendiee.com/v2.0/assistants/kQ8z3cR7hV2bWa \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tools": ["663b1f...", "663b20..."] }'

Authentication & limits

All endpoints use Authorization: Bearer YOUR_API_KEY and are scoped to your organization. Creation is gated by the max_tools plan limit (hitting it returns 403 LIMIT_EXCEEDED). Secrets such as bearer tokens, basic passwords and API-key values are never returned in clear text — they appear masked.