Skip to content
cadenya
Get started
API Reference

Search

Search for tools or tool sets
client.search.searchToolsOrToolSets(stringworkspaceID, SearchSearchToolsOrToolSetsParams { query } query?, RequestOptionsoptions?): SearchSearchToolsOrToolSetsResponse { agents, tools, toolSets }
GET/v1/workspaces/{workspaceId}/search/tools_or_tool_sets
ModelsExpand Collapse
metadata: ResourceMetadata { id, accountId, createdAt, 6 more }

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

id: string

Unique identifier for the resource (prefixed ULID, e.g., “agent_01HXK…”)

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

createdAt: string

Timestamp when this resource was created

formatdate-time
name: string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profileId: string

ID of the actor (user or service account) that created this resource

workspaceId: string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

bundleKey?: string

Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.

externalId?: string

External ID for the resource (e.g., a workflow ID from an external system)

labels?: Record<string, string>

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: AgentSpec { status, variationSelectionMode, description, 3 more }

Agent specification (user-provided configuration)

status: "AGENT_STATUS_UNSPECIFIED" | "AGENT_STATUS_DRAFT" | "AGENT_STATUS_PUBLISHED" | "AGENT_STATUS_ARCHIVED"

Status of the agent

formatenum
One of the following:
"AGENT_STATUS_UNSPECIFIED"
"AGENT_STATUS_DRAFT"
"AGENT_STATUS_PUBLISHED"
"AGENT_STATUS_ARCHIVED"
variationSelectionMode: "VARIATION_SELECTION_MODE_UNSPECIFIED" | "VARIATION_SELECTION_MODE_RANDOM" | "VARIATION_SELECTION_MODE_WEIGHTED"

Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified

formatenum
One of the following:
"VARIATION_SELECTION_MODE_UNSPECIFIED"
"VARIATION_SELECTION_MODE_RANDOM"
"VARIATION_SELECTION_MODE_WEIGHTED"
description?: string

Description of the agent’s purpose

inputDataSchema?: Record<string, unknown>

InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as the tool’s input parameter schema. If omitted, the sub-agent schema will be loaded with a simple “prompt” free text string as its schema.

outputDefinition?: Record<string, unknown>

Optional output definition for objectives created for this agent. When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here. Use this option when you want structured data to be created by your objectives.

webhookEventsUrl?: string

The URL that Cadenya will send events for any objective assigned to the agent.

info?: AgentInfo { createdBy, variationCount }

AgentInfo contains simple information about an agent for display or quick reference

createdBy?: Profile { metadata, spec }

A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.

metadata: AccountResourceMetadata { id, accountId, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: string

Unique identifier for the resource (prefixed ULID, e.g., “apikey_01HXK…”)

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

name: string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profileId: string
externalId?: string

External ID for the resource (e.g., a workflow ID from an external system)

labels?: Record<string, string>

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ProfileSpec { type, email, name }

Configuration for a profile.

type: "PROFILE_TYPE_UNSPECIFIED" | "PROFILE_TYPE_USER" | "PROFILE_TYPE_API_KEY" | "PROFILE_TYPE_SYSTEM"

Whether this profile represents a human user, an API key, or a system principal.

formatenum
One of the following:
"PROFILE_TYPE_UNSPECIFIED"
"PROFILE_TYPE_USER"
"PROFILE_TYPE_API_KEY"
"PROFILE_TYPE_SYSTEM"
email?: string

Email address of the profile. Required and unique within an account for user profiles.

name?: string

Display name (e.g., “Bobby Tables”).

variationCount?: number
metadata: ResourceMetadata { id, accountId, createdAt, 6 more }

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

id: string

Unique identifier for the resource (prefixed ULID, e.g., “agent_01HXK…”)

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

createdAt: string

Timestamp when this resource was created

formatdate-time
name: string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profileId: string

ID of the actor (user or service account) that created this resource

workspaceId: string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

bundleKey?: string

Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.

externalId?: string

External ID for the resource (e.g., a workflow ID from an external system)

labels?: Record<string, string>

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ToolSpec { config, description, parameters, 2 more }
config: ToolSpecConfig { http, mcp, openapi }

Config defines the adapter to use for the tool. This is used to determine how the tool is called. For example, if the tool is an HTTP tool, the adapter will be Http. If the tool is an inline tool, the adapter will be Inline.

http?: ConfigHTTP { requestMethod, headers, path, 4 more }
requestMethod: "HTTP_METHOD_UNSPECIFIED" | "GET" | "POST" | 3 more
formatenum
One of the following:
"HTTP_METHOD_UNSPECIFIED"
"GET"
"POST"
"PUT"
"PATCH"
"DELETE"
headers?: Record<string, string>
path?: string
query?: string
requestBodyContentType?: string
requestBodyTemplate?: string

These are only used when the request method is a POST, PUT, or PATCH

toolName?: string

The tool name (commonly an “operation id” in OpenAPI specs) to call on the HTTP adapter. This is used to match the tool spec to the correct endpoint on the HTTP adapter. it will be derived from the name of the tool if not provided.

mcp?: ConfigMcp { toolDescription, toolName, toolTitle }
toolDescription?: string
toolName?: string
toolTitle?: string
openapi?: ConfigOpenAPI { method, operationId, path }
method?: string
operationId?: string
path?: string
description: string
parameters: Record<string, unknown>
status: "TOOL_STATUS_UNSPECIFIED" | "TOOL_STATUS_AVAILABLE" | "TOOL_STATUS_OMITTED" | "TOOL_STATUS_ARCHIVED"
formatenum
One of the following:
"TOOL_STATUS_UNSPECIFIED"
"TOOL_STATUS_AVAILABLE"
"TOOL_STATUS_OMITTED"
"TOOL_STATUS_ARCHIVED"
requiresApproval?: boolean
info?: ToolInfo { createdBy, toolSet }
createdBy?: Profile { metadata, spec }

A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.

metadata: AccountResourceMetadata { id, accountId, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: string

Unique identifier for the resource (prefixed ULID, e.g., “apikey_01HXK…”)

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

name: string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profileId: string
externalId?: string

External ID for the resource (e.g., a workflow ID from an external system)

labels?: Record<string, string>

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ProfileSpec { type, email, name }

Configuration for a profile.

type: "PROFILE_TYPE_UNSPECIFIED" | "PROFILE_TYPE_USER" | "PROFILE_TYPE_API_KEY" | "PROFILE_TYPE_SYSTEM"

Whether this profile represents a human user, an API key, or a system principal.

formatenum
One of the following:
"PROFILE_TYPE_UNSPECIFIED"
"PROFILE_TYPE_USER"
"PROFILE_TYPE_API_KEY"
"PROFILE_TYPE_SYSTEM"
email?: string

Email address of the profile. Required and unique within an account for user profiles.

name?: string

Display name (e.g., “Bobby Tables”).

toolSet?: ResourceMetadata { id, accountId, createdAt, 6 more }

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

id: string

Unique identifier for the resource (prefixed ULID, e.g., “agent_01HXK…”)

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

createdAt: string

Timestamp when this resource was created

formatdate-time
name: string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profileId: string

ID of the actor (user or service account) that created this resource

workspaceId: string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

bundleKey?: string

Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.

externalId?: string

External ID for the resource (e.g., a workflow ID from an external system)

labels?: Record<string, string>

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

metadata: ResourceMetadata { id, accountId, createdAt, 6 more }

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

id: string

Unique identifier for the resource (prefixed ULID, e.g., “agent_01HXK…”)

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

createdAt: string

Timestamp when this resource was created

formatdate-time
name: string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profileId: string

ID of the actor (user or service account) that created this resource

workspaceId: string

Workspace this resource belongs to for organizational grouping (prefixed ULID)

bundleKey?: string

Optional bundle ownership key. When set, indicates the resource is managed by a configuration bundle identified by this key. Used by BulkWorkspaceResources.Apply to track which resources belong to which bundle for reconciliation / soft-delete on re-apply.

externalId?: string

External ID for the resource (e.g., a workflow ID from an external system)

labels?: Record<string, string>

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ToolSetSpec { adapter, description }
adapter?: ToolSetAdapter { http, mcp, openapi }
http?: ToolSetAdapterHTTP { baseUrl, headers }
baseUrl?: string
headers?: Record<string, string>
mcp?: ToolSetAdapterMcp { excludeTools, headers, includeTools, 2 more }
excludeTools?: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: "OPERATOR_UNSPECIFIED" | "OPERATOR_AND" | "OPERATOR_OR"
formatenum
One of the following:
"OPERATOR_UNSPECIFIED"
"OPERATOR_AND"
"OPERATOR_OR"
filters?: Array<AttributeFilter { attribute, matcher } >
attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"
formatenum
One of the following:
"ATTRIBUTE_UNSPECIFIED"
"ATTRIBUTE_NAME"
"ATTRIBUTE_TITLE"
"ATTRIBUTE_DESCRIPTION"
matcher?: StringMatcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean
contains?: string
endsWith?: string
exact?: string
regex?: string
startsWith?: string
headers?: Record<string, string>
includeTools?: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: "OPERATOR_UNSPECIFIED" | "OPERATOR_AND" | "OPERATOR_OR"
formatenum
One of the following:
"OPERATOR_UNSPECIFIED"
"OPERATOR_AND"
"OPERATOR_OR"
filters?: Array<AttributeFilter { attribute, matcher } >
attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"
formatenum
One of the following:
"ATTRIBUTE_UNSPECIFIED"
"ATTRIBUTE_NAME"
"ATTRIBUTE_TITLE"
"ATTRIBUTE_DESCRIPTION"
matcher?: StringMatcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean
contains?: string
endsWith?: string
exact?: string
regex?: string
startsWith?: string
toolApprovals?: ApprovalRequirementFilter { always, only }

Approval filters that will automatically set the approval requirement on tools synced from an external source

always?: boolean
only?: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: "OPERATOR_UNSPECIFIED" | "OPERATOR_AND" | "OPERATOR_OR"
formatenum
One of the following:
"OPERATOR_UNSPECIFIED"
"OPERATOR_AND"
"OPERATOR_OR"
filters?: Array<AttributeFilter { attribute, matcher } >
attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"
formatenum
One of the following:
"ATTRIBUTE_UNSPECIFIED"
"ATTRIBUTE_NAME"
"ATTRIBUTE_TITLE"
"ATTRIBUTE_DESCRIPTION"
matcher?: StringMatcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean
contains?: string
endsWith?: string
exact?: string
regex?: string
startsWith?: string
url?: string
openapi?: ToolSetAdapterOpenAPI { baseUrl, excludeTools, headers, 5 more }
baseUrl?: string

Base URL for dispatching tool calls. If set, overrides the server resolved from the spec’s servers array.

excludeTools?: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: "OPERATOR_UNSPECIFIED" | "OPERATOR_AND" | "OPERATOR_OR"
formatenum
One of the following:
"OPERATOR_UNSPECIFIED"
"OPERATOR_AND"
"OPERATOR_OR"
filters?: Array<AttributeFilter { attribute, matcher } >
attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"
formatenum
One of the following:
"ATTRIBUTE_UNSPECIFIED"
"ATTRIBUTE_NAME"
"ATTRIBUTE_TITLE"
"ATTRIBUTE_DESCRIPTION"
matcher?: StringMatcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean
contains?: string
endsWith?: string
exact?: string
regex?: string
startsWith?: string
headers?: Record<string, string>

Headers sent when fetching the spec from a URL and when dispatching tool calls.

includeTools?: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: "OPERATOR_UNSPECIFIED" | "OPERATOR_AND" | "OPERATOR_OR"
formatenum
One of the following:
"OPERATOR_UNSPECIFIED"
"OPERATOR_AND"
"OPERATOR_OR"
filters?: Array<AttributeFilter { attribute, matcher } >
attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"
formatenum
One of the following:
"ATTRIBUTE_UNSPECIFIED"
"ATTRIBUTE_NAME"
"ATTRIBUTE_TITLE"
"ATTRIBUTE_DESCRIPTION"
matcher?: StringMatcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean
contains?: string
endsWith?: string
exact?: string
regex?: string
startsWith?: string
serverName?: string

Name of the server entry in the spec’s servers array (OpenAPI 3.2 server.name field). Used to select which server URL to dispatch to when base_url is not set. If unset, the first server is used. Ignored when base_url is set.

toolApprovals?: ApprovalRequirementFilter { always, only }

Approval filters that will automatically set the approval requirement on tools synced from an external source

always?: boolean
only?: ToolFilter { operator, filters }

Top-level filter with simple boolean logic (no nesting)

operator: "OPERATOR_UNSPECIFIED" | "OPERATOR_AND" | "OPERATOR_OR"
formatenum
One of the following:
"OPERATOR_UNSPECIFIED"
"OPERATOR_AND"
"OPERATOR_OR"
filters?: Array<AttributeFilter { attribute, matcher } >
attribute: "ATTRIBUTE_UNSPECIFIED" | "ATTRIBUTE_NAME" | "ATTRIBUTE_TITLE" | "ATTRIBUTE_DESCRIPTION"
formatenum
One of the following:
"ATTRIBUTE_UNSPECIFIED"
"ATTRIBUTE_NAME"
"ATTRIBUTE_TITLE"
"ATTRIBUTE_DESCRIPTION"
matcher?: StringMatcher { caseSensitive, contains, endsWith, 3 more }

String matching operations

caseSensitive?: boolean
contains?: string
endsWith?: string
exact?: string
regex?: string
startsWith?: string
uploadId?: string

ID of a COMPLETE Upload containing the OpenAPI spec document.

url?: string

URL to fetch the OpenAPI spec from. Synced automatically every hour.

description?: string
info?: ToolSetInfo { agentCount, createdBy, lastSync, toolCount }

Tool set information

agentCount?: number
createdBy?: Profile { metadata, spec }

A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.

metadata: AccountResourceMetadata { id, accountId, name, 3 more }

AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

id: string

Unique identifier for the resource (prefixed ULID, e.g., “apikey_01HXK…”)

accountId: string

Account this resource belongs to for multi-tenant isolation (prefixed ULID)

name: string

Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly

profileId: string
externalId?: string

External ID for the resource (e.g., a workflow ID from an external system)

labels?: Record<string, string>

Arbitrary key-value pairs for categorization and filtering Examples: {“environment”: “production”, “team”: “platform”, “version”: “v2”}

spec: ProfileSpec { type, email, name }

Configuration for a profile.

type: "PROFILE_TYPE_UNSPECIFIED" | "PROFILE_TYPE_USER" | "PROFILE_TYPE_API_KEY" | "PROFILE_TYPE_SYSTEM"

Whether this profile represents a human user, an API key, or a system principal.

formatenum
One of the following:
"PROFILE_TYPE_UNSPECIFIED"
"PROFILE_TYPE_USER"
"PROFILE_TYPE_API_KEY"
"PROFILE_TYPE_SYSTEM"
email?: string

Email address of the profile. Required and unique within an account for user profiles.

name?: string

Display name (e.g., “Bobby Tables”).

lastSync?: string
toolCount?: number