Objectives
List objectives
Create a new objective
Get an objective by ID
List objective events
Continue an objective
Cancel an objective
Compact an objective
List objective context windows
ModelsExpand Collapse
class AssistantMessage { content, tool_calls }
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).
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
class AssistantToolCall { arguments, function_name, 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).
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
class CallableTool { agent, cadenya_provided_tool, 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).
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
class ContextWindowCompacted { messages_compacted, new_context_window, strategies, summary }
new_context_window: ObjectiveContextWindowData { completion_tokens, objective_id, previous_window_continue_instructions, 2 more }
The new context window created by this compaction
completion_tokens: Integer
A calculated value for how many completion tokens (output tokens) have been used in this context window
previous_window_continue_instructions: String
The instructions for this window to continue from a previous window’s chat history.
class MemoryRead { memory_entry_id, memory_layer_id, message }
MemoryRead is emitted each time the agent resolves a key against the memory stack and loads an entry. Lookups that miss (key not found in any layer) do not emit this event.
class MemoryReference { memory_entry_id, memory_layer_id }
MemoryReference identifies a memory layer or a specific entry within one, for composition into a memory stack. Used on objectives (where entry pinning is permitted).
memory_layer_id accepts both the canonical form (memlyr_…) and the external-id form (external_id:my-custom-id). The same applies to memory_entry_id when set.
class Objective { data, metadata, status, 2 more }
Agent resource
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Agent specification (user-provided configuration)
status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED
variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED
input_data_schema: Hash[Symbol, untyped]
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.
output_definition: Hash[Symbol, untyped]
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.
AgentInfo contains simple information about an agent for display or quick reference
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.
data: untyped
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
initial_message: String
The initial message sent to the agent. This becomes the first user message in the LLM chat history.
Memory layers/entries to push onto this objective’s memory stack on top of the baseline stack inherited from the selected variation.
Array order is push order: the first element sits lower in the objective’s contribution to the stack; the LAST element ends up on top of the effective stack. Entries pinned via memory_entry_id behave as single-entry layers at their position.
System-managed layers (e.g., episodic) cannot be referenced here; they attach themselves automatically based on episodic_key.
Stack size cap: the TOTAL effective stack (variation’s memory layers
- this field) must not exceed 10 entries. A request that would produce an effective stack larger than 10 is rejected with InvalidArgument.
output: Hash[Symbol, untyped]
The output of the objective, populated when the objective completes. Will match the schema of output_json_schema or output_json_inferred.
output_definition: Hash[Symbol, untyped]
Snapshot of the agent spec’s output_definition at objective creation time. When present, the objective will run an extraction step after the LLM finishes.
parent_objective_id: String
A parent objective means the objective was spawned off using a separate agent to complete an objective
source_schedule_id: String
ID of the AgentSchedule that produced this objective, when applicable. Populated when the objective is created from a schedule fire; empty when the objective was created via CreateObjective directly.
AgentVariation resource
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
AgentVariationSpec defines the operational configuration for a variation
compaction_config: AgentVariationSpecCompactionConfig { summarization, tool_result_clearing, trigger_threshold }
enable_episodic_memory: bool
Enable episodic memory for objectives using this variation. When true, the system automatically creates a document namespace for each objective using the objective’s episodic_key as the external_id, allowing the agent to store and retrieve documents specific to that episode.
episodic_memory_ttl: Integer
How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely.
progressive_discovery: AgentVariationSpecProgressiveDiscovery { hints, max_tools, rerank_threshold }
ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it. Max tools is the maximum number of tools that can be discovered per search. Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
rerank_threshold: Float
Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.
AgentVariationInfo provides read-only summary information about a variation
All tools, tool sets, and sub-agents assigned to this variation. Populated on reads so clients can render a variation’s full assignment list without calling the add/remove endpoints just to enumerate.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
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.
Read-only list of memory layer assignments for this variation,
returned in ascending position (bottom → top). Capped at 10 entries.
id: String
Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer’s id.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
position: Integer
Position in the variation’s baseline stack. Lower values sit lower; the highest-position assignment is on top of the variation’s baseline. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment’s position is rejected with InvalidArgument.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
ObjectiveInfo provides read-only aggregated statistics about an objective’s execution
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
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.
The effective memory stack at objective creation time, flattened from the variation’s baseline plus ObjectiveData.memory_stack. Order is push order (last = top). Returned on reads so clients can see exactly what stack the objective is using without having to re-join variation state.
total_context_windows: Integer
Total number of context windows that this objective has generated
total_input_tokens: Integer
Total input tokens consumed across all LLM completions across all context windows
Read-only list of the last five windows of execution for this objective, ordered by most recent first. Is only included in singular RPC calls (GetObjective, for example).
data: ObjectiveContextWindowData { completion_tokens, objective_id, previous_window_continue_instructions, 2 more }
completion_tokens: Integer
A calculated value for how many completion tokens (output tokens) have been used in this context window
previous_window_continue_instructions: String
The instructions for this window to continue from a previous window’s chat history.
info: Info{ created_by, objective}
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.
class ObjectiveContextWindow { data, metadata, info }
ObjectiveContextWindow is a window of chat completions that is grouped together to prevent context-window overflows. Context windows also allow agents to compact their windows and carry on into a new one.
data: ObjectiveContextWindowData { completion_tokens, objective_id, previous_window_continue_instructions, 2 more }
completion_tokens: Integer
A calculated value for how many completion tokens (output tokens) have been used in this context window
previous_window_continue_instructions: String
The instructions for this window to continue from a previous window’s chat history.
info: Info{ created_by, objective}
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.
class ObjectiveContextWindowData { completion_tokens, objective_id, previous_window_continue_instructions, 2 more }
completion_tokens: Integer
A calculated value for how many completion tokens (output tokens) have been used in this context window
previous_window_continue_instructions: String
The instructions for this window to continue from a previous window’s chat history.
class ObjectiveData { agent, data, initial_message, 8 more }
Agent resource
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Agent specification (user-provided configuration)
status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED
variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED
input_data_schema: Hash[Symbol, untyped]
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.
output_definition: Hash[Symbol, untyped]
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.
AgentInfo contains simple information about an agent for display or quick reference
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.
data: untyped
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
initial_message: String
The initial message sent to the agent. This becomes the first user message in the LLM chat history.
Memory layers/entries to push onto this objective’s memory stack on top of the baseline stack inherited from the selected variation.
Array order is push order: the first element sits lower in the objective’s contribution to the stack; the LAST element ends up on top of the effective stack. Entries pinned via memory_entry_id behave as single-entry layers at their position.
System-managed layers (e.g., episodic) cannot be referenced here; they attach themselves automatically based on episodic_key.
Stack size cap: the TOTAL effective stack (variation’s memory layers
- this field) must not exceed 10 entries. A request that would produce an effective stack larger than 10 is rejected with InvalidArgument.
output: Hash[Symbol, untyped]
The output of the objective, populated when the objective completes. Will match the schema of output_json_schema or output_json_inferred.
output_definition: Hash[Symbol, untyped]
Snapshot of the agent spec’s output_definition at objective creation time. When present, the objective will run an extraction step after the LLM finishes.
parent_objective_id: String
A parent objective means the objective was spawned off using a separate agent to complete an objective
source_schedule_id: String
ID of the AgentSchedule that produced this objective, when applicable. Populated when the objective is created from a schedule fire; empty when the objective was created via CreateObjective directly.
AgentVariation resource
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
AgentVariationSpec defines the operational configuration for a variation
compaction_config: AgentVariationSpecCompactionConfig { summarization, tool_result_clearing, trigger_threshold }
enable_episodic_memory: bool
Enable episodic memory for objectives using this variation. When true, the system automatically creates a document namespace for each objective using the objective’s episodic_key as the external_id, allowing the agent to store and retrieve documents specific to that episode.
episodic_memory_ttl: Integer
How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely.
progressive_discovery: AgentVariationSpecProgressiveDiscovery { hints, max_tools, rerank_threshold }
ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it. Max tools is the maximum number of tools that can be discovered per search. Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
rerank_threshold: Float
Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.
AgentVariationInfo provides read-only summary information about a variation
All tools, tool sets, and sub-agents assigned to this variation. Populated on reads so clients can render a variation’s full assignment list without calling the add/remove endpoints just to enumerate.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
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.
Read-only list of memory layer assignments for this variation,
returned in ascending position (bottom → top). Capped at 10 entries.
id: String
Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer’s id.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
position: Integer
Position in the variation’s baseline stack. Lower values sit lower; the highest-position assignment is on top of the variation’s baseline. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment’s position is rejected with InvalidArgument.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
class ObjectiveEventData { assistant_message, cancelled, context_window_compacted, 13 more }
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).
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
cancelled: Cancelled{ message}
ObjectiveCancelled is the terminal event written when an objective is cancelled. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted.
context_window_compacted: ContextWindowCompacted { messages_compacted, new_context_window, strategies, summary }
new_context_window: ObjectiveContextWindowData { completion_tokens, objective_id, previous_window_continue_instructions, 2 more }
The new context window created by this compaction
completion_tokens: Integer
A calculated value for how many completion tokens (output tokens) have been used in this context window
previous_window_continue_instructions: String
The instructions for this window to continue from a previous window’s chat history.
finalized: Finalized{ output}
ObjectiveFinalized is the terminal event written when an objective is finalized. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted.
MemoryRead is emitted each time the agent resolves a key against the memory stack and loads an entry. Lookups that miss (key not found in any layer) do not emit this event.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
class ObjectiveEventInfo { created_by, objective }
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.
class ObjectiveEventWebhookData { data, timestamp, type }
The envelope for an objective event webhook delivery. Contains timestamp, event type, and the webhook data payload.
data: Data{ agent, agent_variation, objective, objective_event}
The webhook data payload with flat top-level keys for agent, variation, objective, and event.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
objective_event: ObjectiveEvent{ data, metadata, context_window_id, info}
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).
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
cancelled: Cancelled{ message}
ObjectiveCancelled is the terminal event written when an objective is cancelled. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted.
context_window_compacted: ContextWindowCompacted { messages_compacted, new_context_window, strategies, summary }
new_context_window: ObjectiveContextWindowData { completion_tokens, objective_id, previous_window_continue_instructions, 2 more }
The new context window created by this compaction
completion_tokens: Integer
A calculated value for how many completion tokens (output tokens) have been used in this context window
previous_window_continue_instructions: String
The instructions for this window to continue from a previous window’s chat history.
finalized: Finalized{ output}
ObjectiveFinalized is the terminal event written when an objective is finalized. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted.
MemoryRead is emitted each time the agent resolves a key against the memory stack and loads an entry. Lookups that miss (key not found in any layer) do not emit this event.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
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.
class ObjectiveInfo { agent, agent_variation, created_by, 6 more }
ObjectiveInfo provides read-only aggregated statistics about an objective’s execution
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
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.
The effective memory stack at objective creation time, flattened from the variation’s baseline plus ObjectiveData.memory_stack. Order is push order (last = top). Returned on reads so clients can see exactly what stack the objective is using without having to re-join variation state.
total_context_windows: Integer
Total number of context windows that this objective has generated
total_input_tokens: Integer
Total input tokens consumed across all LLM completions across all context windows
class SubAgentSpawned { agent, objective, task }
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
class SubAgentUpdated { agent, message, objective, status }
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
class ObjectiveListEventsResponse { data, metadata, context_window_id, info }
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).
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
cancelled: Cancelled{ message}
ObjectiveCancelled is the terminal event written when an objective is cancelled. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted.
context_window_compacted: ContextWindowCompacted { messages_compacted, new_context_window, strategies, summary }
new_context_window: ObjectiveContextWindowData { completion_tokens, objective_id, previous_window_continue_instructions, 2 more }
The new context window created by this compaction
completion_tokens: Integer
A calculated value for how many completion tokens (output tokens) have been used in this context window
previous_window_continue_instructions: String
The instructions for this window to continue from a previous window’s chat history.
finalized: Finalized{ output}
ObjectiveFinalized is the terminal event written when an objective is finalized. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted.
MemoryRead is emitted each time the agent resolves a key against the memory stack and loads an entry. Lookups that miss (key not found in any layer) do not emit this event.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
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.
class ObjectiveContinueResponse { data, metadata, context_window_id, info }
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).
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
cancelled: Cancelled{ message}
ObjectiveCancelled is the terminal event written when an objective is cancelled. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted.
context_window_compacted: ContextWindowCompacted { messages_compacted, new_context_window, strategies, summary }
new_context_window: ObjectiveContextWindowData { completion_tokens, objective_id, previous_window_continue_instructions, 2 more }
The new context window created by this compaction
completion_tokens: Integer
A calculated value for how many completion tokens (output tokens) have been used in this context window
previous_window_continue_instructions: String
The instructions for this window to continue from a previous window’s chat history.
finalized: Finalized{ output}
ObjectiveFinalized is the terminal event written when an objective is finalized. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted.
MemoryRead is emitted each time the agent resolves a key against the memory stack and loads an entry. Lookups that miss (key not found in any layer) do not emit this event.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
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.
class ObjectiveCompactResponse { context_window }
Compact objective response
context_window: ObjectiveContextWindowData { completion_tokens, objective_id, previous_window_continue_instructions, 2 more }
The new context window created by the compaction
completion_tokens: Integer
A calculated value for how many completion tokens (output tokens) have been used in this context window
previous_window_continue_instructions: String
The instructions for this window to continue from a previous window’s chat history.
ObjectivesTools
List objective tools
ModelsExpand Collapse
class ObjectiveTool { metadata, snapshot }
ObjectiveTool represents a tool that was assigned to an objective.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
Snapshot of the tool at the time it was assigned to the objective. Because tools can change over time, snapshots are used to ensure tools don’t change unexpectedly during an objective’s lifecycle.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
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.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
ObjectivesTool Calls
List objective tool calls
Approve a tool call
Deny a tool call
ModelsExpand Collapse
class 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.
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).
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
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.
status: :TOOL_CALL_STATUS_UNSPECIFIED | :TOOL_CALL_STATUS_AUTO_APPROVED | :TOOL_CALL_STATUS_WAITING_FOR_APPROVAL | 2 more
execution_status: :TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED | :TOOL_CALL_EXECUTION_STATUS_PENDING | :TOOL_CALL_EXECUTION_STATUS_RUNNING | 2 more
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.
class ObjectiveToolCallData { callable, arguments, memo, 2 more }
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).
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
name: String
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
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.
class ObjectiveToolCallInfo { created_by, objective }
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.
ObjectivesTasks
List objective tasks
Get an objective task by ID
ModelsExpand Collapse
class ObjectiveTask { data, metadata }
ObjectiveTask represents a task within an objective, typically created and managed by an AI agent to track progress toward completing the objective.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
ObjectivesFeedback
Submit feedback for an objective
List feedback for an objective
ModelsExpand Collapse
class ObjectiveFeedback { data, metadata, info }
ObjectiveFeedback represents feedback submitted for an objective’s execution. Feedback is used to score agent variations and improve agent performance over time.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
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.
class ObjectiveFeedbackInfo { agent_variation, objective, submitted_by }
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
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.