Skip to main content
POST
JavaScript
A tool set is a collection of tools that share one provider. You supply an adapter, Cadenya discovers the tools behind it, and any agent variation you assign the set to can call them. The request has two required fields, metadata and spec, and the whole story lives in spec.adapter.

Pick an adapter

Four kinds. Set exactly one.
The adapter is a discriminated union: type names the variant, and the key matching type carries the payload. Both are required, and the SDKs type it as a tagged union, so TypeScript narrows on type and Go offers one constructor per variant.
The call returns immediately with state: STATE_ACTIVE. Discovery happens in the background, so info.toolCount reads 0 for a moment even when the provider has tools waiting.

Watch the sync

There is no public sync endpoint. Cadenya syncs when you create or update the adapter. Synced MCP sources and OpenAPI specifications fetched by URL also refresh hourly. The only way to know a sync landed is the event stream.
Three event types: syncStarted, syncCompleted (carries toolsSynced), and syncFailed (carries message and errorType). Poll listEvents after a create when your setup script needs to block until the tools exist. info.lastSync gives you the timestamp of the most recent successful sync (it is omitted until one lands). info returns on every read; includeInfo is a no-op on tool sets.
An MCP adapter with justInTime.enabled set to true syncs nothing up front. Tools load when an objective starts, and info.toolCount stays at 0. That is the point of on-demand discovery, and it surprises anyone waiting for a tool count to climb.

Keep secrets out of the request

Adapter headers take ${SECRET_NAME} placeholders. Cadenya resolves them at call time and the plaintext never comes back on a read.
Read the secret back and spec.value is an empty string. Names resolve in order: objective secrets, then tool set secrets, then workspace secrets. The narrowest scope wins, which is how a per-user token overrides a service credential for one run.

Filter what syncs

MCP and OpenAPI adapters take includeTools and excludeTools. A filter is a list of attribute matchers joined by OPERATOR_AND or OPERATOR_OR.
Match on ATTRIBUTE_NAME, ATTRIBUTE_TITLE, or ATTRIBUTE_DESCRIPTION. The matcher is its own union: type picks exact, contains, startsWith, endsWith, or regex, the matching key carries the string, and caseSensitive rides alongside. toolApprovals puts every synced tool behind human approval, either always or for the subset an only filter selects. Filters apply on every sync, not once. Restore a tool the filter excludes and the next sync omits it again.

Define tools by hand

An http or bare tool set starts empty. Create tools on it with spec.config naming the same adapter kind as the parent set.
Four fields are required on a tool spec: description, parameters (a JSON Schema), requiresApproval, and config. All four are enforced, so a misspelled inputSchema or a missing config is a 400 rather than a tool the agent can never call correctly. The response adds llmToolName, a cleaned-up name Cadenya derives for the model: issue_refund becomes IssueRefund.

Bare tools: your code is the runtime

A bare tool call fires nothing. The objective parks, the tool call sits at TOOL_CALL_EXECUTION_STATUS_WAITING_FOR_CONTENT, and your code answers it.
That unlocks two patterns. Human in the loop: park the call, show it to a person, submit their answer. Reverse harness: run the tool on your own infrastructure, inside your VPC, and report the result back. Cadenya never needs a route into your network. Set contentTimeout on the bare adapter to bound the wait. Leave it unset and the call waits 24 hours, then resolves on its own with a synthesized system result saying no content arrived. The objective keeps going either way.

Lifecycle

Tool sets are created STATE_ACTIVE and archive rather than delete when they are still in use.
Archiving stops the sync, hides the set from lists, and pulls its tools from objectives, while leaving variation assignments and history intact. Delete refuses to run while the set is assigned to a variation. Individual tools follow the same idea with omit and restore: an omitted tool stays in the set but no agent sees it.

Next steps

Connect an MCP server

The hands-on lesson, from server URL to an agent calling the tools.

Import an OpenAPI spec

Turn an existing REST API into a tool set, one operation at a time.

Approve a tool call

Park a dangerous call, ask a person, then let the objective continue.

Store and use secrets

Where ${SECRET_NAME} resolves from, and which scope wins.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId
string
required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

Body

application/json
metadata
object
required

CreateResourceMetadata contains the user-provided fields for creating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.

spec
object
required

Response

OK

metadata
object
required

Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

spec
object
required
state
enum<string>
required
read-only

The current lifecycle state of the tool set. Output only. Tool sets are created STATE_ACTIVE; use the :archive and :unarchive actions to transition between states.

Available options:
STATE_UNSPECIFIED,
STATE_ACTIVE,
STATE_ARCHIVED
info
object

Tool set information