API Reference

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Webhooks

Unwrap

Function

Unsafe Unwrap

Function

ModelsExpand Collapse

UnsafeUnwrapWebhookEvent = object { data, timestamp, type }

The envelope for an objective event webhook delivery. Contains timestamp, event type, and the webhook data payload.

data: object { agent, agentVariation, objective, objectiveEvent }

The webhook data payload with flat top-level keys for agent, variation, objective, and event.

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: optional string

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

labels: optional map[string]

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

agentVariation: 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: optional string

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

labels: optional map[string]

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

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: optional string

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

labels: optional map[string]

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

objectiveEvent: object { data, metadata, contextWindowId, info }

data: ObjectiveEventData { assistantMessage, contextWindowCompacted, error, 9 more }

assistantMessage: optional AssistantMessage { content, toolCalls }

content: optional string

toolCalls: optional array of AssistantToolCall { arguments, functionName, tool }

arguments: optional string

functionName: optional string

tool: optional 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: optional 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: optional string

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

labels: optional map[string]

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

cadenyaProvidedTool: optional 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: optional string

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

labels: optional map[string]

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

tool: optional 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: optional string

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

labels: optional map[string]

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

contextWindowCompacted: optional ContextWindowCompacted { messagesCompacted, newContextWindow, strategies, summary }

messagesCompacted: optional number

Number of messages that were compacted

formatint32

newContextWindow: optional ObjectiveContextWindowData { completionTokens, objectiveId, previousWindowContinueInstructions, 2 more }

The new context window created by this compaction

completionTokens: optional number

A calculated value for how many completion tokens (output tokens) have been used in this context window

formatint32

objectiveId: optional string

The objective's ID that this window belongs to

previousWindowContinueInstructions: optional string

The instructions for this window to continue from a previous window's chat history.

promptTokens: optional number

A calculated value for how many prompt tokens (input tokens) have been used in this context window

formatint32

sequence: optional number

sequence is a numeric representation of which context window this is. Sequences are useful to perform a max(sequence) on in order to calculate how many context windows an objective has.

formatint32

strategies: optional array of string

The strategies that were applied during this compaction

summary: optional string

The summary generated by the summarization strategy, if used.

error: optional ObjectiveError { message, type }

message: optional string

type: optional string

subObjectiveCreated: optional SubObjectiveCreated { metadata }

metadata: optional 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: optional string

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

labels: optional map[string]

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

toolApprovalRequested: optional ToolApprovalRequested { toolCallId }

toolCallId: optional string

The ID of the objective tool call record. Use this ID with the ApproveToolCall or DenyToolCall RPCs to approve or deny the tool call.

toolApproved: optional ToolApproved { toolCallId }

toolCallId: optional string

The ID of the objective tool call record that was approved via the ApproveToolCall RPC.

toolCalled: optional ToolCalled { toolCallId }

toolCallId: optional string

The ID of the objective tool call record that was executed.

toolDenied: optional ToolDenied { memo, toolCallId }

memo: optional string

The memo provided by the reviewer when denying the tool call. This is passed to the agent to provide further instructions.

toolCallId: optional string

The ID of the objective tool call record that was denied via the DenyToolCall RPC.

toolError: optional ToolError { message, toolCallId }

message: optional string

toolCallId: optional string

The ID of the objective tool call record that encountered an error during execution.

toolResult: optional ToolResult { content, toolCallId }

content: optional string

toolCallId: optional string

type: optional string

userMessage: optional UserMessage { content }

content: optional string

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: optional string

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

labels: optional map[string]

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

contextWindowId: optional string

info: optional ObjectiveEventInfo { createdBy, objective }

createdBy: optional 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: optional string

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

labels: optional map[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" or "PROFILE_TYPE_API_KEY" or "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: optional string

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

name: optional string

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

objective: optional 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: optional string

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

labels: optional map[string]

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

timestamp: string

type: string

The event type, prefixed with objective_event. (e.g., objective_event.tool_result)