Create a tool
Creates a new webhook-type tool. tool_key must be unique within your
organization; reuse returns 409. Auth secrets are stored AES-256-GCM
encrypted and are never returned — submit them on create / PATCH to set
or rotate. Integration-type tools must be created via the dashboard
(OAuth flow) and cannot be created through the public API in v1.
API key in the Authorization: Bearer <key> header.
Keys are created in the SMAO dashboard (Settings → API Keys).
In: header
^[a-z][a-z0-9_]*$1 <= length <= 80Leading/trailing whitespace is trimmed.
1 <= length <= 200""length <= 1000v1 accepts webhook only. Integration-type tools must be created via the dashboard (OAuth flow).
"webhook"JSON Schema defining the tool arguments.
Auth credentials sent on POST/PATCH. Shape varies by type.
Note: secret and password are write-only; responses use ToolAuthSummary.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.smao.ai/api/v1/tools" \ -H "Content-Type: application/json" \ -d '{ "tool_key": "get_opening_hours", "display_name": "string", "execution_type": "webhook", "webhook": { "url": "http://example.com" } }'{
"data": {
"id": "string",
"tool_key": "get_opening_hours",
"display_name": "Get Opening Hours",
"description": "Returns the opening hours for the requested weekday.",
"parameters": {},
"execution_type": "webhook",
"source": "custom",
"webhook": {
"url": "http://example.com",
"method": "GET",
"headers": {},
"body_template": "string",
"timeout_ms": 500,
"retry_count": 5
},
"integration": null,
"auth": {
"type": "apiKey",
"header_name": "string",
"username": "string",
"has_secret": true
},
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
}{
"error": {
"code": "validation_failed",
"message": "Validation failed"
}
}{
"error": {
"code": "unauthorized",
"message": "Missing API key"
}
}{
"error": {
"code": "subscription_required",
"message": "This feature is not available in your current subscription. Please upgrade to a higher plan"
}
}{
"error": {
"code": "forbidden",
"message": "No permission"
}
}{
"error": {
"code": "conflict",
"message": "A tool with that tool_key already exists."
}
}{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded"
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred."
}
}