# Objectives ## List objectives `$ cadenya objectives list` **get** `/v1/objectives` Lists all objectives in the workspace ### Parameters - `--agent-id: optional string` Agent ID for filtering - `--cursor: optional string` Pagination cursor from previous response - `--include-info: optional boolean` When set to true you may use more of your alloted API rate-limit - `--limit: optional number` Maximum number of results to return - `--parent-objective-id: optional string` Optional filters - `--profile-id: optional string` - `--sort-order: optional string` Sort order for results (asc or desc by creation time) - `--state: optional "STATE_UNSPECIFIED" or "STATE_PENDING" or "STATE_RUNNING" or 3 more` Filter by state ### Returns - `ListObjectivesResponse: object { items, pagination }` - `items: optional array of Objective` - `data: object { agent, data, initialMessage, 4 more }` - `agent: optional object { metadata, spec, info }` Agent resource - `metadata: object { 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 - `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"} - `spec: object { status, variationSelectionMode, description, webhookEventsUrl }` Agent specification (user-provided configuration) - `status: "AGENT_STATUS_UNSPECIFIED" or "AGENT_STATUS_DRAFT" or "AGENT_STATUS_PUBLISHED" or "AGENT_STATUS_ARCHIVED"` Status of the agent - `"AGENT_STATUS_UNSPECIFIED"` - `"AGENT_STATUS_DRAFT"` - `"AGENT_STATUS_PUBLISHED"` - `"AGENT_STATUS_ARCHIVED"` - `variationSelectionMode: "VARIATION_SELECTION_MODE_UNSPECIFIED" or "VARIATION_SELECTION_MODE_RANDOM" or "VARIATION_SELECTION_MODE_WEIGHTED"` Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified - `"VARIATION_SELECTION_MODE_UNSPECIFIED"` - `"VARIATION_SELECTION_MODE_RANDOM"` - `"VARIATION_SELECTION_MODE_WEIGHTED"` - `description: optional string` Description of the agent's purpose - `webhookEventsUrl: optional string` The URL that Cadenya will send events for any objective assigned to the agent. - `info: optional object { createdBy, variationCount }` AgentInfo contains simple information about an agent for display or quick reference - `createdBy: optional object { 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: object { 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: object { 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. - `"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") - `variationCount: optional number` - `data: optional unknown` 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. - `initialMessage: optional string` The initial message sent to the agent. This becomes the first user message in the LLM chat history. - `parentObjectiveId: optional string` A parent objective means the objective was spawned off using a separate agent to complete an objective - `secrets: optional array of ObjectiveDataSecret` Secrets that can be used in the headers for tool calls using the secret interpolation format. - `name: optional string` - `value: optional string` - `systemPrompt: optional string` system_prompt is read-only, derived from the selected variation's prompt - `variation: optional object { metadata, spec, info }` AgentVariation resource - `metadata: object { 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 - `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"} - `spec: object { compactionConfig, constraints, description, 6 more }` AgentVariationSpec defines the operational configuration for a variation - `compactionConfig: optional object { summarization, toolResultClearing, triggerThreshold }` CompactionConfig defines how context window compaction behaves for objectives using this variation. - `summarization: optional object { instructions }` SummarizationStrategy configures LLM-powered summarization of older conversation turns. - `instructions: optional string` Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." - `toolResultClearing: optional object { preserveRecentResults }` ToolResultClearingStrategy configures clearing of older tool result content. - `preserveRecentResults: optional number` Number of most recent tool call results to keep intact. Older tool results have their content replaced with "[result cleared]" while preserving the assistant tool call message (function name, arguments). Default: 2 - `triggerThreshold: optional number` Trigger threshold as a percentage of the model's context window (0.0 to 1.0). When input tokens reach this percentage of the model's limit, compaction triggers. Default: 0.75 (75%) - `constraints: optional object { maxSubObjectives, maxToolCalls }` Execution constraints - `maxSubObjectives: optional number` The maximum number of sub-objectives that can be created. 0 means no limit. - `maxToolCalls: optional number` The maximum number of tool calls that can be made. 0 means no limit. - `description: optional string` Human-readable description of what this variation does or when it should be used - `enableEpisodicMemory: optional boolean` 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. - `episodicMemoryTtl: optional number` 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. - `modelConfig: optional object { modelId, temperature }` ModelConfig defines the model configuration for a variation - `modelId: optional string` The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5") - `temperature: optional number` Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness - `prompt: optional string` The system prompt for this variation - `toolSelection: optional object { assignedTools, autoDiscovery }` Tool selection strategy - `assignedTools: optional object { allowDiscovery }` AssignedTools is used to indicate that the agent should only use the tools/tool sets that are explicitly assigned to it. Allow discovery is used when the agent thinks it needs to discover more tools. - `allowDiscovery: optional boolean` - `autoDiscovery: optional object { hints, maxTools }` AutoDiscovery 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. 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. - `hints: optional array of string` - `maxTools: optional number` - `weight: optional number` Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights). Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest. - `info: optional object { assignments, createdBy, feedbackCount, 5 more }` AgentVariationInfo provides read-only summary information about a variation - `assignments: optional array of VariationAssignment` 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. - `id: optional string` - `agent: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `tool: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `toolSet: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `feedbackCount: optional number` Total number of objective feedbacks received for this variation - `model: optional object { 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 - `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"} - `score: optional number` Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta). Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative. - `subAgentCount: optional number` Number of sub-agents assigned to this variation - `toolCount: optional number` Number of individual tools assigned to this variation - `toolSetCount: optional number` Number of tool sets assigned to this variation - `metadata: object { 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 - `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"} - `status: object { state, message }` - `state: "STATE_UNSPECIFIED" or "STATE_PENDING" or "STATE_RUNNING" or 3 more` - `"STATE_UNSPECIFIED"` - `"STATE_PENDING"` - `"STATE_RUNNING"` - `"STATE_COMPLETED"` - `"STATE_FAILED"` - `"STATE_CANCELLED"` - `message: optional string` - `info: optional object { callableTools, createdBy, totalContextWindows, 4 more }` ObjectiveInfo provides read-only aggregated statistics about an objective's execution - `callableTools: optional array of CallableTool` List of callable tools assigned to the agent for this objective Includes tools, agents, and cadenya-provided tools from the agent's configuration - `agent: optional object { 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 - `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 object { 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 - `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 object { 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 - `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"} - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `totalContextWindows: optional number` Total number of context windows that this objective has generated - `totalEvents: optional number` Total number of events generated during this objective's execution - `totalInputTokens: optional number` Total input tokens consumed across all LLM completions across all context windows - `totalOutputTokens: optional number` Total output tokens generated across all LLM completions across all context windows - `totalToolCalls: optional number` Total number of tool calls made during execution - `lastFiveWindows: optional array of ObjectiveContextWindow` 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: object { completionTokens, objectiveId, previousWindowContinueInstructions, 2 more }` - `completionTokens: optional number` A calculated value for how many completion tokens (output tokens) have been used in this context window - `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 - `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. - `metadata: object { 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 - `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"} - `info: optional object { createdBy, objective }` - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `objective: optional object { 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 - `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"} - `pagination: optional object { nextCursor, total }` - `nextCursor: optional string` - `total: optional number` ### Example ```cli cadenya objectives list \ --api-key 'My API Key' ``` #### Response ```json { "items": [ { "data": { "agent": { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "status": "AGENT_STATUS_UNSPECIFIED", "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED", "description": "description", "webhookEventsUrl": "webhookEventsUrl" }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "variationCount": 0 } }, "data": {}, "initialMessage": "initialMessage", "parentObjectiveId": "parentObjectiveId", "secrets": [ { "name": "name", "value": "value" } ], "systemPrompt": "systemPrompt", "variation": { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "compactionConfig": { "summarization": { "instructions": "instructions" }, "toolResultClearing": { "preserveRecentResults": 0 }, "triggerThreshold": 0 }, "constraints": { "maxSubObjectives": 0, "maxToolCalls": 0 }, "description": "description", "enableEpisodicMemory": true, "episodicMemoryTtl": 0, "modelConfig": { "modelId": "modelId", "temperature": 0 }, "prompt": "prompt", "toolSelection": { "assignedTools": { "allowDiscovery": true }, "autoDiscovery": { "hints": [ "string" ], "maxTools": 0 } }, "weight": 0 }, "info": { "assignments": [ { "id": "id", "agent": { "id": "id", "name": "name" }, "tool": { "id": "id", "name": "name" }, "toolSet": { "id": "id", "name": "name" } } ], "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "feedbackCount": 0, "model": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "score": 0, "subAgentCount": 0, "toolCount": 0, "toolSetCount": 0 } } }, "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "status": { "state": "STATE_UNSPECIFIED", "message": "message" }, "info": { "callableTools": [ { "agent": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "cadenyaProvidedTool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "tool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } ], "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "totalContextWindows": 0, "totalEvents": 0, "totalInputTokens": 0, "totalOutputTokens": 0, "totalToolCalls": 0 }, "lastFiveWindows": [ { "data": { "completionTokens": 0, "objectiveId": "objectiveId", "previousWindowContinueInstructions": "previousWindowContinueInstructions", "promptTokens": 0, "sequence": 0 }, "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "objective": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } } ] } ], "pagination": { "nextCursor": "nextCursor", "total": 0 } } ``` ## Create a new objective `$ cadenya objectives create` **post** `/v1/objectives` Creates a new objective in the workspace ### Parameters - `--agent-id: string` - `--data: object { agent, data, initialMessage, 4 more }` - `--metadata: object { externalId, labels }` CreateOperationMetadata contains the user-provided fields for creating an operation. Read-only fields (id, account_id, workspace_id, created_at, profile_id) are excluded since they are set by the server. - `--variation-id: optional string` Optional explicit variation selection. Overrides the agent's variation_selection_mode. ### Returns - `objective: object { data, metadata, status, 2 more }` - `data: object { agent, data, initialMessage, 4 more }` - `agent: optional object { metadata, spec, info }` Agent resource - `metadata: object { 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 - `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"} - `spec: object { status, variationSelectionMode, description, webhookEventsUrl }` Agent specification (user-provided configuration) - `status: "AGENT_STATUS_UNSPECIFIED" or "AGENT_STATUS_DRAFT" or "AGENT_STATUS_PUBLISHED" or "AGENT_STATUS_ARCHIVED"` Status of the agent - `"AGENT_STATUS_UNSPECIFIED"` - `"AGENT_STATUS_DRAFT"` - `"AGENT_STATUS_PUBLISHED"` - `"AGENT_STATUS_ARCHIVED"` - `variationSelectionMode: "VARIATION_SELECTION_MODE_UNSPECIFIED" or "VARIATION_SELECTION_MODE_RANDOM" or "VARIATION_SELECTION_MODE_WEIGHTED"` Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified - `"VARIATION_SELECTION_MODE_UNSPECIFIED"` - `"VARIATION_SELECTION_MODE_RANDOM"` - `"VARIATION_SELECTION_MODE_WEIGHTED"` - `description: optional string` Description of the agent's purpose - `webhookEventsUrl: optional string` The URL that Cadenya will send events for any objective assigned to the agent. - `info: optional object { createdBy, variationCount }` AgentInfo contains simple information about an agent for display or quick reference - `createdBy: optional object { 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: object { 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: object { 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. - `"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") - `variationCount: optional number` - `data: optional unknown` 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. - `initialMessage: optional string` The initial message sent to the agent. This becomes the first user message in the LLM chat history. - `parentObjectiveId: optional string` A parent objective means the objective was spawned off using a separate agent to complete an objective - `secrets: optional array of ObjectiveDataSecret` Secrets that can be used in the headers for tool calls using the secret interpolation format. - `name: optional string` - `value: optional string` - `systemPrompt: optional string` system_prompt is read-only, derived from the selected variation's prompt - `variation: optional object { metadata, spec, info }` AgentVariation resource - `metadata: object { 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 - `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"} - `spec: object { compactionConfig, constraints, description, 6 more }` AgentVariationSpec defines the operational configuration for a variation - `compactionConfig: optional object { summarization, toolResultClearing, triggerThreshold }` CompactionConfig defines how context window compaction behaves for objectives using this variation. - `summarization: optional object { instructions }` SummarizationStrategy configures LLM-powered summarization of older conversation turns. - `instructions: optional string` Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." - `toolResultClearing: optional object { preserveRecentResults }` ToolResultClearingStrategy configures clearing of older tool result content. - `preserveRecentResults: optional number` Number of most recent tool call results to keep intact. Older tool results have their content replaced with "[result cleared]" while preserving the assistant tool call message (function name, arguments). Default: 2 - `triggerThreshold: optional number` Trigger threshold as a percentage of the model's context window (0.0 to 1.0). When input tokens reach this percentage of the model's limit, compaction triggers. Default: 0.75 (75%) - `constraints: optional object { maxSubObjectives, maxToolCalls }` Execution constraints - `maxSubObjectives: optional number` The maximum number of sub-objectives that can be created. 0 means no limit. - `maxToolCalls: optional number` The maximum number of tool calls that can be made. 0 means no limit. - `description: optional string` Human-readable description of what this variation does or when it should be used - `enableEpisodicMemory: optional boolean` 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. - `episodicMemoryTtl: optional number` 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. - `modelConfig: optional object { modelId, temperature }` ModelConfig defines the model configuration for a variation - `modelId: optional string` The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5") - `temperature: optional number` Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness - `prompt: optional string` The system prompt for this variation - `toolSelection: optional object { assignedTools, autoDiscovery }` Tool selection strategy - `assignedTools: optional object { allowDiscovery }` AssignedTools is used to indicate that the agent should only use the tools/tool sets that are explicitly assigned to it. Allow discovery is used when the agent thinks it needs to discover more tools. - `allowDiscovery: optional boolean` - `autoDiscovery: optional object { hints, maxTools }` AutoDiscovery 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. 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. - `hints: optional array of string` - `maxTools: optional number` - `weight: optional number` Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights). Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest. - `info: optional object { assignments, createdBy, feedbackCount, 5 more }` AgentVariationInfo provides read-only summary information about a variation - `assignments: optional array of VariationAssignment` 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. - `id: optional string` - `agent: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `tool: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `toolSet: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `feedbackCount: optional number` Total number of objective feedbacks received for this variation - `model: optional object { 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 - `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"} - `score: optional number` Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta). Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative. - `subAgentCount: optional number` Number of sub-agents assigned to this variation - `toolCount: optional number` Number of individual tools assigned to this variation - `toolSetCount: optional number` Number of tool sets assigned to this variation - `metadata: object { 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 - `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"} - `status: object { state, message }` - `state: "STATE_UNSPECIFIED" or "STATE_PENDING" or "STATE_RUNNING" or 3 more` - `"STATE_UNSPECIFIED"` - `"STATE_PENDING"` - `"STATE_RUNNING"` - `"STATE_COMPLETED"` - `"STATE_FAILED"` - `"STATE_CANCELLED"` - `message: optional string` - `info: optional object { callableTools, createdBy, totalContextWindows, 4 more }` ObjectiveInfo provides read-only aggregated statistics about an objective's execution - `callableTools: optional array of CallableTool` List of callable tools assigned to the agent for this objective Includes tools, agents, and cadenya-provided tools from the agent's configuration - `agent: optional object { 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 - `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 object { 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 - `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 object { 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 - `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"} - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `totalContextWindows: optional number` Total number of context windows that this objective has generated - `totalEvents: optional number` Total number of events generated during this objective's execution - `totalInputTokens: optional number` Total input tokens consumed across all LLM completions across all context windows - `totalOutputTokens: optional number` Total output tokens generated across all LLM completions across all context windows - `totalToolCalls: optional number` Total number of tool calls made during execution - `lastFiveWindows: optional array of ObjectiveContextWindow` 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: object { completionTokens, objectiveId, previousWindowContinueInstructions, 2 more }` - `completionTokens: optional number` A calculated value for how many completion tokens (output tokens) have been used in this context window - `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 - `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. - `metadata: object { 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 - `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"} - `info: optional object { createdBy, objective }` - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `objective: optional object { 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 - `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"} ### Example ```cli cadenya objectives create \ --api-key 'My API Key' \ --agent-id agentId \ --data '{}' \ --metadata '{}' ``` #### Response ```json { "data": { "agent": { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "status": "AGENT_STATUS_UNSPECIFIED", "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED", "description": "description", "webhookEventsUrl": "webhookEventsUrl" }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "variationCount": 0 } }, "data": {}, "initialMessage": "initialMessage", "parentObjectiveId": "parentObjectiveId", "secrets": [ { "name": "name", "value": "value" } ], "systemPrompt": "systemPrompt", "variation": { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "compactionConfig": { "summarization": { "instructions": "instructions" }, "toolResultClearing": { "preserveRecentResults": 0 }, "triggerThreshold": 0 }, "constraints": { "maxSubObjectives": 0, "maxToolCalls": 0 }, "description": "description", "enableEpisodicMemory": true, "episodicMemoryTtl": 0, "modelConfig": { "modelId": "modelId", "temperature": 0 }, "prompt": "prompt", "toolSelection": { "assignedTools": { "allowDiscovery": true }, "autoDiscovery": { "hints": [ "string" ], "maxTools": 0 } }, "weight": 0 }, "info": { "assignments": [ { "id": "id", "agent": { "id": "id", "name": "name" }, "tool": { "id": "id", "name": "name" }, "toolSet": { "id": "id", "name": "name" } } ], "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "feedbackCount": 0, "model": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "score": 0, "subAgentCount": 0, "toolCount": 0, "toolSetCount": 0 } } }, "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "status": { "state": "STATE_UNSPECIFIED", "message": "message" }, "info": { "callableTools": [ { "agent": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "cadenyaProvidedTool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "tool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } ], "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "totalContextWindows": 0, "totalEvents": 0, "totalInputTokens": 0, "totalOutputTokens": 0, "totalToolCalls": 0 }, "lastFiveWindows": [ { "data": { "completionTokens": 0, "objectiveId": "objectiveId", "previousWindowContinueInstructions": "previousWindowContinueInstructions", "promptTokens": 0, "sequence": 0 }, "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "objective": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } } ] } ``` ## Get an objective by ID `$ cadenya objectives retrieve` **get** `/v1/objectives/{id}` Retrieves an objective by ID from the workspace ### Parameters - `--id: string` ### Returns - `objective: object { data, metadata, status, 2 more }` - `data: object { agent, data, initialMessage, 4 more }` - `agent: optional object { metadata, spec, info }` Agent resource - `metadata: object { 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 - `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"} - `spec: object { status, variationSelectionMode, description, webhookEventsUrl }` Agent specification (user-provided configuration) - `status: "AGENT_STATUS_UNSPECIFIED" or "AGENT_STATUS_DRAFT" or "AGENT_STATUS_PUBLISHED" or "AGENT_STATUS_ARCHIVED"` Status of the agent - `"AGENT_STATUS_UNSPECIFIED"` - `"AGENT_STATUS_DRAFT"` - `"AGENT_STATUS_PUBLISHED"` - `"AGENT_STATUS_ARCHIVED"` - `variationSelectionMode: "VARIATION_SELECTION_MODE_UNSPECIFIED" or "VARIATION_SELECTION_MODE_RANDOM" or "VARIATION_SELECTION_MODE_WEIGHTED"` Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified - `"VARIATION_SELECTION_MODE_UNSPECIFIED"` - `"VARIATION_SELECTION_MODE_RANDOM"` - `"VARIATION_SELECTION_MODE_WEIGHTED"` - `description: optional string` Description of the agent's purpose - `webhookEventsUrl: optional string` The URL that Cadenya will send events for any objective assigned to the agent. - `info: optional object { createdBy, variationCount }` AgentInfo contains simple information about an agent for display or quick reference - `createdBy: optional object { 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: object { 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: object { 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. - `"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") - `variationCount: optional number` - `data: optional unknown` 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. - `initialMessage: optional string` The initial message sent to the agent. This becomes the first user message in the LLM chat history. - `parentObjectiveId: optional string` A parent objective means the objective was spawned off using a separate agent to complete an objective - `secrets: optional array of ObjectiveDataSecret` Secrets that can be used in the headers for tool calls using the secret interpolation format. - `name: optional string` - `value: optional string` - `systemPrompt: optional string` system_prompt is read-only, derived from the selected variation's prompt - `variation: optional object { metadata, spec, info }` AgentVariation resource - `metadata: object { 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 - `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"} - `spec: object { compactionConfig, constraints, description, 6 more }` AgentVariationSpec defines the operational configuration for a variation - `compactionConfig: optional object { summarization, toolResultClearing, triggerThreshold }` CompactionConfig defines how context window compaction behaves for objectives using this variation. - `summarization: optional object { instructions }` SummarizationStrategy configures LLM-powered summarization of older conversation turns. - `instructions: optional string` Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." - `toolResultClearing: optional object { preserveRecentResults }` ToolResultClearingStrategy configures clearing of older tool result content. - `preserveRecentResults: optional number` Number of most recent tool call results to keep intact. Older tool results have their content replaced with "[result cleared]" while preserving the assistant tool call message (function name, arguments). Default: 2 - `triggerThreshold: optional number` Trigger threshold as a percentage of the model's context window (0.0 to 1.0). When input tokens reach this percentage of the model's limit, compaction triggers. Default: 0.75 (75%) - `constraints: optional object { maxSubObjectives, maxToolCalls }` Execution constraints - `maxSubObjectives: optional number` The maximum number of sub-objectives that can be created. 0 means no limit. - `maxToolCalls: optional number` The maximum number of tool calls that can be made. 0 means no limit. - `description: optional string` Human-readable description of what this variation does or when it should be used - `enableEpisodicMemory: optional boolean` 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. - `episodicMemoryTtl: optional number` 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. - `modelConfig: optional object { modelId, temperature }` ModelConfig defines the model configuration for a variation - `modelId: optional string` The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5") - `temperature: optional number` Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness - `prompt: optional string` The system prompt for this variation - `toolSelection: optional object { assignedTools, autoDiscovery }` Tool selection strategy - `assignedTools: optional object { allowDiscovery }` AssignedTools is used to indicate that the agent should only use the tools/tool sets that are explicitly assigned to it. Allow discovery is used when the agent thinks it needs to discover more tools. - `allowDiscovery: optional boolean` - `autoDiscovery: optional object { hints, maxTools }` AutoDiscovery 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. 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. - `hints: optional array of string` - `maxTools: optional number` - `weight: optional number` Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights). Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest. - `info: optional object { assignments, createdBy, feedbackCount, 5 more }` AgentVariationInfo provides read-only summary information about a variation - `assignments: optional array of VariationAssignment` 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. - `id: optional string` - `agent: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `tool: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `toolSet: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `feedbackCount: optional number` Total number of objective feedbacks received for this variation - `model: optional object { 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 - `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"} - `score: optional number` Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta). Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative. - `subAgentCount: optional number` Number of sub-agents assigned to this variation - `toolCount: optional number` Number of individual tools assigned to this variation - `toolSetCount: optional number` Number of tool sets assigned to this variation - `metadata: object { 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 - `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"} - `status: object { state, message }` - `state: "STATE_UNSPECIFIED" or "STATE_PENDING" or "STATE_RUNNING" or 3 more` - `"STATE_UNSPECIFIED"` - `"STATE_PENDING"` - `"STATE_RUNNING"` - `"STATE_COMPLETED"` - `"STATE_FAILED"` - `"STATE_CANCELLED"` - `message: optional string` - `info: optional object { callableTools, createdBy, totalContextWindows, 4 more }` ObjectiveInfo provides read-only aggregated statistics about an objective's execution - `callableTools: optional array of CallableTool` List of callable tools assigned to the agent for this objective Includes tools, agents, and cadenya-provided tools from the agent's configuration - `agent: optional object { 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 - `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 object { 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 - `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 object { 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 - `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"} - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `totalContextWindows: optional number` Total number of context windows that this objective has generated - `totalEvents: optional number` Total number of events generated during this objective's execution - `totalInputTokens: optional number` Total input tokens consumed across all LLM completions across all context windows - `totalOutputTokens: optional number` Total output tokens generated across all LLM completions across all context windows - `totalToolCalls: optional number` Total number of tool calls made during execution - `lastFiveWindows: optional array of ObjectiveContextWindow` 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: object { completionTokens, objectiveId, previousWindowContinueInstructions, 2 more }` - `completionTokens: optional number` A calculated value for how many completion tokens (output tokens) have been used in this context window - `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 - `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. - `metadata: object { 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 - `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"} - `info: optional object { createdBy, objective }` - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `objective: optional object { 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 - `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"} ### Example ```cli cadenya objectives retrieve \ --api-key 'My API Key' \ --id id ``` #### Response ```json { "data": { "agent": { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "status": "AGENT_STATUS_UNSPECIFIED", "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED", "description": "description", "webhookEventsUrl": "webhookEventsUrl" }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "variationCount": 0 } }, "data": {}, "initialMessage": "initialMessage", "parentObjectiveId": "parentObjectiveId", "secrets": [ { "name": "name", "value": "value" } ], "systemPrompt": "systemPrompt", "variation": { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "compactionConfig": { "summarization": { "instructions": "instructions" }, "toolResultClearing": { "preserveRecentResults": 0 }, "triggerThreshold": 0 }, "constraints": { "maxSubObjectives": 0, "maxToolCalls": 0 }, "description": "description", "enableEpisodicMemory": true, "episodicMemoryTtl": 0, "modelConfig": { "modelId": "modelId", "temperature": 0 }, "prompt": "prompt", "toolSelection": { "assignedTools": { "allowDiscovery": true }, "autoDiscovery": { "hints": [ "string" ], "maxTools": 0 } }, "weight": 0 }, "info": { "assignments": [ { "id": "id", "agent": { "id": "id", "name": "name" }, "tool": { "id": "id", "name": "name" }, "toolSet": { "id": "id", "name": "name" } } ], "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "feedbackCount": 0, "model": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "score": 0, "subAgentCount": 0, "toolCount": 0, "toolSetCount": 0 } } }, "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "status": { "state": "STATE_UNSPECIFIED", "message": "message" }, "info": { "callableTools": [ { "agent": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "cadenyaProvidedTool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "tool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } ], "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "totalContextWindows": 0, "totalEvents": 0, "totalInputTokens": 0, "totalOutputTokens": 0, "totalToolCalls": 0 }, "lastFiveWindows": [ { "data": { "completionTokens": 0, "objectiveId": "objectiveId", "previousWindowContinueInstructions": "previousWindowContinueInstructions", "promptTokens": 0, "sequence": 0 }, "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "objective": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } } ] } ``` ## List objective events `$ cadenya objectives list-events` **get** `/v1/objectives/{objectiveId}/events` Lists all events for an objective ### Parameters - `--objective-id: string` Objective ID for filtering - `--cursor: optional string` Pagination cursor from previous response - `--include-info: optional boolean` When set to true you may use more of your alloted API rate-limit - `--limit: optional number` Maximum number of results to return - `--sort-order: optional string` Sort order for results (asc or desc by creation time) - `--window-id: optional string` Optional context window ID to filter events by ### Returns - `ListObjectiveEventsResponse: object { items, pagination }` - `items: optional array of object { data, metadata, contextWindowId, info }` - `data: object { assistantMessage, contextWindowCompacted, error, 9 more }` - `assistantMessage: optional object { content, toolCalls }` - `content: optional string` - `toolCalls: optional array of AssistantToolCall` - `arguments: optional string` - `functionName: optional string` - `tool: optional object { 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 object { 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 - `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 object { 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 - `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 object { 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 - `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 object { messagesCompacted, newContextWindow, strategies, summary }` - `messagesCompacted: optional number` Number of messages that were compacted - `newContextWindow: optional object { 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 - `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 - `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. - `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 object { message, type }` - `message: optional string` - `type: optional string` - `subObjectiveCreated: optional object { metadata }` - `metadata: optional object { 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 - `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 object { 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 object { toolCallId }` - `toolCallId: optional string` The ID of the objective tool call record that was approved via the ApproveToolCall RPC. - `toolCalled: optional object { toolCallId }` - `toolCallId: optional string` The ID of the objective tool call record that was executed. - `toolDenied: optional object { 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 object { message, toolCallId }` - `message: optional string` - `toolCallId: optional string` The ID of the objective tool call record that encountered an error during execution. - `toolResult: optional object { content, toolCallId }` - `content: optional string` - `toolCallId: optional string` - `type: optional string` - `userMessage: optional object { content }` - `content: optional string` - `metadata: object { 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 - `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 object { createdBy, objective }` - `createdBy: optional object { 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: object { 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: object { 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. - `"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 object { 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 - `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"} - `pagination: optional object { nextCursor, total }` - `nextCursor: optional string` - `total: optional number` ### Example ```cli cadenya objectives list-events \ --api-key 'My API Key' \ --objective-id objectiveId ``` #### Response ```json { "items": [ { "data": { "assistantMessage": { "content": "content", "toolCalls": [ { "arguments": "arguments", "functionName": "functionName", "tool": { "agent": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "cadenyaProvidedTool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "tool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } } ] }, "contextWindowCompacted": { "messagesCompacted": 0, "newContextWindow": { "completionTokens": 0, "objectiveId": "objectiveId", "previousWindowContinueInstructions": "previousWindowContinueInstructions", "promptTokens": 0, "sequence": 0 }, "strategies": [ "string" ], "summary": "summary" }, "error": { "message": "message", "type": "type" }, "subObjectiveCreated": { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } }, "toolApprovalRequested": { "toolCallId": "toolCallId" }, "toolApproved": { "toolCallId": "toolCallId" }, "toolCalled": { "toolCallId": "toolCallId" }, "toolDenied": { "memo": "memo", "toolCallId": "toolCallId" }, "toolError": { "message": "message", "toolCallId": "toolCallId" }, "toolResult": { "content": "content", "toolCallId": "toolCallId" }, "type": "type", "userMessage": { "content": "content" } }, "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "contextWindowId": "contextWindowId", "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "objective": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } } ], "pagination": { "nextCursor": "nextCursor", "total": 0 } } ``` ## Continue an objective `$ cadenya objectives continue` **post** `/v1/objectives/{objectiveId}/continue` Continues an objective that has completed ### Parameters - `--objective-id: string` The ID of the objective. If you have assigned an external ID to the objective, you can prefix the ID with "external_id:". For example, "external_id:1234567890". Otherwise, the ID assigned by Cadenya should be used. - `--enqueue: optional boolean` When set to true, the message will be enqueued for when the agent loop is available to process it. - `--message: optional string` The message to continue an objective that has completed (or you are enqueing) - `--secret: optional array of object { name, value }` Secrets that should be included with the message. Helpful for when you need to update secrets on the objective (IE: A secret expires and needs to be refreshed) ### Returns - `ObjectiveContinueResponse: object { data, metadata, contextWindowId, info }` - `data: object { assistantMessage, contextWindowCompacted, error, 9 more }` - `assistantMessage: optional object { content, toolCalls }` - `content: optional string` - `toolCalls: optional array of AssistantToolCall` - `arguments: optional string` - `functionName: optional string` - `tool: optional object { 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 object { 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 - `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 object { 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 - `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 object { 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 - `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 object { messagesCompacted, newContextWindow, strategies, summary }` - `messagesCompacted: optional number` Number of messages that were compacted - `newContextWindow: optional object { 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 - `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 - `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. - `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 object { message, type }` - `message: optional string` - `type: optional string` - `subObjectiveCreated: optional object { metadata }` - `metadata: optional object { 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 - `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 object { 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 object { toolCallId }` - `toolCallId: optional string` The ID of the objective tool call record that was approved via the ApproveToolCall RPC. - `toolCalled: optional object { toolCallId }` - `toolCallId: optional string` The ID of the objective tool call record that was executed. - `toolDenied: optional object { 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 object { message, toolCallId }` - `message: optional string` - `toolCallId: optional string` The ID of the objective tool call record that encountered an error during execution. - `toolResult: optional object { content, toolCallId }` - `content: optional string` - `toolCallId: optional string` - `type: optional string` - `userMessage: optional object { content }` - `content: optional string` - `metadata: object { 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 - `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 object { createdBy, objective }` - `createdBy: optional object { 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: object { 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: object { 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. - `"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 object { 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 - `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"} ### Example ```cli cadenya objectives continue \ --api-key 'My API Key' \ --objective-id objectiveId ``` #### Response ```json { "data": { "assistantMessage": { "content": "content", "toolCalls": [ { "arguments": "arguments", "functionName": "functionName", "tool": { "agent": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "cadenyaProvidedTool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "tool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } } ] }, "contextWindowCompacted": { "messagesCompacted": 0, "newContextWindow": { "completionTokens": 0, "objectiveId": "objectiveId", "previousWindowContinueInstructions": "previousWindowContinueInstructions", "promptTokens": 0, "sequence": 0 }, "strategies": [ "string" ], "summary": "summary" }, "error": { "message": "message", "type": "type" }, "subObjectiveCreated": { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } }, "toolApprovalRequested": { "toolCallId": "toolCallId" }, "toolApproved": { "toolCallId": "toolCallId" }, "toolCalled": { "toolCallId": "toolCallId" }, "toolDenied": { "memo": "memo", "toolCallId": "toolCallId" }, "toolError": { "message": "message", "toolCallId": "toolCallId" }, "toolResult": { "content": "content", "toolCallId": "toolCallId" }, "type": "type", "userMessage": { "content": "content" } }, "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "contextWindowId": "contextWindowId", "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "objective": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } } ``` ## Cancel an objective `$ cadenya objectives cancel` **post** `/v1/objectives/{objectiveId}/cancel` Cancels a running or pending objective. The objective's state will be set to STATE_CANCELLED. ### Parameters - `--objective-id: string` The ID of the objective. Supports "external_id:" prefix for external IDs. - `--reason: optional string` Optional reason for cancellation ### Returns - `objective: object { data, metadata, status, 2 more }` - `data: object { agent, data, initialMessage, 4 more }` - `agent: optional object { metadata, spec, info }` Agent resource - `metadata: object { 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 - `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"} - `spec: object { status, variationSelectionMode, description, webhookEventsUrl }` Agent specification (user-provided configuration) - `status: "AGENT_STATUS_UNSPECIFIED" or "AGENT_STATUS_DRAFT" or "AGENT_STATUS_PUBLISHED" or "AGENT_STATUS_ARCHIVED"` Status of the agent - `"AGENT_STATUS_UNSPECIFIED"` - `"AGENT_STATUS_DRAFT"` - `"AGENT_STATUS_PUBLISHED"` - `"AGENT_STATUS_ARCHIVED"` - `variationSelectionMode: "VARIATION_SELECTION_MODE_UNSPECIFIED" or "VARIATION_SELECTION_MODE_RANDOM" or "VARIATION_SELECTION_MODE_WEIGHTED"` Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified - `"VARIATION_SELECTION_MODE_UNSPECIFIED"` - `"VARIATION_SELECTION_MODE_RANDOM"` - `"VARIATION_SELECTION_MODE_WEIGHTED"` - `description: optional string` Description of the agent's purpose - `webhookEventsUrl: optional string` The URL that Cadenya will send events for any objective assigned to the agent. - `info: optional object { createdBy, variationCount }` AgentInfo contains simple information about an agent for display or quick reference - `createdBy: optional object { 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: object { 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: object { 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. - `"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") - `variationCount: optional number` - `data: optional unknown` 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. - `initialMessage: optional string` The initial message sent to the agent. This becomes the first user message in the LLM chat history. - `parentObjectiveId: optional string` A parent objective means the objective was spawned off using a separate agent to complete an objective - `secrets: optional array of ObjectiveDataSecret` Secrets that can be used in the headers for tool calls using the secret interpolation format. - `name: optional string` - `value: optional string` - `systemPrompt: optional string` system_prompt is read-only, derived from the selected variation's prompt - `variation: optional object { metadata, spec, info }` AgentVariation resource - `metadata: object { 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 - `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"} - `spec: object { compactionConfig, constraints, description, 6 more }` AgentVariationSpec defines the operational configuration for a variation - `compactionConfig: optional object { summarization, toolResultClearing, triggerThreshold }` CompactionConfig defines how context window compaction behaves for objectives using this variation. - `summarization: optional object { instructions }` SummarizationStrategy configures LLM-powered summarization of older conversation turns. - `instructions: optional string` Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." - `toolResultClearing: optional object { preserveRecentResults }` ToolResultClearingStrategy configures clearing of older tool result content. - `preserveRecentResults: optional number` Number of most recent tool call results to keep intact. Older tool results have their content replaced with "[result cleared]" while preserving the assistant tool call message (function name, arguments). Default: 2 - `triggerThreshold: optional number` Trigger threshold as a percentage of the model's context window (0.0 to 1.0). When input tokens reach this percentage of the model's limit, compaction triggers. Default: 0.75 (75%) - `constraints: optional object { maxSubObjectives, maxToolCalls }` Execution constraints - `maxSubObjectives: optional number` The maximum number of sub-objectives that can be created. 0 means no limit. - `maxToolCalls: optional number` The maximum number of tool calls that can be made. 0 means no limit. - `description: optional string` Human-readable description of what this variation does or when it should be used - `enableEpisodicMemory: optional boolean` 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. - `episodicMemoryTtl: optional number` 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. - `modelConfig: optional object { modelId, temperature }` ModelConfig defines the model configuration for a variation - `modelId: optional string` The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5") - `temperature: optional number` Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness - `prompt: optional string` The system prompt for this variation - `toolSelection: optional object { assignedTools, autoDiscovery }` Tool selection strategy - `assignedTools: optional object { allowDiscovery }` AssignedTools is used to indicate that the agent should only use the tools/tool sets that are explicitly assigned to it. Allow discovery is used when the agent thinks it needs to discover more tools. - `allowDiscovery: optional boolean` - `autoDiscovery: optional object { hints, maxTools }` AutoDiscovery 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. 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. - `hints: optional array of string` - `maxTools: optional number` - `weight: optional number` Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights). Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest. - `info: optional object { assignments, createdBy, feedbackCount, 5 more }` AgentVariationInfo provides read-only summary information about a variation - `assignments: optional array of VariationAssignment` 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. - `id: optional string` - `agent: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `tool: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `toolSet: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `feedbackCount: optional number` Total number of objective feedbacks received for this variation - `model: optional object { 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 - `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"} - `score: optional number` Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta). Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative. - `subAgentCount: optional number` Number of sub-agents assigned to this variation - `toolCount: optional number` Number of individual tools assigned to this variation - `toolSetCount: optional number` Number of tool sets assigned to this variation - `metadata: object { 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 - `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"} - `status: object { state, message }` - `state: "STATE_UNSPECIFIED" or "STATE_PENDING" or "STATE_RUNNING" or 3 more` - `"STATE_UNSPECIFIED"` - `"STATE_PENDING"` - `"STATE_RUNNING"` - `"STATE_COMPLETED"` - `"STATE_FAILED"` - `"STATE_CANCELLED"` - `message: optional string` - `info: optional object { callableTools, createdBy, totalContextWindows, 4 more }` ObjectiveInfo provides read-only aggregated statistics about an objective's execution - `callableTools: optional array of CallableTool` List of callable tools assigned to the agent for this objective Includes tools, agents, and cadenya-provided tools from the agent's configuration - `agent: optional object { 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 - `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 object { 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 - `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 object { 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 - `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"} - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `totalContextWindows: optional number` Total number of context windows that this objective has generated - `totalEvents: optional number` Total number of events generated during this objective's execution - `totalInputTokens: optional number` Total input tokens consumed across all LLM completions across all context windows - `totalOutputTokens: optional number` Total output tokens generated across all LLM completions across all context windows - `totalToolCalls: optional number` Total number of tool calls made during execution - `lastFiveWindows: optional array of ObjectiveContextWindow` 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: object { completionTokens, objectiveId, previousWindowContinueInstructions, 2 more }` - `completionTokens: optional number` A calculated value for how many completion tokens (output tokens) have been used in this context window - `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 - `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. - `metadata: object { 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 - `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"} - `info: optional object { createdBy, objective }` - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `objective: optional object { 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 - `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"} ### Example ```cli cadenya objectives cancel \ --api-key 'My API Key' \ --objective-id objectiveId ``` #### Response ```json { "data": { "agent": { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "status": "AGENT_STATUS_UNSPECIFIED", "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED", "description": "description", "webhookEventsUrl": "webhookEventsUrl" }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "variationCount": 0 } }, "data": {}, "initialMessage": "initialMessage", "parentObjectiveId": "parentObjectiveId", "secrets": [ { "name": "name", "value": "value" } ], "systemPrompt": "systemPrompt", "variation": { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "compactionConfig": { "summarization": { "instructions": "instructions" }, "toolResultClearing": { "preserveRecentResults": 0 }, "triggerThreshold": 0 }, "constraints": { "maxSubObjectives": 0, "maxToolCalls": 0 }, "description": "description", "enableEpisodicMemory": true, "episodicMemoryTtl": 0, "modelConfig": { "modelId": "modelId", "temperature": 0 }, "prompt": "prompt", "toolSelection": { "assignedTools": { "allowDiscovery": true }, "autoDiscovery": { "hints": [ "string" ], "maxTools": 0 } }, "weight": 0 }, "info": { "assignments": [ { "id": "id", "agent": { "id": "id", "name": "name" }, "tool": { "id": "id", "name": "name" }, "toolSet": { "id": "id", "name": "name" } } ], "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "feedbackCount": 0, "model": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "score": 0, "subAgentCount": 0, "toolCount": 0, "toolSetCount": 0 } } }, "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "status": { "state": "STATE_UNSPECIFIED", "message": "message" }, "info": { "callableTools": [ { "agent": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "cadenyaProvidedTool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "tool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } ], "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "totalContextWindows": 0, "totalEvents": 0, "totalInputTokens": 0, "totalOutputTokens": 0, "totalToolCalls": 0 }, "lastFiveWindows": [ { "data": { "completionTokens": 0, "objectiveId": "objectiveId", "previousWindowContinueInstructions": "previousWindowContinueInstructions", "promptTokens": 0, "sequence": 0 }, "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "objective": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } } ] } ``` ## Compact an objective `$ cadenya objectives compact` **post** `/v1/objectives/{objectiveId}/compact` Triggers compaction on a running objective. Optionally override the variation's compaction config. ### Parameters - `--objective-id: string` Objective ID (from path) - `--compaction-config: optional object { summarization, toolResultClearing, triggerThreshold }` CompactionConfig defines how context window compaction behaves for objectives using this variation. ### Returns - `ObjectiveCompactResponse: object { contextWindow }` Compact objective response - `contextWindow: optional object { completionTokens, objectiveId, previousWindowContinueInstructions, 2 more }` The new context window created by the compaction - `completionTokens: optional number` A calculated value for how many completion tokens (output tokens) have been used in this context window - `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 - `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. ### Example ```cli cadenya objectives compact \ --api-key 'My API Key' \ --objective-id objectiveId ``` #### Response ```json { "contextWindow": { "completionTokens": 0, "objectiveId": "objectiveId", "previousWindowContinueInstructions": "previousWindowContinueInstructions", "promptTokens": 0, "sequence": 0 } } ``` ## List objective context windows `$ cadenya objectives list-context-windows` **get** `/v1/objectives/{objectiveId}/context_windows` Read-only list of the last five windows of execution for this objective, ordered by most recent first ### Parameters - `--objective-id: string` The objective ID to return windows for - `--cursor: optional string` Pagination cursor from previous response - `--include-info: optional boolean` When set to true you may use more of your alloted API rate-limit - `--limit: optional number` Maximum number of results to return ### Returns - `ListObjectiveContextWindowsResponse: object { items, pagination }` ListObjectiveContextWindowsResponse is the response to a ListObjectiveContextWindowsRequest - `items: optional array of ObjectiveContextWindow` - `data: object { completionTokens, objectiveId, previousWindowContinueInstructions, 2 more }` - `completionTokens: optional number` A calculated value for how many completion tokens (output tokens) have been used in this context window - `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 - `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. - `metadata: object { 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 - `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"} - `info: optional object { createdBy, objective }` - `createdBy: optional object { 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: object { 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: object { 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. - `"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 object { 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 - `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"} - `pagination: optional object { nextCursor, total }` - `nextCursor: optional string` - `total: optional number` ### Example ```cli cadenya objectives list-context-windows \ --api-key 'My API Key' \ --objective-id objectiveId ``` #### Response ```json { "items": [ { "data": { "completionTokens": 0, "objectiveId": "objectiveId", "previousWindowContinueInstructions": "previousWindowContinueInstructions", "promptTokens": 0, "sequence": 0 }, "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "objective": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } } ], "pagination": { "nextCursor": "nextCursor", "total": 0 } } ``` ## Domain Types ### Assistant Message - `assistant_message: object { content, toolCalls }` - `content: optional string` - `toolCalls: optional array of AssistantToolCall` - `arguments: optional string` - `functionName: optional string` - `tool: optional object { 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 object { 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 - `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 object { 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 - `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 object { 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 - `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"} ### Assistant Tool Call - `assistant_tool_call: object { arguments, functionName, tool }` - `arguments: optional string` - `functionName: optional string` - `tool: optional object { 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 object { 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 - `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 object { 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 - `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 object { 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 - `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"} ### Callable Tool - `callable_tool: object { 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 object { 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 - `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 object { 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 - `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 object { 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 - `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"} ### Context Window Compacted - `context_window_compacted: object { messagesCompacted, newContextWindow, strategies, summary }` - `messagesCompacted: optional number` Number of messages that were compacted - `newContextWindow: optional object { 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 - `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 - `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. - `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. ### Objective - `objective: object { data, metadata, status, 2 more }` - `data: object { agent, data, initialMessage, 4 more }` - `agent: optional object { metadata, spec, info }` Agent resource - `metadata: object { 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 - `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"} - `spec: object { status, variationSelectionMode, description, webhookEventsUrl }` Agent specification (user-provided configuration) - `status: "AGENT_STATUS_UNSPECIFIED" or "AGENT_STATUS_DRAFT" or "AGENT_STATUS_PUBLISHED" or "AGENT_STATUS_ARCHIVED"` Status of the agent - `"AGENT_STATUS_UNSPECIFIED"` - `"AGENT_STATUS_DRAFT"` - `"AGENT_STATUS_PUBLISHED"` - `"AGENT_STATUS_ARCHIVED"` - `variationSelectionMode: "VARIATION_SELECTION_MODE_UNSPECIFIED" or "VARIATION_SELECTION_MODE_RANDOM" or "VARIATION_SELECTION_MODE_WEIGHTED"` Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified - `"VARIATION_SELECTION_MODE_UNSPECIFIED"` - `"VARIATION_SELECTION_MODE_RANDOM"` - `"VARIATION_SELECTION_MODE_WEIGHTED"` - `description: optional string` Description of the agent's purpose - `webhookEventsUrl: optional string` The URL that Cadenya will send events for any objective assigned to the agent. - `info: optional object { createdBy, variationCount }` AgentInfo contains simple information about an agent for display or quick reference - `createdBy: optional object { 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: object { 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: object { 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. - `"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") - `variationCount: optional number` - `data: optional unknown` 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. - `initialMessage: optional string` The initial message sent to the agent. This becomes the first user message in the LLM chat history. - `parentObjectiveId: optional string` A parent objective means the objective was spawned off using a separate agent to complete an objective - `secrets: optional array of ObjectiveDataSecret` Secrets that can be used in the headers for tool calls using the secret interpolation format. - `name: optional string` - `value: optional string` - `systemPrompt: optional string` system_prompt is read-only, derived from the selected variation's prompt - `variation: optional object { metadata, spec, info }` AgentVariation resource - `metadata: object { 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 - `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"} - `spec: object { compactionConfig, constraints, description, 6 more }` AgentVariationSpec defines the operational configuration for a variation - `compactionConfig: optional object { summarization, toolResultClearing, triggerThreshold }` CompactionConfig defines how context window compaction behaves for objectives using this variation. - `summarization: optional object { instructions }` SummarizationStrategy configures LLM-powered summarization of older conversation turns. - `instructions: optional string` Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." - `toolResultClearing: optional object { preserveRecentResults }` ToolResultClearingStrategy configures clearing of older tool result content. - `preserveRecentResults: optional number` Number of most recent tool call results to keep intact. Older tool results have their content replaced with "[result cleared]" while preserving the assistant tool call message (function name, arguments). Default: 2 - `triggerThreshold: optional number` Trigger threshold as a percentage of the model's context window (0.0 to 1.0). When input tokens reach this percentage of the model's limit, compaction triggers. Default: 0.75 (75%) - `constraints: optional object { maxSubObjectives, maxToolCalls }` Execution constraints - `maxSubObjectives: optional number` The maximum number of sub-objectives that can be created. 0 means no limit. - `maxToolCalls: optional number` The maximum number of tool calls that can be made. 0 means no limit. - `description: optional string` Human-readable description of what this variation does or when it should be used - `enableEpisodicMemory: optional boolean` 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. - `episodicMemoryTtl: optional number` 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. - `modelConfig: optional object { modelId, temperature }` ModelConfig defines the model configuration for a variation - `modelId: optional string` The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5") - `temperature: optional number` Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness - `prompt: optional string` The system prompt for this variation - `toolSelection: optional object { assignedTools, autoDiscovery }` Tool selection strategy - `assignedTools: optional object { allowDiscovery }` AssignedTools is used to indicate that the agent should only use the tools/tool sets that are explicitly assigned to it. Allow discovery is used when the agent thinks it needs to discover more tools. - `allowDiscovery: optional boolean` - `autoDiscovery: optional object { hints, maxTools }` AutoDiscovery 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. 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. - `hints: optional array of string` - `maxTools: optional number` - `weight: optional number` Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights). Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest. - `info: optional object { assignments, createdBy, feedbackCount, 5 more }` AgentVariationInfo provides read-only summary information about a variation - `assignments: optional array of VariationAssignment` 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. - `id: optional string` - `agent: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `tool: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `toolSet: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `feedbackCount: optional number` Total number of objective feedbacks received for this variation - `model: optional object { 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 - `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"} - `score: optional number` Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta). Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative. - `subAgentCount: optional number` Number of sub-agents assigned to this variation - `toolCount: optional number` Number of individual tools assigned to this variation - `toolSetCount: optional number` Number of tool sets assigned to this variation - `metadata: object { 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 - `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"} - `status: object { state, message }` - `state: "STATE_UNSPECIFIED" or "STATE_PENDING" or "STATE_RUNNING" or 3 more` - `"STATE_UNSPECIFIED"` - `"STATE_PENDING"` - `"STATE_RUNNING"` - `"STATE_COMPLETED"` - `"STATE_FAILED"` - `"STATE_CANCELLED"` - `message: optional string` - `info: optional object { callableTools, createdBy, totalContextWindows, 4 more }` ObjectiveInfo provides read-only aggregated statistics about an objective's execution - `callableTools: optional array of CallableTool` List of callable tools assigned to the agent for this objective Includes tools, agents, and cadenya-provided tools from the agent's configuration - `agent: optional object { 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 - `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 object { 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 - `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 object { 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 - `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"} - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `totalContextWindows: optional number` Total number of context windows that this objective has generated - `totalEvents: optional number` Total number of events generated during this objective's execution - `totalInputTokens: optional number` Total input tokens consumed across all LLM completions across all context windows - `totalOutputTokens: optional number` Total output tokens generated across all LLM completions across all context windows - `totalToolCalls: optional number` Total number of tool calls made during execution - `lastFiveWindows: optional array of ObjectiveContextWindow` 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: object { completionTokens, objectiveId, previousWindowContinueInstructions, 2 more }` - `completionTokens: optional number` A calculated value for how many completion tokens (output tokens) have been used in this context window - `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 - `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. - `metadata: object { 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 - `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"} - `info: optional object { createdBy, objective }` - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `objective: optional object { 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 - `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"} ### Objective Context Window - `objective_context_window: object { 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: object { completionTokens, objectiveId, previousWindowContinueInstructions, 2 more }` - `completionTokens: optional number` A calculated value for how many completion tokens (output tokens) have been used in this context window - `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 - `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. - `metadata: object { 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 - `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"} - `info: optional object { createdBy, objective }` - `createdBy: optional object { 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: object { 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: object { 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. - `"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 object { 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 - `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"} ### Objective Context Window Data - `objective_context_window_data: object { completionTokens, objectiveId, previousWindowContinueInstructions, 2 more }` - `completionTokens: optional number` A calculated value for how many completion tokens (output tokens) have been used in this context window - `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 - `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. ### Objective Data - `objective_data: object { agent, data, initialMessage, 4 more }` - `agent: optional object { metadata, spec, info }` Agent resource - `metadata: object { 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 - `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"} - `spec: object { status, variationSelectionMode, description, webhookEventsUrl }` Agent specification (user-provided configuration) - `status: "AGENT_STATUS_UNSPECIFIED" or "AGENT_STATUS_DRAFT" or "AGENT_STATUS_PUBLISHED" or "AGENT_STATUS_ARCHIVED"` Status of the agent - `"AGENT_STATUS_UNSPECIFIED"` - `"AGENT_STATUS_DRAFT"` - `"AGENT_STATUS_PUBLISHED"` - `"AGENT_STATUS_ARCHIVED"` - `variationSelectionMode: "VARIATION_SELECTION_MODE_UNSPECIFIED" or "VARIATION_SELECTION_MODE_RANDOM" or "VARIATION_SELECTION_MODE_WEIGHTED"` Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified - `"VARIATION_SELECTION_MODE_UNSPECIFIED"` - `"VARIATION_SELECTION_MODE_RANDOM"` - `"VARIATION_SELECTION_MODE_WEIGHTED"` - `description: optional string` Description of the agent's purpose - `webhookEventsUrl: optional string` The URL that Cadenya will send events for any objective assigned to the agent. - `info: optional object { createdBy, variationCount }` AgentInfo contains simple information about an agent for display or quick reference - `createdBy: optional object { 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: object { 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: object { 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. - `"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") - `variationCount: optional number` - `data: optional unknown` 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. - `initialMessage: optional string` The initial message sent to the agent. This becomes the first user message in the LLM chat history. - `parentObjectiveId: optional string` A parent objective means the objective was spawned off using a separate agent to complete an objective - `secrets: optional array of ObjectiveDataSecret` Secrets that can be used in the headers for tool calls using the secret interpolation format. - `name: optional string` - `value: optional string` - `systemPrompt: optional string` system_prompt is read-only, derived from the selected variation's prompt - `variation: optional object { metadata, spec, info }` AgentVariation resource - `metadata: object { 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 - `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"} - `spec: object { compactionConfig, constraints, description, 6 more }` AgentVariationSpec defines the operational configuration for a variation - `compactionConfig: optional object { summarization, toolResultClearing, triggerThreshold }` CompactionConfig defines how context window compaction behaves for objectives using this variation. - `summarization: optional object { instructions }` SummarizationStrategy configures LLM-powered summarization of older conversation turns. - `instructions: optional string` Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions." - `toolResultClearing: optional object { preserveRecentResults }` ToolResultClearingStrategy configures clearing of older tool result content. - `preserveRecentResults: optional number` Number of most recent tool call results to keep intact. Older tool results have their content replaced with "[result cleared]" while preserving the assistant tool call message (function name, arguments). Default: 2 - `triggerThreshold: optional number` Trigger threshold as a percentage of the model's context window (0.0 to 1.0). When input tokens reach this percentage of the model's limit, compaction triggers. Default: 0.75 (75%) - `constraints: optional object { maxSubObjectives, maxToolCalls }` Execution constraints - `maxSubObjectives: optional number` The maximum number of sub-objectives that can be created. 0 means no limit. - `maxToolCalls: optional number` The maximum number of tool calls that can be made. 0 means no limit. - `description: optional string` Human-readable description of what this variation does or when it should be used - `enableEpisodicMemory: optional boolean` 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. - `episodicMemoryTtl: optional number` 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. - `modelConfig: optional object { modelId, temperature }` ModelConfig defines the model configuration for a variation - `modelId: optional string` The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5") - `temperature: optional number` Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness - `prompt: optional string` The system prompt for this variation - `toolSelection: optional object { assignedTools, autoDiscovery }` Tool selection strategy - `assignedTools: optional object { allowDiscovery }` AssignedTools is used to indicate that the agent should only use the tools/tool sets that are explicitly assigned to it. Allow discovery is used when the agent thinks it needs to discover more tools. - `allowDiscovery: optional boolean` - `autoDiscovery: optional object { hints, maxTools }` AutoDiscovery 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. 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. - `hints: optional array of string` - `maxTools: optional number` - `weight: optional number` Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights). Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest. - `info: optional object { assignments, createdBy, feedbackCount, 5 more }` AgentVariationInfo provides read-only summary information about a variation - `assignments: optional array of VariationAssignment` 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. - `id: optional string` - `agent: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `tool: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `toolSet: optional object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `feedbackCount: optional number` Total number of objective feedbacks received for this variation - `model: optional object { 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 - `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"} - `score: optional number` Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta). Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative. - `subAgentCount: optional number` Number of sub-agents assigned to this variation - `toolCount: optional number` Number of individual tools assigned to this variation - `toolSetCount: optional number` Number of tool sets assigned to this variation ### Objective Data Secret - `objective_data_secret: object { name, value }` - `name: optional string` - `value: optional string` ### Objective Error - `objective_error: object { message, type }` - `message: optional string` - `type: optional string` ### Objective Event Data - `objective_event_data: object { assistantMessage, contextWindowCompacted, error, 9 more }` - `assistantMessage: optional object { content, toolCalls }` - `content: optional string` - `toolCalls: optional array of AssistantToolCall` - `arguments: optional string` - `functionName: optional string` - `tool: optional object { 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 object { 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 - `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 object { 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 - `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 object { 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 - `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 object { messagesCompacted, newContextWindow, strategies, summary }` - `messagesCompacted: optional number` Number of messages that were compacted - `newContextWindow: optional object { 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 - `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 - `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. - `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 object { message, type }` - `message: optional string` - `type: optional string` - `subObjectiveCreated: optional object { metadata }` - `metadata: optional object { 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 - `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 object { 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 object { toolCallId }` - `toolCallId: optional string` The ID of the objective tool call record that was approved via the ApproveToolCall RPC. - `toolCalled: optional object { toolCallId }` - `toolCallId: optional string` The ID of the objective tool call record that was executed. - `toolDenied: optional object { 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 object { message, toolCallId }` - `message: optional string` - `toolCallId: optional string` The ID of the objective tool call record that encountered an error during execution. - `toolResult: optional object { content, toolCallId }` - `content: optional string` - `toolCallId: optional string` - `type: optional string` - `userMessage: optional object { content }` - `content: optional string` ### Objective Event Info - `objective_event_info: object { createdBy, objective }` - `createdBy: optional object { 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: object { 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: object { 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. - `"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 object { 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 - `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"} ### Objective Event Webhook Data - `objective_event_webhook_data: 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: object { 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 - `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: object { 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 - `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: object { 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 - `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: object { assistantMessage, contextWindowCompacted, error, 9 more }` - `assistantMessage: optional object { content, toolCalls }` - `content: optional string` - `toolCalls: optional array of AssistantToolCall` - `arguments: optional string` - `functionName: optional string` - `tool: optional object { 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 object { 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 - `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 object { 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 - `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 object { 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 - `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 object { messagesCompacted, newContextWindow, strategies, summary }` - `messagesCompacted: optional number` Number of messages that were compacted - `newContextWindow: optional object { 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 - `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 - `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. - `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 object { message, type }` - `message: optional string` - `type: optional string` - `subObjectiveCreated: optional object { metadata }` - `metadata: optional object { 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 - `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 object { 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 object { toolCallId }` - `toolCallId: optional string` The ID of the objective tool call record that was approved via the ApproveToolCall RPC. - `toolCalled: optional object { toolCallId }` - `toolCallId: optional string` The ID of the objective tool call record that was executed. - `toolDenied: optional object { 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 object { message, toolCallId }` - `message: optional string` - `toolCallId: optional string` The ID of the objective tool call record that encountered an error during execution. - `toolResult: optional object { content, toolCallId }` - `content: optional string` - `toolCallId: optional string` - `type: optional string` - `userMessage: optional object { content }` - `content: optional string` - `metadata: object { 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 - `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 object { createdBy, objective }` - `createdBy: optional object { 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: object { 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: object { 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. - `"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 object { 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 - `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) ### Objective Info - `objective_info: object { callableTools, createdBy, totalContextWindows, 4 more }` ObjectiveInfo provides read-only aggregated statistics about an objective's execution - `callableTools: optional array of CallableTool` List of callable tools assigned to the agent for this objective Includes tools, agents, and cadenya-provided tools from the agent's configuration - `agent: optional object { 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 - `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 object { 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 - `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 object { 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 - `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"} - `createdBy: optional object { 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: object { 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: object { 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. - `"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") - `totalContextWindows: optional number` Total number of context windows that this objective has generated - `totalEvents: optional number` Total number of events generated during this objective's execution - `totalInputTokens: optional number` Total input tokens consumed across all LLM completions across all context windows - `totalOutputTokens: optional number` Total output tokens generated across all LLM completions across all context windows - `totalToolCalls: optional number` Total number of tool calls made during execution ### Objective Status - `objective_status: object { state, message }` - `state: "STATE_UNSPECIFIED" or "STATE_PENDING" or "STATE_RUNNING" or 3 more` - `"STATE_UNSPECIFIED"` - `"STATE_PENDING"` - `"STATE_RUNNING"` - `"STATE_COMPLETED"` - `"STATE_FAILED"` - `"STATE_CANCELLED"` - `message: optional string` ### Sub Objective Created - `sub_objective_created: object { metadata }` - `metadata: optional object { 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 - `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"} ### Tool Approval Requested - `tool_approval_requested: object { 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. ### Tool Approved - `tool_approved: object { toolCallId }` - `toolCallId: optional string` The ID of the objective tool call record that was approved via the ApproveToolCall RPC. ### Tool Called - `tool_called: object { toolCallId }` - `toolCallId: optional string` The ID of the objective tool call record that was executed. ### Tool Denied - `tool_denied: object { 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. ### Tool Error - `tool_error: object { message, toolCallId }` - `message: optional string` - `toolCallId: optional string` The ID of the objective tool call record that encountered an error during execution. ### Tool Result - `tool_result: object { content, toolCallId }` - `content: optional string` - `toolCallId: optional string` ### User Message - `user_message: object { content }` - `content: optional string` # Tools ## List objective tools `$ cadenya objectives:tools list` **get** `/v1/objectives/{objectiveId}/tools` Lists all tools that were assigned to an objective ### Parameters - `--objective-id: string` The ID of the objective. Supports "external_id:" prefix for external IDs. - `--cursor: optional string` Pagination cursor from previous response - `--limit: optional number` Maximum number of results to return ### Returns - `ListObjectiveToolsResponse: object { items, pagination }` - `items: optional array of ObjectiveTool` - `metadata: object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `snapshot: optional object { metadata, spec, info }` 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. - `metadata: object { 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 - `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"} - `spec: object { config, description, parameters, 2 more }` - `config: object { http, mcp }` 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: optional object { requestMethod, headers, path, 4 more }` - `requestMethod: "GET" or "POST" or "PUT" or 2 more` - `"GET"` - `"POST"` - `"PUT"` - `"PATCH"` - `"DELETE"` - `headers: optional map[string]` - `path: optional string` - `query: optional string` - `requestBodyContentType: optional string` - `requestBodyTemplate: optional string` These are only used when the request method is a POST, PUT, or PATCH - `toolName: optional 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: optional object { toolDescription, toolName, toolTitle }` - `toolDescription: optional string` - `toolName: optional string` - `toolTitle: optional string` - `description: string` - `parameters: map[unknown]` - `status: "TOOL_STATUS_UNSPECIFIED" or "TOOL_STATUS_AVAILABLE" or "TOOL_STATUS_FILTERED" or "TOOL_STATUS_ARCHIVED"` - `"TOOL_STATUS_UNSPECIFIED"` - `"TOOL_STATUS_AVAILABLE"` - `"TOOL_STATUS_FILTERED"` - `"TOOL_STATUS_ARCHIVED"` - `requiresApproval: optional boolean` - `info: optional object { createdBy, toolSet }` - `createdBy: optional object { 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: object { 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: object { 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. - `"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") - `toolSet: optional object { 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 - `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"} - `pagination: optional object { nextCursor, total }` - `nextCursor: optional string` - `total: optional number` ### Example ```cli cadenya objectives:tools list \ --api-key 'My API Key' \ --objective-id objectiveId ``` #### Response ```json { "items": [ { "metadata": { "id": "id", "name": "name" }, "snapshot": { "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "config": { "http": { "requestMethod": "GET", "headers": { "foo": "string" }, "path": "path", "query": "query", "requestBodyContentType": "requestBodyContentType", "requestBodyTemplate": "requestBodyTemplate", "toolName": "toolName" }, "mcp": { "toolDescription": "toolDescription", "toolName": "toolName", "toolTitle": "toolTitle" } }, "description": "description", "parameters": { "foo": "bar" }, "status": "TOOL_STATUS_UNSPECIFIED", "requiresApproval": true }, "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "toolSet": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } } } ], "pagination": { "nextCursor": "nextCursor", "total": 0 } } ``` ## Domain Types ### Objective Tool - `objective_tool: object { metadata, snapshot }` ObjectiveTool represents a tool that was assigned to an objective. - `metadata: object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `snapshot: optional object { metadata, spec, info }` 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. - `metadata: object { 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 - `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"} - `spec: object { config, description, parameters, 2 more }` - `config: object { http, mcp }` 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: optional object { requestMethod, headers, path, 4 more }` - `requestMethod: "GET" or "POST" or "PUT" or 2 more` - `"GET"` - `"POST"` - `"PUT"` - `"PATCH"` - `"DELETE"` - `headers: optional map[string]` - `path: optional string` - `query: optional string` - `requestBodyContentType: optional string` - `requestBodyTemplate: optional string` These are only used when the request method is a POST, PUT, or PATCH - `toolName: optional 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: optional object { toolDescription, toolName, toolTitle }` - `toolDescription: optional string` - `toolName: optional string` - `toolTitle: optional string` - `description: string` - `parameters: map[unknown]` - `status: "TOOL_STATUS_UNSPECIFIED" or "TOOL_STATUS_AVAILABLE" or "TOOL_STATUS_FILTERED" or "TOOL_STATUS_ARCHIVED"` - `"TOOL_STATUS_UNSPECIFIED"` - `"TOOL_STATUS_AVAILABLE"` - `"TOOL_STATUS_FILTERED"` - `"TOOL_STATUS_ARCHIVED"` - `requiresApproval: optional boolean` - `info: optional object { createdBy, toolSet }` - `createdBy: optional object { 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: object { 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: object { 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. - `"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") - `toolSet: optional object { 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 - `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 Calls ## List objective tool calls `$ cadenya objectives:tool-calls list` **get** `/v1/objectives/{objectiveId}/tool_calls` Lists all tool calls for an objective ### Parameters - `--objective-id: string` The objective ID to return tool calls for - `--cursor: optional string` Pagination cursor from previous response - `--include-info: optional boolean` When set to true you may use more of your alloted API rate-limit - `--limit: optional number` Maximum number of results to return - `--status: optional "TOOL_CALL_STATUS_UNSPECIFIED" or "TOOL_CALL_STATUS_AUTO_APPROVED" or "TOOL_CALL_STATUS_WAITING_FOR_APPROVAL" or 2 more` Filter by tool call status ### Returns - `ListObjectiveToolCallsResponse: object { items, pagination }` - `items: optional array of ObjectiveToolCall` - `data: object { callable, arguments, memo, 2 more }` - `callable: object { 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 object { 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 - `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 object { 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 - `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 object { 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 - `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"} - `arguments: optional map[unknown]` The arguments passed to the tool - `memo: optional string` A memo supplied by the reviewer when denying the tool call - `result: optional string` The result content returned by the tool after execution - `statusChangedBy: optional object { 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: object { 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: object { 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. - `"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") - `metadata: object { 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 - `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"} - `status: "TOOL_CALL_STATUS_UNSPECIFIED" or "TOOL_CALL_STATUS_AUTO_APPROVED" or "TOOL_CALL_STATUS_WAITING_FOR_APPROVAL" or 2 more` Current status of the tool call - `"TOOL_CALL_STATUS_UNSPECIFIED"` - `"TOOL_CALL_STATUS_AUTO_APPROVED"` - `"TOOL_CALL_STATUS_WAITING_FOR_APPROVAL"` - `"TOOL_CALL_STATUS_APPROVED"` - `"TOOL_CALL_STATUS_DENIED"` - `executionStatus: optional "TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED" or "TOOL_CALL_EXECUTION_STATUS_PENDING" or "TOOL_CALL_EXECUTION_STATUS_RUNNING" or 2 more` - `"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: optional object { createdBy, objective }` - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `objective: optional object { 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 - `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"} - `pagination: optional object { nextCursor, total }` - `nextCursor: optional string` - `total: optional number` ### Example ```cli cadenya objectives:tool-calls list \ --api-key 'My API Key' \ --objective-id objectiveId ``` #### Response ```json { "items": [ { "data": { "callable": { "agent": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "cadenyaProvidedTool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "tool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } }, "arguments": { "foo": "bar" }, "memo": "memo", "result": "result", "statusChangedBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } } }, "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "status": "TOOL_CALL_STATUS_UNSPECIFIED", "executionStatus": "TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED", "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "objective": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } } ], "pagination": { "nextCursor": "nextCursor", "total": 0 } } ``` ## Approve a tool call `$ cadenya objectives:tool-calls approve` **put** `/v1/objectives/{objectiveId}/tool_calls/{toolCallId}/approve` When an agent attempts to use a tool that requires approval, use this endpoint to mark it as approved. ### Parameters - `--objective-id: string` The ID of the objective. Supports "external_id:" prefix for external IDs. - `--tool-call-id: string` The ID of the tool call to approve ### Returns - `objective_tool_call: object { 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: object { callable, arguments, memo, 2 more }` - `callable: object { 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 object { 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 - `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 object { 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 - `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 object { 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 - `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"} - `arguments: optional map[unknown]` The arguments passed to the tool - `memo: optional string` A memo supplied by the reviewer when denying the tool call - `result: optional string` The result content returned by the tool after execution - `statusChangedBy: optional object { 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: object { 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: object { 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. - `"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") - `metadata: object { 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 - `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"} - `status: "TOOL_CALL_STATUS_UNSPECIFIED" or "TOOL_CALL_STATUS_AUTO_APPROVED" or "TOOL_CALL_STATUS_WAITING_FOR_APPROVAL" or 2 more` Current status of the tool call - `"TOOL_CALL_STATUS_UNSPECIFIED"` - `"TOOL_CALL_STATUS_AUTO_APPROVED"` - `"TOOL_CALL_STATUS_WAITING_FOR_APPROVAL"` - `"TOOL_CALL_STATUS_APPROVED"` - `"TOOL_CALL_STATUS_DENIED"` - `executionStatus: optional "TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED" or "TOOL_CALL_EXECUTION_STATUS_PENDING" or "TOOL_CALL_EXECUTION_STATUS_RUNNING" or 2 more` - `"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: optional object { createdBy, objective }` - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `objective: optional object { 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 - `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"} ### Example ```cli cadenya objectives:tool-calls approve \ --api-key 'My API Key' \ --objective-id objectiveId \ --tool-call-id toolCallId ``` #### Response ```json { "data": { "callable": { "agent": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "cadenyaProvidedTool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "tool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } }, "arguments": { "foo": "bar" }, "memo": "memo", "result": "result", "statusChangedBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } } }, "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "status": "TOOL_CALL_STATUS_UNSPECIFIED", "executionStatus": "TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED", "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "objective": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } } ``` ## Deny a tool call `$ cadenya objectives:tool-calls deny` **put** `/v1/objectives/{objectiveId}/tool_calls/{toolCallId}/deny` When an agent attempts to use a tool that requires approval, use this endpoint to mark it as denied. Use a memo to steer the LLM to a different decision or usage of the tool. ### Parameters - `--objective-id: string` The ID of the objective. Supports "external_id:" prefix for external IDs. - `--tool-call-id: string` The ID of the tool call to deny - `--memo: optional string` A memo to associate to the tool call denial. Use a memo to steer the LLM to a different decision or usage of the tool. ### Returns - `objective_tool_call: object { 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: object { callable, arguments, memo, 2 more }` - `callable: object { 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 object { 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 - `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 object { 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 - `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 object { 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 - `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"} - `arguments: optional map[unknown]` The arguments passed to the tool - `memo: optional string` A memo supplied by the reviewer when denying the tool call - `result: optional string` The result content returned by the tool after execution - `statusChangedBy: optional object { 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: object { 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: object { 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. - `"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") - `metadata: object { 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 - `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"} - `status: "TOOL_CALL_STATUS_UNSPECIFIED" or "TOOL_CALL_STATUS_AUTO_APPROVED" or "TOOL_CALL_STATUS_WAITING_FOR_APPROVAL" or 2 more` Current status of the tool call - `"TOOL_CALL_STATUS_UNSPECIFIED"` - `"TOOL_CALL_STATUS_AUTO_APPROVED"` - `"TOOL_CALL_STATUS_WAITING_FOR_APPROVAL"` - `"TOOL_CALL_STATUS_APPROVED"` - `"TOOL_CALL_STATUS_DENIED"` - `executionStatus: optional "TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED" or "TOOL_CALL_EXECUTION_STATUS_PENDING" or "TOOL_CALL_EXECUTION_STATUS_RUNNING" or 2 more` - `"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: optional object { createdBy, objective }` - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `objective: optional object { 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 - `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"} ### Example ```cli cadenya objectives:tool-calls deny \ --api-key 'My API Key' \ --objective-id objectiveId \ --tool-call-id toolCallId ``` #### Response ```json { "data": { "callable": { "agent": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "cadenyaProvidedTool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "tool": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "name": "name", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } }, "arguments": { "foo": "bar" }, "memo": "memo", "result": "result", "statusChangedBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } } }, "metadata": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } }, "status": "TOOL_CALL_STATUS_UNSPECIFIED", "executionStatus": "TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED", "info": { "createdBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } }, "objective": { "id": "id", "accountId": "accountId", "createdAt": "2019-12-27T18:11:19.117Z", "profileId": "profileId", "workspaceId": "workspaceId", "externalId": "externalId", "labels": { "foo": "string" } } } } ``` ## Domain Types ### Objective Tool Call - `objective_tool_call: object { 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: object { callable, arguments, memo, 2 more }` - `callable: object { 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 object { 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 - `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 object { 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 - `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 object { 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 - `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"} - `arguments: optional map[unknown]` The arguments passed to the tool - `memo: optional string` A memo supplied by the reviewer when denying the tool call - `result: optional string` The result content returned by the tool after execution - `statusChangedBy: optional object { 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: object { 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: object { 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. - `"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") - `metadata: object { 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 - `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"} - `status: "TOOL_CALL_STATUS_UNSPECIFIED" or "TOOL_CALL_STATUS_AUTO_APPROVED" or "TOOL_CALL_STATUS_WAITING_FOR_APPROVAL" or 2 more` Current status of the tool call - `"TOOL_CALL_STATUS_UNSPECIFIED"` - `"TOOL_CALL_STATUS_AUTO_APPROVED"` - `"TOOL_CALL_STATUS_WAITING_FOR_APPROVAL"` - `"TOOL_CALL_STATUS_APPROVED"` - `"TOOL_CALL_STATUS_DENIED"` - `executionStatus: optional "TOOL_CALL_EXECUTION_STATUS_UNSPECIFIED" or "TOOL_CALL_EXECUTION_STATUS_PENDING" or "TOOL_CALL_EXECUTION_STATUS_RUNNING" or 2 more` - `"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: optional object { createdBy, objective }` - `createdBy: optional object { 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: object { id, accountId, name, 3 more }` AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace. - `spec: object { type, email, name }` ProfileSpec contains the profile-specific fields - `objective: optional object { 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 - `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"} ### Objective Tool Call Data - `objective_tool_call_data: object { callable, arguments, memo, 2 more }` - `callable: object { 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 object { 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 - `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 object { 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 - `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 object { 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 - `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"} - `arguments: optional map[unknown]` The arguments passed to the tool - `memo: optional string` A memo supplied by the reviewer when denying the tool call - `result: optional string` The result content returned by the tool after execution - `statusChangedBy: optional object { 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: object { 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: object { 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. - `"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 Tool Call Info - `objective_tool_call_info: object { createdBy, objective }` - `createdBy: optional object { 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: object { 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: object { 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. - `"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 object { 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 - `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"} # Tasks ## List objective tasks `$ cadenya objectives:tasks list` **get** `/v1/objectives/{objectiveId}/tasks` Lists all tasks for an objective ### Parameters - `--objective-id: string` The ID of the objective. Supports "external_id:" prefix for external IDs. - `--cursor: optional string` Pagination cursor from previous response - `--limit: optional number` Maximum number of results to return - `--sort-order: optional string` Sort order for results ### Returns - `ListObjectiveTasksResponse: object { items, pagination }` - `items: optional array of ObjectiveTask` - `data: object { completed, number, task, completedAt }` - `completed: boolean` Whether the task has been completed - `number: number` The sequential number of this task within the objective (auto-assigned, 1-based) - `task: string` Description of the task to be completed - `completedAt: optional string` Timestamp when the task was marked as completed - `metadata: object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `pagination: optional object { nextCursor, total }` - `nextCursor: optional string` - `total: optional number` ### Example ```cli cadenya objectives:tasks list \ --api-key 'My API Key' \ --objective-id objectiveId ``` #### Response ```json { "items": [ { "data": { "completed": true, "number": 0, "task": "task", "completedAt": "2019-12-27T18:11:19.117Z" }, "metadata": { "id": "id", "name": "name" } } ], "pagination": { "nextCursor": "nextCursor", "total": 0 } } ``` ## Get an objective task by ID `$ cadenya objectives:tasks retrieve` **get** `/v1/objectives/{objectiveId}/tasks/{id}` Retrieves a task by ID from an objective ### Parameters - `--objective-id: string` The ID of the objective. Supports "external_id:" prefix for external IDs. - `--id: string` Task ID ### Returns - `objective_task: object { data, metadata }` ObjectiveTask represents a task within an objective, typically created and managed by an AI agent to track progress toward completing the objective. - `data: object { completed, number, task, completedAt }` - `completed: boolean` Whether the task has been completed - `number: number` The sequential number of this task within the objective (auto-assigned, 1-based) - `task: string` Description of the task to be completed - `completedAt: optional string` Timestamp when the task was marked as completed - `metadata: object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). ### Example ```cli cadenya objectives:tasks retrieve \ --api-key 'My API Key' \ --objective-id objectiveId \ --id id ``` #### Response ```json { "data": { "completed": true, "number": 0, "task": "task", "completedAt": "2019-12-27T18:11:19.117Z" }, "metadata": { "id": "id", "name": "name" } } ``` ## Domain Types ### Objective Task - `objective_task: object { data, metadata }` ObjectiveTask represents a task within an objective, typically created and managed by an AI agent to track progress toward completing the objective. - `data: object { completed, number, task, completedAt }` - `completed: boolean` Whether the task has been completed - `number: number` The sequential number of this task within the objective (auto-assigned, 1-based) - `task: string` Description of the task to be completed - `completedAt: optional string` Timestamp when the task was marked as completed - `metadata: object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). ### Objective Task Data - `objective_task_data: object { completed, number, task, completedAt }` - `completed: boolean` Whether the task has been completed - `number: number` The sequential number of this task within the objective (auto-assigned, 1-based) - `task: string` Description of the task to be completed - `completedAt: optional string` Timestamp when the task was marked as completed # Feedback ## Submit feedback for an objective `$ cadenya objectives:feedback create` **post** `/v1/objectives/{objectiveId}/feedback` Submits feedback for an objective's execution. Feedback scores are used by the agent variation scoring system to evaluate and rank variation performance. ### Parameters - `--objective-id: string` The ID of the objective. Supports "external_id:" prefix for external IDs. - `--data: object { attributes, comment, score }` ### Returns - `objective_feedback: object { 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. - `data: object { attributes, comment, score }` - `attributes: optional map[string]` Arbitrary key-value pairs to identify the source of the feedback. Since the submitting profile is typically an API key, use this to pass through application-specific identifiers (e.g., {"user_id": "usr_123", "session_id": "abc"}). - `comment: optional string` Optional human-readable comment explaining the feedback - `score: optional number` A score between -1.0 and 1.0 representing the quality of the objective's execution. -1.0 is the worst possible score, 0.0 is neutral, and 1.0 is the best. - `metadata: object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `info: optional object { submittedBy }` - `submittedBy: optional object { 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: object { 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: object { 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. - `"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") ### Example ```cli cadenya objectives:feedback create \ --api-key 'My API Key' \ --objective-id objectiveId \ --data '{}' ``` #### Response ```json { "data": { "attributes": { "foo": "string" }, "comment": "comment", "score": 0 }, "metadata": { "id": "id", "name": "name" }, "info": { "submittedBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } } } } ``` ## List feedback for an objective `$ cadenya objectives:feedback list` **get** `/v1/objectives/{objectiveId}/feedback` Lists all feedback submitted for an objective ### Parameters - `--objective-id: string` The ID of the objective. Supports "external_id:" prefix for external IDs. - `--cursor: optional string` Pagination cursor from previous response - `--limit: optional number` Maximum number of results to return ### Returns - `ListObjectiveFeedbackResponse: object { items, pagination }` Response for listing feedback - `items: optional array of ObjectiveFeedback` - `data: object { attributes, comment, score }` - `attributes: optional map[string]` Arbitrary key-value pairs to identify the source of the feedback. Since the submitting profile is typically an API key, use this to pass through application-specific identifiers (e.g., {"user_id": "usr_123", "session_id": "abc"}). - `comment: optional string` Optional human-readable comment explaining the feedback - `score: optional number` A score between -1.0 and 1.0 representing the quality of the objective's execution. -1.0 is the worst possible score, 0.0 is neutral, and 1.0 is the best. - `metadata: object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `info: optional object { submittedBy }` - `submittedBy: optional object { 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: object { 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: object { 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. - `"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") - `pagination: optional object { nextCursor, total }` - `nextCursor: optional string` - `total: optional number` ### Example ```cli cadenya objectives:feedback list \ --api-key 'My API Key' \ --objective-id objectiveId ``` #### Response ```json { "items": [ { "data": { "attributes": { "foo": "string" }, "comment": "comment", "score": 0 }, "metadata": { "id": "id", "name": "name" }, "info": { "submittedBy": { "metadata": { "id": "id", "accountId": "accountId", "name": "name", "profileId": "profileId", "externalId": "externalId", "labels": { "foo": "string" } }, "spec": { "type": "PROFILE_TYPE_USER", "email": "email", "name": "name" } } } } ], "pagination": { "nextCursor": "nextCursor", "total": 0 } } ``` ## Domain Types ### Objective Feedback - `objective_feedback: object { 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. - `data: object { attributes, comment, score }` - `attributes: optional map[string]` Arbitrary key-value pairs to identify the source of the feedback. Since the submitting profile is typically an API key, use this to pass through application-specific identifiers (e.g., {"user_id": "usr_123", "session_id": "abc"}). - `comment: optional string` Optional human-readable comment explaining the feedback - `score: optional number` A score between -1.0 and 1.0 representing the quality of the objective's execution. -1.0 is the worst possible score, 0.0 is neutral, and 1.0 is the best. - `metadata: object { id, name }` 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. - `id: optional string` - `name: optional string` Human-readable name of the referenced resource, populated by the server on reads for convenience. Absent on references to resources that do not have a name (e.g., objective tasks). - `info: optional object { submittedBy }` - `submittedBy: optional object { 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: object { 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: object { 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. - `"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 Feedback Data - `objective_feedback_data: object { attributes, comment, score }` - `attributes: optional map[string]` Arbitrary key-value pairs to identify the source of the feedback. Since the submitting profile is typically an API key, use this to pass through application-specific identifiers (e.g., {"user_id": "usr_123", "session_id": "abc"}). - `comment: optional string` Optional human-readable comment explaining the feedback - `score: optional number` A score between -1.0 and 1.0 representing the quality of the objective's execution. -1.0 is the worst possible score, 0.0 is neutral, and 1.0 is the best. ### Objective Feedback Info - `objective_feedback_info: object { submittedBy }` - `submittedBy: optional object { 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: object { 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: object { 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. - `"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")