Developers / Tools
Get a tool
https://api.echonova.ai/v1/tools/{toolId}Returns one tool of this key's workspace. Free. Needs the tools:write scope on the key.
Headers
Bearer, a space, then your API key, which starts with ek_. Create keys in the portal under Developers, API Keys.
Path parameters
The tool id, as GET /v1/tools returned it.
Response
200 application/json Every response uses this envelope.
The result.
The tool id.
Tool name, unique in the workspace.
webhook, openapi or integration.
What the tool does, or null.
When the tool was created.
When the tool last changed.
Set for webhook tools. Constant values are never returned.
The URL the tool calls.
HTTP method of the call.
How long the call may take, in milliseconds, or null for the default.
Auth connection id used for the call, or null.
The values the call sends.
Where the parameter goes in the request.
Parameter key, or the path placeholder name.
The type of value the parameter takes.
Whether the call needs this parameter.
Tells the model what to put here, or null.
llm, constant or secret. Constant values are never returned.
The vault secret id when valueType is secret, otherwise null.
Set for OpenAPI tools.
Title of the imported OpenAPI document.
How many operations the tool imported.
Whether the import is ready for agents.
The server the tool calls, or null.
Operation names selected for import, empty for all.
Auth connection id sent on every call, or null.
Why the import failed, or null.
Set for integration tools.
The integration provider.
The integration tool key.
true for a successful call.
Repeats the HTTP status.
null on success.
Errors
Same envelope, with success false and data null. All errors
When. toolId is not a 24-character hexadecimal id.
Fix. Use the id exactly as GET /v1/tools returned it.
When. The Authorization header is missing or is not Bearer ek_..., no key matches the token, or the key is deleted, disabled, expired or its account is closed.
Fix. Send Authorization: Bearer ek_... with an enabled key from this environment.
When. The workspace that owns the key has no subscription.
Fix. Check the workspace's plan in the portal.
When. The subscription is in a state other than active or trial.
Fix. Renew the subscription.
When. The key does not have the tools:write scope. agents:write does not give it.
Fix. Edit the key and give it the tools:write scope, or use another key.
When. The member who created the key has left the workspace, or no longer has both the Manage tools and Manage developer API permissions. It is checked on every call.
Fix. Give that member both permissions again, or create a key as a member who has them.
When. The tool id is unknown, or the tool belongs to another workspace.
Fix. Use an id from GET /v1/tools with a key of the tool workspace.
When. The key made more than 100 requests to one endpoint in 60 seconds, or one IP address made more than 100 requests to one endpoint in 60 seconds (the IP limit is counted before the key is checked, so it can answer with no key at all); a Retry-After header carries the seconds to wait.
Fix. Wait Retry-After seconds, then retry.
When. An error the API did not classify.
Fix. Check the request, then retry after a short wait; contact support if it persists.
When. A transient outage inside the API.
Fix. Retry after a short wait.
When. A transient timeout inside the API.
Fix. Retry after a short wait.
curl "https://api.echonova.ai/v1/tools/{toolId}" \
-H "Authorization: Bearer YOUR_API_KEY"{
"data": {
"id": "6650a1b2c3d4e5f6a7b8c9d0",
"name": "Order lookup",
"type": "webhook",
"description": "Finds an order by its number.",
"createdAt": "2026-11-01T10:00:00.000Z",
"updatedAt": "2026-11-01T10:00:00.000Z",
"webhook": {
"url": "https://api.example.com/orders/{orderId}",
"method": "GET",
"timeoutMs": 10000,
"connectionId": "6650a1b2c3d4e5f6a7b8c9d0",
"parameters": [
{
"location": "header",
"name": "orderId",
"dataType": "string",
"required": true,
"description": "Finds an order by its number.",
"valueType": "llm",
"secretId": "YOUR_SECRET_ID"
}
]
},
"openapi": {
"apiTitle": "Orders API",
"operationCount": 12,
"status": "ready",
"baseUrl": "https://api.example.com",
"includeOperations": [
"getOrder"
],
"authConnectionId": "YOUR_AUTH_CONNECTION_ID",
"error": null
},
"integration": {
"provider": "slack",
"key": "add_reaction"
}
},
"success": true,
"statusCode": 200,
"errorMessage": null
}