API reference · AI agents

Add a tool

Let an agent call one of your APIs, for example to check stock or create a booking. The agent decides when to use it from description_for_model.

POST/v1/whatsapp/agents/{agent_id}/tools

Bearer API key
Rate limit 120 / min
Returns 201 Created
Needs the WhatsApp permission · free

POST /v1/whatsapp/agents/{agent_id}/tools

curl https://api.talks.africa/v1/whatsapp/agents/agt_92kd/tools \
  -H "Authorization: Bearer $TALKS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "check_stock",
    "endpoint": "https://api.dukafresh.co.ke/stock",
    "method": "GET",
    "description_for_model": "Check if an item is in stock and its price before quoting.",
    "is_secure": true
  }'

{
  "id": "tool_6pq",
  "name": "check_stock",
  "enabled": true,
  "usage_count": 0
}

Use a tk_test_ key while you build. Nothing is sent and no credits are used.

Body parameters

agent_idstringrequired
The agent ID from when you created it.
namestringoptional
Short tool name, e.g. check_stock.
endpointstringoptional
Your HTTPS URL.
methodstringoptional
GET, POST, PUT or DELETE.
headersobjectoptional
Headers to send, e.g. your own API key.
request_body_templatestringoptional
Body with placeholders the agent fills.
description_for_modelstringoptional
Tells the agent when and how to use it.
is_securebooleanoptional
Hide headers from logs.

Response fieldsResponse

id
Tool ID
enabled
Whether the agent can use it
usage_count · last_used_at
Usage

Errors

Tap one to see its response above.

All errors use the standard error object. Select one to see its response.

Was this page helpful?