Developers / Agents
Detach tools from an agent
https://api.echonova.ai/v1/agents/{agentId}/tools/detachDetaches workspace tools from the agent. Ids that are not attached are ignored. The tools stay in the workspace. Free. Needs the agents:write scope on the key, and the key creator also needs Manage tools.
Headers
Bearer, a space, then your API key, which starts with ek_. Create keys in the portal under Developers, API Keys.
Path parameters
The agent id, as GET /v1/agents returned it.
Request body
application/json
Workspace tool ids, 1 to 20, as GET /v1/agents/{agentId}/tools shows them.
Response
200 application/json Every response uses this envelope.
The result.
Built-in tools and whether each is on.
The built-in tool key.
The tool name.
Whether the agent can use it.
Workspace tools attached to the agent. Their URLs and credentials are never shown.
The workspace tool id.
The tool name.
The kind of tool.
What the tool does, or null.
true for a successful call.
Repeats the HTTP status.
null on success.
Errors
Same envelope, with success false and data null. All errors
When. agentId or sessionId is not a 24-character hexadecimal id.
Fix. Use the id exactly as GET /v1/agents or the conversations list returned it.
When. toolIds is an empty list.
Fix. Send 1 to 20 tool ids.
When. toolIds lists more than 20 ids.
Fix. Send 1 to 20 tool ids per call.
When. A toolId is not a 24-character hexadecimal id.
Fix. Use workspace tool ids exactly as the portal or GET /v1/agents/{agentId}/tools shows them.
When. The body or query carries a field the endpoint does not define.
Fix. Remove the field.
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 agents:write scope.
Fix. Edit the key and give it the agents:write scope, or use another key.
When. The member who created the key has left the workspace, or no longer has both the Manage agents 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 member who created the key does not have the Manage tools permission, which attaching and detaching tools also need.
Fix. Give that member the Manage tools permission, or create a key as a member who has it.
When. The agent id is unknown, or the agent belongs to another workspace.
Fix. Use an id from GET /v1/agents with a key of the agent's workspace.
When. The agent is archived. Only duplicate, archive and restore work on an archived agent.
Fix. Restore it with POST /v1/agents/{agentId}/restore, or duplicate it and change the copy.
When. The JSON body of an agent write is over 512 KB; the request is rejected before the API key is checked, so it has no Activity row.
Fix. Send a smaller body; split long knowledge text into several sources.
When. The request has a body whose Content-Type is not application/json.
Fix. Send Content-Type: application/json.
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 -X POST "https://api.echonova.ai/v1/agents/{agentId}/tools/detach" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"toolIds":["6654a1b2c3d4e5f6a7b8c9d0"]}'{
"data": {
"system": [
{
"key": "web_search",
"name": "Web search",
"enabled": true
}
],
"attached": [
{
"id": "6654a1b2c3d4e5f6a7b8c9d0",
"name": "CRM lookup",
"type": "webhook",
"description": "Looks up a customer by phone number."
}
]
},
"success": true,
"statusCode": 200,
"errorMessage": null
}