Skip to main content
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.
If you only want the agent to stop calling it, PUT it with is_active: false instead. That is reversible and keeps the URL, headers and parameters intact.

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 the agents:write scope.

404 Not Found

No webhook tool with that id in the token’s company. A repeated delete lands here, so treat 404 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 409 is 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 tools without 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: false is the reversible alternative and is usually what you want when retiring an integration gradually.

Authorizations

Authorization
string
header
required

Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.

Path Parameters

id
string
required

Response

204 - undefined