List variations

GET/v1/agents/{agentId}/variations

Lists all variations for an agent

Path ParametersExpand Collapse

agentId: string

Query ParametersExpand Collapse

cursor: optional string

Pagination cursor from previous response

includeInfo: 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

formatint32

sortOrder: optional string

Sort order for results (asc or desc by creation time)

ReturnsExpand Collapse

items: optional array of AgentVariation { metadata, spec, info }

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

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

id: string

Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

accountId: string

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

createdAt: string

Timestamp when this resource was created

formatdate-time

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: AgentVariationSpec { compactionConfig, constraints, description, 6 more }

AgentVariationSpec defines the operational configuration for a variation

compactionConfig: optional AgentVariationSpecCompactionConfig { summarization, toolResultClearing, triggerThreshold }

CompactionConfig defines how context window compaction behaves for objectives using this variation.

summarization: optional CompactionConfigSummarizationStrategy { 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 CompactionConfigToolResultClearingStrategy { 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

formatint32

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%)

formatfloat

constraints: optional AgentVariationSpecConstraints { maxSubObjectives, maxToolCalls }

Execution constraints

maxSubObjectives: optional number

The maximum number of sub-objectives that can be created. 0 means no limit.

formatint32

maxToolCalls: optional number

The maximum number of tool calls that can be made. 0 means no limit.

formatint32

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 AgentVariationSpecModelConfig { 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

formatfloat

prompt: optional string

The system prompt for this variation

toolSelection: optional AgentVariationSpecToolSelection { assignedTools, autoDiscovery }

Tool selection strategy

assignedTools: optional ToolSelectionAssignedTools { 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 ToolSelectionAutoDiscovery { 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.

formatint32

info: optional AgentVariationInfo { assignments, createdBy, feedbackCount, 5 more }

AgentVariationInfo provides read-only summary information about a variation

assignments: optional array of VariationAssignment { id, agent, tool, toolSet }

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 BareMetadata { 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

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 BareMetadata { id, name }

id: 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 BareMetadata { id, name }

id: 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 Profile { metadata, spec }

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

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

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

id: string

Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

accountId: string

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

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

profileId: string

externalId: optional string

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

labels: optional map[string]

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

spec: ProfileSpec { type, email, name }

ProfileSpec contains the profile-specific fields

type: "PROFILE_TYPE_USER" or "PROFILE_TYPE_API_KEY" or "PROFILE_TYPE_SYSTEM"

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

formatenum

One of the following:

"PROFILE_TYPE_USER"

"PROFILE_TYPE_API_KEY"

"PROFILE_TYPE_SYSTEM"

email: optional string

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

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

feedbackCount: optional number

Total number of objective feedbacks received for this variation

formatint32

model: optional ResourceMetadata { id, accountId, createdAt, 5 more }

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

id: string

Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

accountId: string

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

createdAt: string

Timestamp when this resource was created

formatdate-time

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.

formatfloat

subAgentCount: optional number

Number of sub-agents assigned to this variation

formatint32

toolCount: optional number

Number of individual tools assigned to this variation

formatint32

toolSetCount: optional number

Number of tool sets assigned to this variation

formatint32

pagination: optional Page { nextCursor, total }

nextCursor: optional string

total: optional number

List variations

curl https://api.cadenya.com/v1/agents/$AGENT_ID/variations \
    -H "Authorization: Bearer $CADENYA_API_KEY"

{
  "items": [
    {
      "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
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}

Returns Examples

{
  "items": [
    {
      "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
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}