JavaScript
import Cadenya from '@cadenya/cadenya';
const client = new Cadenya({
apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});
const agentVariation = await client.agents.variations.retrieve(
'agent_01HXKD2E5NQM3T9AYWCFMGWT9Y',
'agentvar_01HXKD2E5NQM3T9AYWCF32BSPP',
{ workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q' },
);
console.log(agentVariation.metadata);import os
from cadenya import Cadenya
client = Cadenya(
api_key=os.environ.get("CADENYA_API_KEY"), # This is the default and can be omitted
)
agent_variation = client.agents.variations.retrieve(
agent_id="agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
id="agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
print(agent_variation.metadata)package main
import (
"context"
"fmt"
"go.cadenya.com/cadenya-go"
"go.cadenya.com/cadenya-go/option"
)
func main() {
client := cadenya.NewClient(
option.WithAPIKey("My API Key"),
)
agentVariation, err := client.Agents.Variations.Get(
context.TODO(),
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
cadenya.AgentVariationGetParams{
WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", agentVariation.Metadata)
}
require "cadenya"
cadenya = Cadenya::Client.new(api_key: "My API Key")
agent_variation = cadenya.agents.variations.retrieve(
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)
puts(agent_variation)cadenya agents:variations retrieve \
--api-key 'My API Key' \
--workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
--agent-id agent_01HXKD2E5NQM3T9AYWCFMGWT9Y \
--id agentvar_01HXKD2E5NQM3T9AYWCF32BSPPcurl --request GET \
--url https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id} \
--header 'Authorization: Bearer <token>'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}HttpResponse<String> response = Unirest.get("https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}")
.header("Authorization", "Bearer <token>")
.asString();{
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"createdAt": "2023-11-07T05:31:56Z",
"externalId": "<string>",
"labels": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"spec": {
"systemPromptTemplate": "<string>",
"progressiveDiscovery": {
"maxTools": 123,
"hints": [
"<string>"
]
},
"constraints": {
"maxToolCalls": 123,
"maxSubObjectives": 123,
"inactivityTimeout": "<string>"
},
"description": "<string>",
"modelConfig": {
"modelId": "claude/opus-4.6",
"temperature": 123
},
"compactionConfig": {
"triggerThreshold": 123,
"summarization": {
"instructions": "<string>"
},
"toolResultClearing": {
"preserveRecentResults": 123
}
},
"firstUserMessageTemplate": "<string>"
},
"info": {
"toolCount": 123,
"toolSetCount": 123,
"subAgentCount": 123,
"createdBy": {
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"externalId": "<string>",
"labels": {},
"createdAt": "2023-11-07T05:31:56Z"
},
"spec": {
"email": "<string>",
"name": "<string>"
}
},
"model": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"createdAt": "2023-11-07T05:31:56Z",
"externalId": "<string>",
"labels": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"score": 123,
"feedbackCount": 123,
"assignments": [
{
"type": "tool",
"tool": {
"id": "<string>",
"name": "<string>"
},
"id": "avt_01HXKD2E5NQM3T9AYWCFJE6K89"
}
],
"memoryLayerAssignments": [
{
"id": "avml_01HXKD2E5NQM3T9AYWCFX8AF59",
"memoryLayer": {
"id": "<string>",
"name": "<string>"
},
"position": 123
}
],
"memoryLayerCount": 123
}
}{
"code": 123,
"message": "<string>",
"details": [
{
"@type": "<string>"
}
]
}Agent Variations
Get a variation
One variation’s full configuration and its live score, in a single read.
GET
/
v1
/
workspaces
/
{workspaceId}
/
agents
/
{agentId}
/
variations
/
{id}
JavaScript
import Cadenya from '@cadenya/cadenya';
const client = new Cadenya({
apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});
const agentVariation = await client.agents.variations.retrieve(
'agent_01HXKD2E5NQM3T9AYWCFMGWT9Y',
'agentvar_01HXKD2E5NQM3T9AYWCF32BSPP',
{ workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q' },
);
console.log(agentVariation.metadata);import os
from cadenya import Cadenya
client = Cadenya(
api_key=os.environ.get("CADENYA_API_KEY"), # This is the default and can be omitted
)
agent_variation = client.agents.variations.retrieve(
agent_id="agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
id="agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
print(agent_variation.metadata)package main
import (
"context"
"fmt"
"go.cadenya.com/cadenya-go"
"go.cadenya.com/cadenya-go/option"
)
func main() {
client := cadenya.NewClient(
option.WithAPIKey("My API Key"),
)
agentVariation, err := client.Agents.Variations.Get(
context.TODO(),
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
cadenya.AgentVariationGetParams{
WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
},
)
if err != nil {
panic(err.Error())
}
fmt.Printf("%+v\n", agentVariation.Metadata)
}
require "cadenya"
cadenya = Cadenya::Client.new(api_key: "My API Key")
agent_variation = cadenya.agents.variations.retrieve(
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)
puts(agent_variation)cadenya agents:variations retrieve \
--api-key 'My API Key' \
--workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
--agent-id agent_01HXKD2E5NQM3T9AYWCFMGWT9Y \
--id agentvar_01HXKD2E5NQM3T9AYWCF32BSPPcurl --request GET \
--url https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id} \
--header 'Authorization: Bearer <token>'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}HttpResponse<String> response = Unirest.get("https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}")
.header("Authorization", "Bearer <token>")
.asString();{
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"createdAt": "2023-11-07T05:31:56Z",
"externalId": "<string>",
"labels": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"spec": {
"systemPromptTemplate": "<string>",
"progressiveDiscovery": {
"maxTools": 123,
"hints": [
"<string>"
]
},
"constraints": {
"maxToolCalls": 123,
"maxSubObjectives": 123,
"inactivityTimeout": "<string>"
},
"description": "<string>",
"modelConfig": {
"modelId": "claude/opus-4.6",
"temperature": 123
},
"compactionConfig": {
"triggerThreshold": 123,
"summarization": {
"instructions": "<string>"
},
"toolResultClearing": {
"preserveRecentResults": 123
}
},
"firstUserMessageTemplate": "<string>"
},
"info": {
"toolCount": 123,
"toolSetCount": 123,
"subAgentCount": 123,
"createdBy": {
"metadata": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"externalId": "<string>",
"labels": {},
"createdAt": "2023-11-07T05:31:56Z"
},
"spec": {
"email": "<string>",
"name": "<string>"
}
},
"model": {
"id": "<string>",
"accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
"workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
"name": "<string>",
"profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
"createdAt": "2023-11-07T05:31:56Z",
"externalId": "<string>",
"labels": {},
"updatedAt": "2023-11-07T05:31:56Z"
},
"score": 123,
"feedbackCount": 123,
"assignments": [
{
"type": "tool",
"tool": {
"id": "<string>",
"name": "<string>"
},
"id": "avt_01HXKD2E5NQM3T9AYWCFJE6K89"
}
],
"memoryLayerAssignments": [
{
"id": "avml_01HXKD2E5NQM3T9AYWCFX8AF59",
"memoryLayer": {
"id": "<string>",
"name": "<string>"
},
"position": 123
}
],
"memoryLayerCount": 123
}
}{
"code": 123,
"message": "<string>",
"details": [
{
"@type": "<string>"
}
]
}The complete configuration of one variation: its prompt, model, assignments, and the score it has earned.
So this is the read for “show me everything about this one variation.” For a leaderboard across an agent’s variations, List variations returns the same shape for all of them and explains what
const variation = await client.agents.variations.retrieve(agentId, variationId, { workspaceId });
console.log(variation.spec.systemPromptTemplate);
console.log(variation.spec.modelConfig); // { modelId: 'model_...', temperature: 0.2 }
console.log(variation.info.score); // 0.63
console.log(variation.info.feedbackCount); // 6
variation, err := client.Agents.Variations.Get(ctx, agentID, variationID,
cadenya.AgentVariationGetParams{WorkspaceID: cadenya.String(workspaceID)})
if err != nil {
log.Fatal(err)
}
log.Println(variation.Spec.SystemPromptTemplate)
log.Println(variation.Spec.ModelConfig) // {model_... 0.2}
log.Println(variation.Info.Score) // 0.63
log.Println(variation.Info.FeedbackCount) // 6
variation = cadenya.agents.variations.retrieve(agent_id, variation_id, workspace_id: workspace_id)
puts variation.spec.system_prompt_template
puts variation.spec.model_config # modelId: model_..., temperature: 0.2
puts variation.info.score # 0.63
puts variation.info.feedback_count # 6
curl "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/agents/${AGENT_ID}/variations/${VARIATION_ID}" \
-H "Authorization: Bearer ${CADENYA_API_KEY}"
What one read gives you
spec is the configuration you set: systemPromptTemplate, firstUserMessageTemplate, modelConfig, description. info is everything computed around it, and it returns on every read, includeInfo is a no-op here as on the other variation reads.
info field | Is |
|---|---|
score | Posterior mean of Beta(ts_alpha, ts_beta), 0.5 when fresh |
feedbackCount | How much evidence sits behind that score |
assignments | The tools, tool sets, and sub-agents wired in |
memoryLayerAssignments | The memory layers, with their cascade position |
model | The resolved model record, so you skip a lookup |
toolCount, toolSetCount, subAgentCount, memoryLayerCount | The tallies |
createdBy | Who made it |
score means and how to rank on it.
Variations take an external ID like any resource, scoped to their agent, so pass the agentvar_... value or the external_id: form. A missing ID is a 404.
Related
List variations
Every variation on the agent, and the score story in full.
Update a variation
Change the prompt or model, with the zero-value rule.
Add an assignment
What fills
info.assignments.Submit feedback
What moves
info.score.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
Example:
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Agent ID. Accepts the canonical agent_… form or the external_id:<value> form.
Example:
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"
Variation ID. Accepts the canonical agentvar_… form or the external_id:<value> form.
Example:
"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP"
⌘I