Update a variation

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.update(
  '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.update(
    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.Update(
		context.TODO(),
		"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
		"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
		cadenya.AgentVariationUpdateParams{
			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.update(
  "agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
  "agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(agent_variation)

cadenya agents:variations update \
  --api-key 'My API Key' \
  --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
  --agent-id agent_01HXKD2E5NQM3T9AYWCFMGWT9Y \
  --id agentvar_01HXKD2E5NQM3T9AYWCF32BSPP

curl --request PATCH \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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>"
  },
  "updateMask": "<string>"
}
'

<?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 => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
    ],
    'updateMask' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.patch("https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"spec\": {\n    \"systemPromptTemplate\": \"<string>\",\n    \"progressiveDiscovery\": {\n      \"maxTools\": 123,\n      \"hints\": [\n        \"<string>\"\n      ]\n    },\n    \"constraints\": {\n      \"maxToolCalls\": 123,\n      \"maxSubObjectives\": 123,\n      \"inactivityTimeout\": \"<string>\"\n    },\n    \"description\": \"<string>\",\n    \"modelConfig\": {\n      \"modelId\": \"claude/opus-4.6\",\n      \"temperature\": 123\n    },\n    \"compactionConfig\": {\n      \"triggerThreshold\": 123,\n      \"summarization\": {\n        \"instructions\": \"<string>\"\n      },\n      \"toolResultClearing\": {\n        \"preserveRecentResults\": 123\n      }\n    },\n    \"firstUserMessageTemplate\": \"<string>\"\n  },\n  \"updateMask\": \"<string>\"\n}")
  .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>"
    }
  ]
}

PATCH

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.update(
  '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.update(
    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.Update(
		context.TODO(),
		"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
		"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
		cadenya.AgentVariationUpdateParams{
			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.update(
  "agent_01HXKD2E5NQM3T9AYWCFMGWT9Y",
  "agentvar_01HXKD2E5NQM3T9AYWCF32BSPP",
  workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)

puts(agent_variation)

cadenya agents:variations update \
  --api-key 'My API Key' \
  --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
  --agent-id agent_01HXKD2E5NQM3T9AYWCFMGWT9Y \
  --id agentvar_01HXKD2E5NQM3T9AYWCF32BSPP

curl --request PATCH \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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>"
  },
  "updateMask": "<string>"
}
'

<?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 => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
    ],
    'updateMask' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

HttpResponse<String> response = Unirest.patch("https://api.cadenya.com/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"spec\": {\n    \"systemPromptTemplate\": \"<string>\",\n    \"progressiveDiscovery\": {\n      \"maxTools\": 123,\n      \"hints\": [\n        \"<string>\"\n      ]\n    },\n    \"constraints\": {\n      \"maxToolCalls\": 123,\n      \"maxSubObjectives\": 123,\n      \"inactivityTimeout\": \"<string>\"\n    },\n    \"description\": \"<string>\",\n    \"modelConfig\": {\n      \"modelId\": \"claude/opus-4.6\",\n      \"temperature\": 123\n    },\n    \"compactionConfig\": {\n      \"triggerThreshold\": 123,\n      \"summarization\": {\n        \"instructions\": \"<string>\"\n      },\n      \"toolResultClearing\": {\n        \"preserveRecentResults\": 123\n      }\n    },\n    \"firstUserMessageTemplate\": \"<string>\"\n  },\n  \"updateMask\": \"<string>\"\n}")
  .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>"
    }
  ]
}

This is how you iterate. Change a prompt, and the next objective uses it. No republish, no new variation, no version to promote.

await client.agents.variations.update(agentId, variationId, {
  workspaceId,
  spec: { systemPromptTemplate: 'You help {{ system_prompt_data.company }}. Be brief.' },
});

_, err := client.Agents.Variations.Update(ctx, agentID, variationID,
	cadenya.AgentVariationUpdateParams{
		WorkspaceID: cadenya.String(workspaceID),
		Spec: cadenya.AgentVariationSpecParam{
			SystemPromptTemplate: cadenya.String("You help {{ system_prompt_data.company }}. Be brief."),
		},
	})

cadenya.agents.variations.update(
  agent_id,
  variation_id,
  workspace_id: workspace_id,
  spec: {systemPromptTemplate: "You help {{ system_prompt_data.company }}. Be brief."}
)

curl -X PATCH "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/agents/${AGENT_ID}/variations/${VARIATION_ID}" \
  -H "Authorization: Bearer ${CADENYA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "spec": { "systemPromptTemplate": "You help {{ system_prompt_data.company }}. Be brief." } }'

Running objectives keep the prompt they started with, because each one froze the variation into its configSnapshot at creation. Only new objectives see the change.

The update merges, deeply

Send one field and the rest survive. That holds inside nested messages too: patch modelConfig.temperature alone and modelConfig.modelId stays put.

// Before: { modelId: 'model_01KWDY...', temperature: 0.3 }
await client.agents.variations.update(agentId, variationId, {
  workspaceId,
  spec: { modelConfig: { temperature: 0.9 } },
});
// After:  { modelId: 'model_01KWDY...', temperature: 0.9 }

An empty spec: {} changes nothing and returns 200.

A zero value is invisible without `updateMask`

Here is the trap. 0, "", and false are proto zero values, indistinguishable from “not sent.” A merge skips them, so the field keeps its old value and you get a 200 saying nothing happened.

// temperature is 0.2. You want deterministic output.
await client.agents.variations.update(agentId, variationId, {
  workspaceId,
  spec: { modelConfig: { temperature: 0 } },
});
// 200. temperature is still 0.2.

A variation cannot be set to temperature: 0, and a description cannot be cleared, by sending the value alone. The request succeeds and the field does not move.

updateMask fixes it. Name the paths you mean, and their values become authoritative, zero or not.

await client.agents.variations.update(agentId, variationId, {
  workspaceId,
  updateMask: 'spec.modelConfig.temperature',
  spec: { modelConfig: { temperature: 0 } },
});
// temperature: 0

Verified against the live API: temperature moves 0.5 → 0, and description clears to '', only with the mask. Both forms work, in the body or as a query parameter (?updateMask=spec.description). A masked update touches only the masked paths. Everything else is left alone, including fields you happened to include in the body. Comma-separate several: updateMask: 'spec.description,spec.modelConfig.temperature'.

You want	Send
Change a prompt	The field alone. Merge handles it.
Set `temperature: 0`	`updateMask: 'spec.modelConfig.temperature'`
Clear a `description`	`updateMask: 'spec.description'`
Change several fields	The fields alone, unless one is a zero value

Guards that hold

A model that does not exist is a 404, resolved through the external_id: form the same as everywhere else:

PATCH  spec.modelConfig.modelId = "external_id:does-not-exist"   -> 404

A disabled model is a 400 on spec.model_id, and disabling a model that any variation references is itself a 400. The two guards hold each other up, so a running objective never finds its model pulled out from under it.

What you cannot change here

Assignments and memory layers are not part of the spec. They have their own routes:

Add an assignment for tools, tool sets, and sub-agents
addMemoryLayer for memory, because position orders the cascade

score and feedbackCount are read-only. They come from feedback and drive weighted selection.

Create a variation

Every field this endpoint can change, and what they do.

Publish an agent

Why an edit goes live without a republish.

List models

What modelId accepts, and what maxInputTokens does to compaction.

Add an assignment

The capabilities that live outside the spec.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspaceId

string

required

Workspace ID.

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

agentId

string

required

Agent ID. Accepts the canonical agent_… form or the external_id:<value> form.

Example:

"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"

string

required

Variation ID. Accepts the canonical agentvar_… form or the external_id:<value> form.

Example:

"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP"

Body

application/json

Update agent variation request

metadata

object

UpdateResourceMetadata contains the user-provided fields for updating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.

Show child attributes

spec

object

AgentVariationSpec defines the operational configuration for a variation

Show child attributes

updateMask

string<field-mask>

Fields to update

Response

AgentVariation resource

metadata

object

required

Resource metadata

Show child attributes

spec

object

required

Variation specification

Show child attributes

info

object

Read-only summary information

Show child attributes

​The update merges, deeply

​A zero value is invisible without updateMask

​Guards that hold

​What you cannot change here

​Related

Create a variation

Publish an agent

List models

Add an assignment

Authorizations

Path Parameters

Body

Response

The update merges, deeply

A zero value is invisible without `updateMask`

Guards that hold

What you cannot change here

Related