> ## Documentation Index
> Fetch the complete documentation index at: https://cadenya.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Update a variation
> Change a prompt, a model, a threshold. The update merges, which means a zero value needs updateMask.
This is how you iterate. Change a prompt, and the next [objective](/docs/api-reference/objectiveservice/create-a-new-objective) uses it. No republish, no new variation, no version to promote.
```typescript TypeScript theme={null}
await client.agents.variations.update(agentId, variationId, {
workspaceId,
spec: { systemPromptTemplate: 'You help {{ system_prompt_data.company }}. Be brief.' },
});
```
```go Go theme={null}
_, 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."),
},
})
```
```ruby Ruby theme={null}
cadenya.agents.variations.update(
agent_id,
variation_id,
workspace_id: workspace_id,
spec: {systemPromptTemplate: "You help {{ system_prompt_data.company }}. Be brief."}
)
```
```bash cURL theme={null}
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.
```typescript theme={null}
// 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.
```typescript theme={null}
// 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.
```typescript theme={null}
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](/docs/api-reference/modelservice/disable-a-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](/docs/api-reference/agentvariationservice/add-an-assignment-to-a-variation) for tools, tool sets, and sub-agents
* `addMemoryLayer` for [memory](/docs/guides/memory-layers), because `position` orders the cascade
`score` and `feedbackCount` are read-only. They come from [feedback](/docs/api-reference/objectiveservice/submit-feedback-for-an-objective) and drive weighted selection.
## Related
Every field this endpoint can change, and what they do.
Why an edit goes live without a republish.
What `modelId` accepts, and what `maxInputTokens` does to compaction.
The capabilities that live outside the spec.
## OpenAPI
````yaml patch /v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}
openapi: 3.1.0
info:
title: Cadenya API
description: API for the Cadenya Agent Runtime platform.
version: '1.0'
servers:
- url: https://api.cadenya.com
description: Production server
security:
- bearerAuth: []
tags:
- name: AIProviderKeyService
- name: APIKeyService
description: |-
Issue, rotate, disable, and revoke a workspace's API keys. Every key
belongs to exactly one workspace; the system-managed global account key is
managed via GlobalAPIKeyService instead.
- name: AccountService
description: >-
Manage the authenticated account. Accounts are the top-level
organizational
unit and contain one or more workspaces.
- name: AgentScheduleService
description: >-
Manage recurring schedules attached to agents. Schedules trigger
objectives
on a cadence defined by AgentScheduleSpec.Schedule.
- name: AgentService
description: >-
Manage AI agents within a workspace. Agents define AI behavior and tool
access.
- name: AgentVariationService
description: >-
Manage variations of an agent and their tool, sub-agent, and memory layer
assignments.
- name: GlobalAPIKeyService
description: |-
Manage the account's system-provisioned global API key. The global key is
the only key that spans every workspace; it is created by the system and
cannot be deleted, so the surface is retrieve, rotate, and the
disable/enable kill switch.
- name: MemoryService
description: >-
Manage memory layers and their entries. Layers are named containers that
can
be composed into an objective's memory cascade; entries are the keyed values
within a layer. System-managed layers (e.g., episodic layers created by the
runtime) cannot be mutated through this API.
- name: ModelService
description: |-
Manage LLM models available to a workspace. Models represent provider and
family pairs (e.g., "anthropic/claude-sonnet-4.6"). Workspaces are seeded
with the supported models and you can enable or disable each one.
- name: ObjectiveEventStreamsService
- name: ObjectiveService
- name: ProfilesService
description: |-
Operations on profiles, the account-level principals (users, API keys,
system) that authenticate against the API.
- name: SearchService
- name: TenantService
description: >-
Read and erase tenants and the subjects under them. Tenants and subjects
are
created by assertion — on objective creation or widget session mint — never
directly, so this service has no create or update: it exists to enumerate what
assertions have produced, and to destroy it on request.
- name: ToolService
description: >-
Manage tool sets and the tools they contain. Tool sets group related
tools,
and tools define specific capabilities available to agents.
When a tool set is managed, only API key actors can modify its tools; human
(profile) actors cannot.
- name: UploadService
description: |-
Issue short-lived presigned URLs for direct client-to-object-storage
uploads. Created uploads can be referenced by id when creating or updating
resources that accept binary content (e.g., MemoryEntry).
- name: WidgetService
description: |-
Manage embeddable chat widgets. A widget binds an agent to a globally
unique hostname with a per-widget origin allowlist; browsers reach it with
session tokens minted via WidgetSessionService.
- name: WidgetSessionService
description: >-
Mint and manage widget sessions. Session creation is server-to-server
only:
the customer's backend authenticates its visitor, asserts tenant/subject
context, attaches any per-visitor secrets, and receives a short-lived
bearer token the browser uses against the widget host.
- name: WorkspaceAdminService
description: >-
Administer workspaces across the account: create and archive workspaces
and
manage their membership. These operations are account-scoped and require the
admin role (a token whose profile holds the WorkOS admin role); they live
under /v1/account/workspaces rather than the workspace-scoped /v1/workspaces
tree so an admin can manage any workspace in the account, including ones they
are not themselves a member of.
- name: WorkspaceSecretService
- name: WorkspaceService
description: |-
Manage workspaces within an account. Workspaces provide organizational
grouping and isolation for resources such as agents, tools, and API keys.
This is the workspace-scoped, end-user surface. Administrative operations
(create / archive workspaces, manage members) live in WorkspaceAdminService
under /v1/account/workspaces and require the admin role.
paths:
/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}:
patch:
tags:
- AgentVariationService
- Agent Variations
summary: Update a variation
description: Updates a variation for an agent
operationId: AgentVariationService_UpdateAgentVariation
parameters:
- name: workspaceId
in: path
description: Workspace ID.
required: true
schema:
type: string
example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
- name: agentId
in: path
description: >-
Agent ID. Accepts the canonical `agent_…` form or the
`external_id:` form.
required: true
schema:
example: agent_01HXKD2E5NQM3T9AYWCFMGWT9Y
type: string
- name: id
in: path
description: >-
Variation ID. Accepts the canonical `agentvar_…` form or the
`external_id:` form.
required: true
schema:
type: string
example: agentvar_01HXKD2E5NQM3T9AYWCF32BSPP
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAgentVariationRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AgentVariation'
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
x-codeSamples:
- lang: JavaScript
source: |-
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);
- lang: Python
source: |-
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)
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"go.cadenya.com/cadenya-go\"\n\t\"go.cadenya.com/cadenya-go/option\"\n)\n\nfunc main() {\n\tclient := cadenya.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tagentVariation, err := client.Agents.Variations.Update(\n\t\tcontext.TODO(),\n\t\t\"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y\",\n\t\t\"agentvar_01HXKD2E5NQM3T9AYWCF32BSPP\",\n\t\tcadenya.AgentVariationUpdateParams{\n\t\t\tWorkspaceID: cadenya.String(\"workspace_01HXKD2E5NQM3T9AYWCF133E3Q\"),\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", agentVariation.Metadata)\n}\n"
- lang: Ruby
source: |-
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)
- lang: CLI
source: |-
cadenya agents:variations update \
--api-key 'My API Key' \
--workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
--agent-id agent_01HXKD2E5NQM3T9AYWCFMGWT9Y \
--id agentvar_01HXKD2E5NQM3T9AYWCF32BSPP
components:
schemas:
UpdateAgentVariationRequest:
type: object
properties:
workspaceId:
readOnly: true
example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
type: string
description: Workspace ID.
agentId:
readOnly: true
example: agent_01HXKD2E5NQM3T9AYWCFMGWT9Y
type: string
description: >-
Agent ID. Accepts the canonical `agent_…` form or the
`external_id:` form.
id:
readOnly: true
example: agentvar_01HXKD2E5NQM3T9AYWCF32BSPP
type: string
description: >-
Variation ID. Accepts the canonical `agentvar_…` form or the
`external_id:` form.
metadata:
$ref: '#/components/schemas/UpdateResourceMetadata'
spec:
$ref: '#/components/schemas/AgentVariationSpec'
updateMask:
type: string
description: Fields to update
format: field-mask
description: Update agent variation request
AgentVariation:
required:
- metadata
- spec
type: object
properties:
metadata:
allOf:
- $ref: '#/components/schemas/ResourceMetadata'
description: Resource metadata
spec:
allOf:
- $ref: '#/components/schemas/AgentVariationSpec'
description: Variation specification
info:
readOnly: true
allOf:
- $ref: '#/components/schemas/AgentVariationInfo'
description: Read-only summary information
description: AgentVariation resource
Status:
type: object
properties:
code:
type: integer
description: >-
The status code, which should be an enum value of
[google.rpc.Code][google.rpc.Code].
format: int32
message:
type: string
description: >-
A developer-facing error message, which should be in English. Any
user-facing error message should be localized and sent in the
[google.rpc.Status.details][google.rpc.Status.details] field, or
localized by the client.
details:
type: array
items:
$ref: '#/components/schemas/GoogleProtobufAny'
description: >-
A list of messages that carry the error details. There is a common
set of message types for APIs to use.
description: >-
The `Status` type defines a logical error model that is suitable for
different programming environments, including REST APIs and RPC APIs. It
is used by [gRPC](https://github.com/grpc). Each `Status` message
contains three pieces of data: error code, error message, and error
details. You can find out more about this error model and how to work
with it in the [API Design
Guide](https://cloud.google.com/apis/design/errors).
UpdateResourceMetadata:
required:
- name
type: object
properties:
name:
type: string
description: >-
Human-readable name for the resource (e.g., "Customer Support
Agent", "Email Tool")
externalId:
type: string
description: >-
External ID for the resource (e.g., a workflow ID from an external
system)
labels:
type: object
additionalProperties:
type: string
description: |-
Key-value pairs for categorization and filtering. Values are 0-63
alphanumeric characters with "-", "_", or "." allowed between; keys
follow the same shape and additionally accept an optional DNS-subdomain
prefix (e.g. "cadenya.com/") of at most 253 characters.
Examples: {"environment": "production", "team": "platform", "version": "v2"}
description: |-
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.
AgentVariationSpec:
type: object
properties:
systemPromptTemplate:
type: string
description: >-
Liquid template for the system prompt of objectives using this
variation.
Rendered with CreateObjectiveRequest.system_prompt_data into Objective.system_prompt.
progressiveDiscovery:
allOf:
- $ref: '#/components/schemas/AgentVariationSpec_ProgressiveDiscovery'
description: >-
ProgressiveDiscovery is an optional config that, when set, will load
a Cadenya provided tool that
can search for tools in the assigned tool sets or tools.
Note: Sub-agents are always loaded as a tool regardless of this value.
constraints:
allOf:
- $ref: '#/components/schemas/AgentVariationSpec_Constraints'
description: Execution constraints
description:
type: string
description: >-
Human-readable description of what this variation does or when it
should be used
modelConfig:
allOf:
- $ref: '#/components/schemas/AgentVariationSpec_ModelConfig'
description: Model configuration for this variation
compactionConfig:
allOf:
- $ref: '#/components/schemas/AgentVariationSpec_CompactionConfig'
description: >-
Compaction configuration for managing context window limits during
long-running objectives.
When not set, the system uses a default summarization strategy at 75% context window usage.
firstUserMessageTemplate:
type: string
description: >-
Liquid template for the first user message of objectives using this
variation.
Rendered with CreateObjectiveRequest.first_user_message_data into
Objective.first_user_message, the first user message in the LLM chat history.
CreateObjectiveRequest.first_user_message, when set, overrides the rendered
result. If neither this template nor first_user_message is present, objective
creation is rejected with InvalidArgument.
description: AgentVariationSpec defines the operational configuration for a variation
ResourceMetadata:
required:
- id
- accountId
- workspaceId
- name
- profileId
- createdAt
type: object
properties:
id:
readOnly: true
type: string
description: >-
Unique identifier for the resource (prefixed ULID, e.g.,
"agent_01HXK...")
accountId:
readOnly: true
example: account_01HXKD2E5NQM3T9AYWCFTJHJVF
type: string
description: >-
Account this resource belongs to for multi-tenant isolation
(prefixed ULID)
workspaceId:
readOnly: true
example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
type: string
description: >-
Workspace this resource belongs to for organizational grouping
(prefixed ULID)
name:
type: string
description: >-
Human-readable name for the resource (e.g., "Customer Support
Agent", "Email Tool")
Required for resources that users interact with directly
externalId:
type: string
description: >-
External ID for the resource (e.g., a workflow ID from an external
system)
labels:
type: object
additionalProperties:
type: string
description: |-
Key-value pairs for categorization and filtering. Values are 0-63
alphanumeric characters with "-", "_", or "." allowed between; keys
follow the same shape and additionally accept an optional DNS-subdomain
prefix (e.g. "cadenya.com/") of at most 253 characters.
Examples: {"environment": "production", "team": "platform", "version": "v2"}
profileId:
readOnly: true
example: profile_01HXKD2E5NQM3T9AYWCFS0AP08
type: string
description: ID of the actor (user or service account) that created this resource
createdAt:
readOnly: true
type: string
description: Timestamp when this resource was created
format: date-time
updatedAt:
readOnly: true
type: string
description: Timestamp when this resource was last updated
format: date-time
description: >-
Standard metadata for persistent, named resources (e.g., agents, tools,
prompts)
AgentVariationInfo:
type: object
properties:
toolCount:
readOnly: true
type: integer
description: Number of individual tools assigned to this variation
format: int32
toolSetCount:
readOnly: true
type: integer
description: Number of tool sets assigned to this variation
format: int32
subAgentCount:
readOnly: true
type: integer
description: Number of sub-agents assigned to this variation
format: int32
createdBy:
$ref: '#/components/schemas/Profile'
model:
readOnly: true
allOf:
- $ref: '#/components/schemas/ResourceMetadata'
description: Metadata for the model assigned to this variation
score:
type: number
description: |-
Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.
format: float
feedbackCount:
type: integer
description: Total number of objective feedbacks received for this variation
format: int32
assignments:
readOnly: true
type: array
items:
$ref: '#/components/schemas/VariationAssignment'
description: |-
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.
memoryLayerAssignments:
readOnly: true
type: array
items:
$ref: '#/components/schemas/VariationMemoryLayerAssignment'
description: |-
Read-only list of memory layer assignments for this variation,
returned in ascending `position` (most specific first — resolution
order). Capped at 10 entries.
memoryLayerCount:
readOnly: true
type: integer
description: Count of memory layer assignments.
format: int32
description: >-
AgentVariationInfo provides read-only summary information about a
variation
GoogleProtobufAny:
type: object
properties:
'@type':
type: string
description: The type of the serialized message.
additionalProperties: true
description: >-
Contains an arbitrary serialized message along with a @type that
describes the type of the serialized message.
AgentVariationSpec_ProgressiveDiscovery:
type: object
properties:
maxTools:
type: integer
description: >-
The most tool names tool_search will load in a single call.
Requesting more
than this returns an error telling the model to retry in smaller batches --
it is a per-call batch limit, not a ceiling on how many tools an objective
may end up with.
format: int32
hints:
type: array
items:
type: string
description: >-
Free-text guidance appended to the discoverable-tools appendix in
the
system prompt. Hints steer the model's choice of tool names; they do not
filter or rank anything, because tool_search matches names exactly rather
than searching.
description: >-
ProgressiveDiscovery is used to indicate that the agent should
automatically discover tools that are not explicitly assigned to it.
Max tools is the maximum number of tools that can be discovered per search.
Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
AgentVariationSpec_Constraints:
type: object
properties:
maxToolCalls:
type: integer
description: The maximum number of tool calls that can be made. 0 means no limit.
format: int32
maxSubObjectives:
type: integer
description: >-
The maximum number of sub-objectives that can be created. 0 means no
limit.
format: int32
inactivityTimeout:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
description: |-
How long an objective may sit with no activity (no user messages, no
LLM calls) before it is finalized as timed out. Between 1 minute and
24 hours, expressed as a duration string in seconds (e.g. "7200s").
When not set, objectives are still swept at the system-wide 24 hour
maximum — every objective eventually reaches a terminal state.
Note: no gnostic integer hint here on purpose. The Envoy gRPC-JSON
transcoder only accepts the canonical protobuf JSON form for
Durations — a "s" string — so the SDKs must type this as a
string (like AgentScheduleSpec.every), not an integer.
AgentVariationSpec_ModelConfig:
type: object
properties:
modelId:
example: claude/opus-4.6
type: string
description: >-
The model identifier in family/model format (e.g.,
"claude/opus-4.6", "claude/sonnet-4.5")
temperature:
type: number
description: |-
Sampling temperature for model inference (0.0 to 1.0)
Lower values produce more deterministic outputs, higher values increase randomness
format: float
description: ModelConfig defines the model configuration for a variation
AgentVariationSpec_CompactionConfig:
type: object
properties:
triggerThreshold:
type: number
description: >-
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%)
format: float
summarization:
allOf:
- $ref: '#/components/schemas/CompactionConfig_SummarizationStrategy'
description: >-
Strategies — set one or more. When multiple are set, they execute in
order:
tool_result_clearing → summarization.
When none are set, defaults to summarization with the system default prompt.
toolResultClearing:
$ref: '#/components/schemas/CompactionConfig_ToolResultClearingStrategy'
description: >-
CompactionConfig defines how context window compaction behaves for
objectives using this variation.
Profile:
required:
- metadata
- spec
type: object
properties:
metadata:
$ref: '#/components/schemas/AccountResourceMetadata'
spec:
$ref: '#/components/schemas/ProfileSpec'
description: |-
A profile identifies a user or non-human principal (such as an API key)
at the account level. Profiles are account-scoped and can be granted access
to multiple workspaces.
VariationAssignment:
oneOf:
- $ref: '#/components/schemas/VariationAssignment_Tool'
- $ref: '#/components/schemas/VariationAssignment_ToolSet'
- $ref: '#/components/schemas/VariationAssignment_Agent'
discriminator:
propertyName: type
mapping:
tool:
$ref: '#/components/schemas/VariationAssignment_Tool'
toolSet:
$ref: '#/components/schemas/VariationAssignment_ToolSet'
agent:
$ref: '#/components/schemas/VariationAssignment_Agent'
description: >-
A read-only reference to a single tool, tool set, or sub-agent attached
to
a variation. Read the full set of assignments via `AgentVariationInfo.assignments`;
mutations go through the dedicated add/remove assignment endpoints.
The `id` identifies the assignment itself (not the referenced resource) and
is the handle used to remove the assignment. It is returned by the add
endpoint and present on every entry in `AgentVariationInfo.assignments`.
VariationMemoryLayerAssignment:
type: object
properties:
id:
readOnly: true
example: avml_01HXKD2E5NQM3T9AYWCFX8AF59
type: string
description: |-
Assignment row id — handle for removing the assignment. Distinct
from the referenced memory layer's id.
memoryLayer:
allOf:
- $ref: '#/components/schemas/BareMetadata'
description: The attached memory layer.
position:
type: integer
description: |-
Position in the variation's baseline cascade. Position is
specificity, CSS-style: a LOWER position is more specific and is
consulted first; the highest-position assignment is the most
general fallback. Gaps are fine — only relative position matters.
Positions must be unique within a variation; a request that would
collide with an existing assignment's position is rejected with
InvalidArgument.
format: int32
description: |-
VariationMemoryLayerAssignment attaches a single MemoryLayer to a
variation at a given position in the variation's baseline memory
cascade. A variation has at most one assignment per memory_layer_id.
Variations only support whole-layer attachments — entry pinning is an
objective-level capability.
CompactionConfig_SummarizationStrategy:
type: object
properties:
instructions:
type: string
description: |-
Custom instructions that guide what the summarizer preserves.
Replaces the default summarization prompt entirely.
Example: "Preserve all code snippets, variable names, and technical decisions."
description: >-
SummarizationStrategy configures LLM-powered summarization of older
conversation turns.
CompactionConfig_ToolResultClearingStrategy:
type: object
properties:
preserveRecentResults:
type: integer
description: |-
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
format: int32
description: >-
ToolResultClearingStrategy configures clearing of older tool result
content.
AccountResourceMetadata:
required:
- id
- accountId
- name
- profileId
type: object
properties:
id:
readOnly: true
type: string
description: >-
Unique identifier for the resource (prefixed ULID, e.g.,
"apikey_01HXK...")
accountId:
readOnly: true
example: account_01HXKD2E5NQM3T9AYWCFTJHJVF
type: string
description: >-
Account this resource belongs to for multi-tenant isolation
(prefixed ULID)
name:
type: string
description: >-
Human-readable name for the resource (e.g., "Customer Support
Agent", "Email Tool")
Required for resources that users interact with directly
externalId:
type: string
description: >-
External ID for the resource (e.g., a workflow ID from an external
system)
labels:
type: object
additionalProperties:
type: string
description: |-
Key-value pairs for categorization and filtering. Values are 0-63
alphanumeric characters with "-", "_", or "." allowed between; keys
follow the same shape and additionally accept an optional DNS-subdomain
prefix (e.g. "cadenya.com/") of at most 253 characters.
Examples: {"environment": "production", "team": "platform", "version": "v2"}
profileId:
readOnly: true
example: profile_01HXKD2E5NQM3T9AYWCFS0AP08
type: string
createdAt:
readOnly: true
type: string
format: date-time
description: >-
AccountResourceMetadata is used to represent a resource that is
associated to an account but not to a workspace.
ProfileSpec:
required:
- type
type: object
properties:
email:
type: string
description: >-
Email address of the profile. Required and unique within an account
for
user profiles.
name:
type: string
description: Display name (e.g., "Bobby Tables").
type:
enum:
- PROFILE_TYPE_UNSPECIFIED
- PROFILE_TYPE_USER
- PROFILE_TYPE_API_KEY
- PROFILE_TYPE_SYSTEM
type: string
description: >-
Whether this profile represents a human user, an API key, or a
system
principal.
format: enum
description: Configuration for a profile.
VariationAssignment_Tool:
type: object
required:
- type
- tool
properties:
type:
type: string
enum:
- tool
tool:
$ref: '#/components/schemas/BareMetadata'
id:
readOnly: true
example: avt_01HXKD2E5NQM3T9AYWCFJE6K89
type: string
VariationAssignment_ToolSet:
type: object
required:
- type
- toolSet
properties:
type:
type: string
enum:
- toolSet
toolSet:
$ref: '#/components/schemas/BareMetadata'
id:
readOnly: true
example: avt_01HXKD2E5NQM3T9AYWCFJE6K89
type: string
VariationAssignment_Agent:
type: object
required:
- type
- agent
properties:
type:
type: string
enum:
- agent
agent:
$ref: '#/components/schemas/BareMetadata'
id:
readOnly: true
example: avt_01HXKD2E5NQM3T9AYWCFJE6K89
type: string
BareMetadata:
type: object
properties:
id:
readOnly: true
type: string
name:
readOnly: true
type: string
description: >-
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).
description: |-
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.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````