Skip to main content
DELETE
Delete a workspace tool set
Deletes the workspace tool set named by id and revokes every agent grant of it: its assignment rows are removed, and every agent that held it loses its tools at its next dispatch. The response is { id, deleted: true, revokedAssignments }, the number of grants removed. The delete is refused with 409, and nothing is deleted, when more than 100 agents hold the set, when it has more than 2,000 grants, or when the deployment’s tool-set grants exceed the 5,000-row read window.

Authority and retries

Requires tools:manage at the platform scope. Skill sets and tool sets have no org-unit home, so a credential granted tools:manage only at an org unit is refused with 403 and nothing is written. A Forge agent can never hold tools:manage. MCP clients reach this operation through forge_call_operation. A same-key retry with the same body returns the recorded result while you still hold the route’s permissions (Stored-response replay), and the delete never runs twice.

Errors

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Path Parameters

setId
string
required

The set's id (its setId), as the list routes return it

Minimum string length: 1

Response

Delete a workspace tool set A same-key repeat whose first response was not stored (over 32 KiB, or a one-time secret) answers this status with only data.id (IdOnlyReplay, Idempotency-Replay-Disclosure: id-only).

data
object
required

The deleted workspace tool set's id and how many agent grants of it were revoked with it.

meta
object
required