Skip to content
cadenya
Get started
API Reference
Objectives

Tool Calls

List objective tool calls
client.objectives.toolCalls.list(stringobjectiveID, ToolCallListParams { cursor, includeInfo, limit, status } query?, RequestOptionsoptions?): CursorPagination<ObjectiveToolCall { data, metadata, status, 2 more } >
GET/v1/objectives/{objectiveId}/tool_calls
Approve a tool call
client.objectives.toolCalls.approve(stringtoolCallID, ToolCallApproveParams { objectiveId } params, RequestOptionsoptions?): ObjectiveToolCall { data, metadata, status, 2 more }
PUT/v1/objectives/{objectiveId}/tool_calls/{toolCallId}/approve
Deny a tool call
client.objectives.toolCalls.deny(stringtoolCallID, ToolCallDenyParams { objectiveId, memo } params, RequestOptionsoptions?): ObjectiveToolCall { data, metadata, status, 2 more }
PUT/v1/objectives/{objectiveId}/tool_calls/{toolCallId}/deny
ModelsExpand Collapse
ObjectiveToolCall { data, metadata, status, 2 more }

ObjectiveToolCall is a record of a tool call made during an objective's execution. Tool calls are mutable — their status changes as they are approved, denied, or executed.

data: ObjectiveToolCallData { callable, arguments, memo, 2 more }
callable: CallableTool { agent, cadenyaProvidedTool, tool }

CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

agent?: ResourceMetadata { id, accountId, createdAt, 5 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)

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"}

cadenyaProvidedTool?: ResourceMetadata { id, accountId, createdAt, 5 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)

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"}

tool?: ResourceMetadata { id, accountId, createdAt, 5 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)

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"}

arguments?: Record<string, unknown>

The arguments passed to the tool

memo?: string

A memo supplied by the reviewer when denying the tool call

result?: string

The result content returned by the tool after execution

statusChangedBy?: Profile { metadata, spec }

Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).

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 }

ProfileSpec contains the profile-specific fields

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

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

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

Email address of the user (required, unique per account)

name?: string

Display name for the user (e.g., "Bobby Tables")

metadata: OperationMetadata { id, accountId, createdAt, 4 more }

Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

id: string

Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

accountId: string

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

createdAt: string

Timestamp when this operation was created ULID includes timestamp information, but this explicit field enables easier querying

formatdate-time
profileId: string

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

workspaceId: string

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

externalId?: string

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

labels?: Record<string, string>

Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

status: "TOOL_CALL_STATUS_UNSPECIFIED" | "TOOL_CALL_STATUS_AUTO_APPROVED" | "TOOL_CALL_STATUS_WAITING_FOR_APPROVAL" | 2 more

Current status of the tool call

formatenum
One of the following:
"TOOL_CALL_STATUS_UNSPECIFIED"
"TOOL_CALL_STATUS_AUTO_APPROVED"
"TOOL_CALL_STATUS_WAITING_FOR_APPROVAL"
"TOOL_CALL_STATUS_APPROVED"
"TOOL_CALL_STATUS_DENIED"
executionStatus?: "TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED" | "TOOL_CALL_EXECUTION_STATUS_PENDING" | "TOOL_CALL_EXECUTION_STATUS_RUNNING" | 2 more
formatenum
One of the following:
"TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED"
"TOOL_CALL_EXECUTION_STATUS_PENDING"
"TOOL_CALL_EXECUTION_STATUS_RUNNING"
"TOOL_CALL_EXECUTION_STATUS_COMPLETED"
"TOOL_CALL_EXECUTION_STATUS_ERRORED"
info?: ObjectiveToolCallInfo { createdBy, objective }
createdBy?: Profile { metadata, spec }

Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).

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 }

ProfileSpec contains the profile-specific fields

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

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

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

Email address of the user (required, unique per account)

name?: string

Display name for the user (e.g., "Bobby Tables")

objective?: OperationMetadata { id, accountId, createdAt, 4 more }

Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

id: string

Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

accountId: string

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

createdAt: string

Timestamp when this operation was created ULID includes timestamp information, but this explicit field enables easier querying

formatdate-time
profileId: string

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

workspaceId: string

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

externalId?: string

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

labels?: Record<string, string>

Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

ObjectiveToolCallData { callable, arguments, memo, 2 more }
callable: CallableTool { agent, cadenyaProvidedTool, tool }

CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).

agent?: ResourceMetadata { id, accountId, createdAt, 5 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)

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"}

cadenyaProvidedTool?: ResourceMetadata { id, accountId, createdAt, 5 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)

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"}

tool?: ResourceMetadata { id, accountId, createdAt, 5 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)

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"}

arguments?: Record<string, unknown>

The arguments passed to the tool

memo?: string

A memo supplied by the reviewer when denying the tool call

result?: string

The result content returned by the tool after execution

statusChangedBy?: Profile { metadata, spec }

Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).

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 }

ProfileSpec contains the profile-specific fields

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

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

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

Email address of the user (required, unique per account)

name?: string

Display name for the user (e.g., "Bobby Tables")

ObjectiveToolCallInfo { createdBy, objective }
createdBy?: Profile { metadata, spec }

Profile represents a human user at the account level. Profiles are account-scoped resources that can be associated with multiple workspaces through the Actor model. Authentication for profiles is handled via SSO/OAuth (WorkOS).

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 }

ProfileSpec contains the profile-specific fields

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

Type is the type of profile. User's are humans, API keys are computers. You know the deal.

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

Email address of the user (required, unique per account)

name?: string

Display name for the user (e.g., "Bobby Tables")

objective?: OperationMetadata { id, accountId, createdAt, 4 more }

Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

id: string

Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

accountId: string

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

createdAt: string

Timestamp when this operation was created ULID includes timestamp information, but this explicit field enables easier querying

formatdate-time
profileId: string

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

workspaceId: string

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

externalId?: string

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

labels?: Record<string, string>

Arbitrary key-value pairs for categorization and filtering Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}