Eliminar una funcion de webhook
DELETE /v1/tools/{id}
Delete a webhook tool permanently. Fails while an agent still holds it.
DELETE
Eliminar una funcion de webhook
Deletes the tool. This is a hard delete and it cannot be undone.
It is refused while an agent still holds the tool, and the error names which ones — so the normal sequence is: take the tool out of those agents with
PATCH /v1/agents/{id}, then delete.
Endpoint
Required scope
agents:write
Headers
Path parameters
Example request
Response
204 No Content
Deleted. No body.401 Unauthorized
Missing, invalid, revoked, or expired token.403 Forbidden
The token does not have theagents:write scope.
404 Not Found
No webhook tool with that id in the token’s company. A repeated delete lands here, so treat404 as “already gone”.
409 Conflict
error.code is AGENT_TOOL_IN_USE. At least one agent still holds the tool; the error details list them.
502 Bad Gateway
The agent service is unreachable.Operational notes
- The
409is the useful part of this endpoint. It is what stops you silently breaking an agent mid-conversation, and it tells you exactly which agents to fix. - Taking a tool off an agent is an agent update, not a tool operation: send
toolswithout that id. - Deleting is company-wide. A tool held by an agent in another project of the same company counts as in use and blocks the delete.
- A retry is safe: the second call is a
404, never a partial delete. is_active: falseis the reversible alternative and is usually what you want when retiring an integration gradually.