> ## Documentation Index
> Fetch the complete documentation index at: https://cadenya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Delete a tool set
> Permanently remove a tool set. It refuses while any variation still assigns it.
Deletes a [tool set](/docs/api-reference/toolservice/create-a-new-tool-set) and its tools for good. Use it for a set nothing depends on. For one still wired into an agent, [archive](/docs/api-reference/toolservice/archive-a-tool-set) instead.
```typescript TypeScript theme={null}
await client.toolSets.delete(toolSetId, { workspaceId });
```
```go Go theme={null}
err := client.ToolSets.Delete(ctx, toolSetID,
cadenya.ToolSetDeleteParams{WorkspaceID: cadenya.String(workspaceID)})
```
```ruby Ruby theme={null}
cadenya.tool_sets.delete(tool_set_id, workspace_id: workspace_id)
```
```bash cURL theme={null}
curl -X DELETE "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/tool_sets/${TOOL_SET_ID}" \
-H "Authorization: Bearer ${CADENYA_API_KEY}"
```
A deleted tool set is gone: a later `GET` is a `404`. This is not the soft, reversible archive.
## It refuses while assigned
A tool set assigned to any [variation](/docs/api-reference/agentvariationservice/add-an-assignment-to-a-variation) does not delete. The guard is a typed `400`:
```
DELETE .../tool_sets/{assigned}
→ 400 "tool set cannot be deleted while it is assigned to agent variations"
```
To delete a set that is assigned, first remove the assignment or [archive](/docs/api-reference/toolservice/archive-a-tool-set) the set. The guard checks the actual assignments; a `400` means at least one variation still points at the set.
`info.agentCount` looks like the field to check here, but it currently always reads `0` even for an assigned set. Do not use it to predict a delete. To know whether a set is assigned, read its variations' `info.assignments`, or attempt the delete and handle the `400`.
## Deleting the agent clears the assignment
Deleting an agent cascades to its variations and their assignments, so a tool set is not stranded when the agent that used it goes away. Verified end to end:
```
assign tool set to a variation → 200
DELETE the agent → 200 (variation and assignment go with it)
DELETE the tool set → 200 (no longer assigned)
```
Earlier this was a trap: deleting the agent left a dangling assignment that could not be removed, so the tool set became permanently undeletable. That is fixed. If you have an old tool set stuck this way, it was archived as the workaround; it can be deleted now.
## Archive versus delete
| | Archive | Delete |
| -------------- | ---------------------------- | ------- |
| Reversible | Yes, `unarchive` | No |
| While assigned | Allowed | Refused |
| History | Kept | Gone |
| Tools | Pulled from agents, retained | Removed |
Reach for archive by default. It stops the sync, hides the set, and pulls its tools from objectives, while leaving assignments and history intact. Delete only when you are sure nothing needs the set or its history again.
## Related
The reversible retirement, allowed even while assigned.
Clear the assignment that blocks a delete.
The adapter, state, and tool counts on one set.
Archived sets appear under `?state=STATE_ARCHIVED`.
## OpenAPI
````yaml delete /v1/workspaces/{workspaceId}/tool_sets/{id}
openapi: 3.1.0
info:
title: Cadenya API
description: API for the Cadenya Agent Runtime platform.
version: '1.0'
servers:
- url: https://api.cadenya.com
description: Production server
security:
- bearerAuth: []
tags:
- name: AIProviderKeyService
- name: APIKeyService
description: |-
Issue, rotate, disable, and revoke a workspace's API keys. Every key
belongs to exactly one workspace; the system-managed global account key is
managed via GlobalAPIKeyService instead.
- name: AccountService
description: >-
Manage the authenticated account. Accounts are the top-level
organizational
unit and contain one or more workspaces.
- name: AgentScheduleService
description: >-
Manage recurring schedules attached to agents. Schedules trigger
objectives
on a cadence defined by AgentScheduleSpec.Schedule.
- name: AgentService
description: >-
Manage AI agents within a workspace. Agents define AI behavior and tool
access.
- name: AgentVariationService
description: >-
Manage variations of an agent and their tool, sub-agent, and memory layer
assignments.
- name: GlobalAPIKeyService
description: |-
Manage the account's system-provisioned global API key. The global key is
the only key that spans every workspace; it is created by the system and
cannot be deleted, so the surface is retrieve, rotate, and the
disable/enable kill switch.
- name: MemoryService
description: >-
Manage memory layers and their entries. Layers are named containers that
can
be composed into an objective's memory cascade; entries are the keyed values
within a layer. System-managed layers (e.g., episodic layers created by the
runtime) cannot be mutated through this API.
- name: ModelService
description: |-
Manage LLM models available to a workspace. Models represent provider and
family pairs (e.g., "anthropic/claude-sonnet-4.6"). Workspaces are seeded
with the supported models and you can enable or disable each one.
- name: ObjectiveEventStreamsService
- name: ObjectiveService
- name: ProfilesService
description: |-
Operations on profiles, the account-level principals (users, API keys,
system) that authenticate against the API.
- name: SearchService
- name: TenantService
description: >-
Read and erase tenants and the subjects under them. Tenants and subjects
are
created by assertion — on objective creation or widget session mint — never
directly, so this service has no create or update: it exists to enumerate what
assertions have produced, and to destroy it on request.
- name: ToolService
description: >-
Manage tool sets and the tools they contain. Tool sets group related
tools,
and tools define specific capabilities available to agents.
When a tool set is managed, only API key actors can modify its tools; human
(profile) actors cannot.
- name: UploadService
description: |-
Issue short-lived presigned URLs for direct client-to-object-storage
uploads. Created uploads can be referenced by id when creating or updating
resources that accept binary content (e.g., MemoryEntry).
- name: WidgetService
description: |-
Manage embeddable chat widgets. A widget binds an agent to a globally
unique hostname with a per-widget origin allowlist; browsers reach it with
session tokens minted via WidgetSessionService.
- name: WidgetSessionService
description: >-
Mint and manage widget sessions. Session creation is server-to-server
only:
the customer's backend authenticates its visitor, asserts tenant/subject
context, attaches any per-visitor secrets, and receives a short-lived
bearer token the browser uses against the widget host.
- name: WorkspaceAdminService
description: >-
Administer workspaces across the account: create and archive workspaces
and
manage their membership. These operations are account-scoped and require the
admin role (a token whose profile holds the WorkOS admin role); they live
under /v1/account/workspaces rather than the workspace-scoped /v1/workspaces
tree so an admin can manage any workspace in the account, including ones they
are not themselves a member of.
- name: WorkspaceSecretService
- name: WorkspaceService
description: |-
Manage workspaces within an account. Workspaces provide organizational
grouping and isolation for resources such as agents, tools, and API keys.
This is the workspace-scoped, end-user surface. Administrative operations
(create / archive workspaces, manage members) live in WorkspaceAdminService
under /v1/account/workspaces and require the admin role.
paths:
/v1/workspaces/{workspaceId}/tool_sets/{id}:
delete:
tags:
- ToolService
- Tool Sets
summary: Delete a tool set
description: Deletes a tool set in the workspace
operationId: ToolService_DeleteToolSet
parameters:
- name: workspaceId
in: path
description: Workspace ID.
required: true
schema:
type: string
example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
- name: id
in: path
description: |-
Tool set ID. Accepts the canonical ts_… form or the
external_id: form.
required: true
schema:
example: toolset_01HXKD2E5NQM3T9AYWCFNRMN74
type: string
responses:
'200':
description: OK
content: {}
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
x-codeSamples:
- lang: JavaScript
source: |-
import Cadenya from '@cadenya/cadenya';
const client = new Cadenya({
apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});
await client.toolSets.delete('toolset_01HXKD2E5NQM3T9AYWCFNRMN74', {
workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
});
- lang: Python
source: |-
import os
from cadenya import Cadenya
client = Cadenya(
api_key=os.environ.get("CADENYA_API_KEY"), # This is the default and can be omitted
)
client.tool_sets.delete(
id="toolset_01HXKD2E5NQM3T9AYWCFNRMN74",
workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"go.cadenya.com/cadenya-go\"\n\t\"go.cadenya.com/cadenya-go/option\"\n)\n\nfunc main() {\n\tclient := cadenya.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\terr := client.ToolSets.Delete(\n\t\tcontext.TODO(),\n\t\t\"toolset_01HXKD2E5NQM3T9AYWCFNRMN74\",\n\t\tcadenya.ToolSetDeleteParams{\n\t\t\tWorkspaceID: cadenya.String(\"workspace_01HXKD2E5NQM3T9AYWCF133E3Q\"),\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
- lang: Ruby
source: |-
require "cadenya"
cadenya = Cadenya::Client.new(api_key: "My API Key")
result = cadenya.tool_sets.delete(
"toolset_01HXKD2E5NQM3T9AYWCFNRMN74",
workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)
puts(result)
- lang: CLI
source: |-
cadenya tool-sets delete \
--api-key 'My API Key' \
--workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
--id toolset_01HXKD2E5NQM3T9AYWCFNRMN74
components:
schemas:
Status:
type: object
properties:
code:
type: integer
description: >-
The status code, which should be an enum value of
[google.rpc.Code][google.rpc.Code].
format: int32
message:
type: string
description: >-
A developer-facing error message, which should be in English. Any
user-facing error message should be localized and sent in the
[google.rpc.Status.details][google.rpc.Status.details] field, or
localized by the client.
details:
type: array
items:
$ref: '#/components/schemas/GoogleProtobufAny'
description: >-
A list of messages that carry the error details. There is a common
set of message types for APIs to use.
description: >-
The `Status` type defines a logical error model that is suitable for
different programming environments, including REST APIs and RPC APIs. It
is used by [gRPC](https://github.com/grpc). Each `Status` message
contains three pieces of data: error code, error message, and error
details. You can find out more about this error model and how to work
with it in the [API Design
Guide](https://cloud.google.com/apis/design/errors).
GoogleProtobufAny:
type: object
properties:
'@type':
type: string
description: The type of the serialized message.
additionalProperties: true
description: >-
Contains an arbitrary serialized message along with a @type that
describes the type of the serialized message.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````