Tools
Create tool
Create a new function-calling tool in the current project. A tool is an HTTP webhook the agent can call during a conversation; the agent decides when to invoke it based on the name and description, then sends the configured parameters to your url. The response returns the full tool record including its generated id (the tool_id). After creating a tool you typically link it to one or more agents with POST /api/ext/tool/link before it can be used in a call.
curl --request POST \
--url 'https://api.nabrah.ai/api/ext/tool' \
--header 'X-API-Key: <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{
"name": "get_weather",
"description": "Look up the current weather for a city. Call this when the caller asks about weather conditions.",
"url": "https://api.example.com/weather",
"method": "GET",
"timeout_seconds": 5,
"parameters": [
{
"name": "api_token",
"location": "header",
"parameter_type": "constant",
"data_type": "string",
"description": "Service API token",
"required": true,
"value": "secret-token-123",
"default_value": ""
},
{
"name": "city",
"location": "query",
"parameter_type": "inferred",
"data_type": "string",
"description": "The city the caller is asking about",
"required": true,
"value": "",
"default_value": "Riyadh"
}
]
}'{
"name": "string",
"description": "string",
"url": "string",
"method": "GET",
"id": "00000000-0000-4000-8000-000000000000",
"project_id": "00000000-0000-4000-8000-000000000000",
"created_at": "2026-01-15T12:00:00.000Z",
"updated_at": "2026-01-15T12:00:00.000Z",
"timeout_seconds": 5,
"parameters": [
{
"name": "string",
"location": "query",
"parameter_type": "constant",
"data_type": "string",
"description": "string",
"tool_id": "00000000-0000-4000-8000-000000000000",
"required": false,
"value": "string",
"default_value": "string"
}
],
"link_id": "00000000-0000-4000-8000-000000000000"
}Request fields
Describe the webhook the agent should call and the parameters it may pass.
name and description tell the model what the tool does and when to use it — write them clearly because the agent selects tools from these. url is the endpoint Nabrah calls; method is the HTTP verb (GET, POST, etc.). timeout_seconds bounds how long Nabrah waits for your endpoint.
namedescriptionurlmethodtimeout_secondsparameters[]Defines each value sent with the call. name is the parameter key. location is where it is placed (query, header, path, or body). parameter_type is either constant (a fixed value you supply in value) or inferred from the conversation by the model. data_type is the JSON type (string, number, boolean, etc.). description guides the model when it must fill the value. required marks whether the agent must provide it. value holds the fixed value for constant parameters; default_value is used when no value is supplied.
namelocationparameter_typedata_typedescriptionrequiredvaluedefault_valueNext step: linking
Creating a tool does not attach it to any agent.
Take the id from the response and call POST /api/ext/tool/link with that tool_id plus an agent_id to make the tool available during the agent's conversations.
Delivery and retries
How Nabrah calls your endpoint during a call or chat.
Each time the agent uses the tool, Nabrah calls your endpoint once and waits up to timeout_seconds. There is no automatic retry or backoff, and no request ID is sent.
timeout_secondsErrorsYour status code and response body are passed back to the agent, which decides what to tell the caller. On a timeout or connection error the agent is told the tool failed. The agent may call the tool again in the same conversation, so make booking-style endpoints idempotent, for example by keying them on your own appointment ID.
Authorization
X-API-KeystringheaderrequiredYour workspace API key. Create one in the dashboard under API keys.
Body
application/jsonA GET webhook with two query parameters: a constant API token and a model-filled city name.
{
"name": "get_weather",
"description": "Look up the current weather for a city. Call this when the caller asks about weather conditions.",
"url": "https://api.example.com/weather",
"method": "GET",
"timeout_seconds": 5,
"parameters": [
{
"name": "api_token",
"location": "header",
"parameter_type": "constant",
"data_type": "string",
"description": "Service API token",
"required": true,
"value": "secret-token-123",
"default_value": ""
},
{
"name": "city",
"location": "query",
"parameter_type": "inferred",
"data_type": "string",
"description": "The city the caller is asking about",
"required": true,
"value": "",
"default_value": "Riyadh"
}
]
}Response
Successful Response
application/json
Validation Error
application/json