> ## 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.
# Get an objective
> The state of one run. What to poll, what it does not tell you, and where the answer lives.
The most-called read in the API. You create an objective, it works in the background, and this is how you find out where it got to.
```typescript TypeScript theme={null}
const objective = await client.objectives.retrieve(objectiveId, { workspaceId });
console.log(objective.state); // 'STATE_WAITING'
console.log(objective.stateMessage); // ''
```
```go Go theme={null}
objective, err := client.Objectives.Get(ctx, objectiveID,
cadenya.ObjectiveGetParams{WorkspaceID: cadenya.String(workspaceID)})
fmt.Println(objective.State) // STATE_WAITING
fmt.Println(objective.StateMessage) // ""
```
```ruby Ruby theme={null}
objective = cadenya.objectives.retrieve(objective_id, workspace_id: workspace_id)
puts objective.state # STATE_WAITING
puts objective.state_message # ""
```
```bash cURL theme={null}
curl "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/objectives/${OBJECTIVE_ID}" \
-H "Authorization: Bearer ${CADENYA_API_KEY}"
```
## The seven states
| State | Meaning | Terminal |
| ----------------- | ---------------------------------------------------------------------------- | -------- |
| `STATE_PENDING` | Accepted, not yet started | no |
| `STATE_RUNNING` | The agent is working | no |
| `STATE_WAITING` | Answered, waiting for your next turn | no |
| `STATE_FINALIZED` | Produced its structured output | yes |
| `STATE_CANCELLED` | A caller [cancelled](/docs/api-reference/objectiveservice/cancel-an-objective) it | yes |
| `STATE_TIMED_OUT` | Hit the inactivity timeout | yes |
| `STATE_FAILED` | Errored out | yes |
`STATE_WAITING` is the one that trips people. It is not terminal. An agent that answers your message and expects a reply parks in `WAITING`, and an agent with no [`outputDefinition`](/docs/api-reference/agentservice/create-a-new-agent) parks there for good, because it has no structured output to finalize on. If you poll for `STATE_FINALIZED` on such an agent, you poll forever. Poll for a terminal state, or watch for `WAITING` when you are driving a conversation.
## `output` populates only on `STATE_FINALIZED`
`output` is a field on the objective, but it is empty until the objective finalizes, so it is omitted from the response on a pending, running, or waiting one. Read it back on a finalized objective:
```typescript theme={null}
const objective = await client.objectives.retrieve(objectiveId, { workspaceId });
if (objective.state === 'STATE_FINALIZED') {
console.log(objective.output); // the structured result, matching the agent's outputDefinition
}
```
The same result is mirrored on the `finalized` event, so if you are already reading [events](/docs/api-reference/objectiveservice/list-objective-events) or a [webhook](/docs/guides/webhooks), take it from `finalized.output` there rather than making a second call:
```typescript theme={null}
for await (const event of await client.objectives.listEvents(objectiveId, { workspaceId })) {
if (event.data?.type === 'finalized') {
console.log(event.data.finalized.output); // same structured result
}
}
```
An objective whose agent has no `outputDefinition` never finalizes, so its `output` never populates; it ends in `STATE_WAITING`.
## What the response does carry
`systemPrompt` is the **rendered** prompt, with `system_prompt_data.` interpolated. Create an objective with `systemPromptData: { company: 'Acme' }` against a variation templated on `{{ system_prompt_data.company }}`, and this reads back `"Serve Acme."`, not the template. It is the exact prompt the agent ran on.
`configSnapshot` is the agent and variation frozen at creation. This is why an objective is stable: edit the variation afterward and running objectives keep the config they started with. Read `configSnapshot.agentVariation` to see which variation served the run.
`secrets` is always redacted to `[]` on a read, the same as everywhere. `memoryCascade` and `info.effectiveMemoryCascade` describe the layers the run resolves keys against.
## `info` needs no opt-in
`includeInfo` is a no-op on this endpoint. The full `info` block returns on every request: `totalEvents`, `totalToolCalls`, `totalInputTokens`, `totalOutputTokens`, `totalContextWindows`, `totalIterations`, `currentContextWindowId`, `agent`, `agentVariation`, `createdBy`, and `effectiveMemoryCascade`.
Those counts are the cheap way to watch progress without pulling the event history: `totalIterations` climbs as the agent loops, `totalToolCalls` as it acts.
## Fetch by your own ID
Objectives take an [external ID](/docs/guides/use-your-own-ids). Tag one with a ticket number at creation and fetch it back by that, never storing a Cadenya ID:
```typescript theme={null}
await client.objectives.create({
workspaceId,
agentId: 'external_id:support',
metadata: { externalId: 'ticket-4242' },
systemPromptData: { company: 'Acme' },
firstUserMessage: 'My order never arrived.',
});
const objective = await client.objectives.retrieve('external_id:ticket-4242', { workspaceId });
```
A nonexistent ID, in either form, is a `404`.
## Related
Where the `finalized` event, and the output, live.
Watch the run instead of polling this endpoint.
The next turn, when state is `WAITING`.
`outputDefinition`, and what lets a run finalize.
## OpenAPI
````yaml get /v1/workspaces/{workspaceId}/objectives/{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}/objectives/{id}:
get:
tags:
- ObjectiveService
- Objectives
summary: Get an objective by ID
description: Retrieves an objective by ID from the workspace
operationId: ObjectiveService_GetObjective
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
- name: id
in: path
required: true
schema:
example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Objective'
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 objective = await
client.objectives.retrieve('obj_01HXKD2E5NQM3T9AYWCFQAZGFV', {
workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
});
console.log(objective.configSnapshot);
- 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
)
objective = client.objectives.retrieve(
id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
)
print(objective.config_snapshot)
- 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\tobjective, err := client.Objectives.Get(\n\t\tcontext.TODO(),\n\t\t\"obj_01HXKD2E5NQM3T9AYWCFQAZGFV\",\n\t\tcadenya.ObjectiveGetParams{\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\", objective.ConfigSnapshot)\n}\n"
- lang: Ruby
source: |-
require "cadenya"
cadenya = Cadenya::Client.new(api_key: "My API Key")
objective = cadenya.objectives.retrieve(
"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
)
puts(objective)
- lang: CLI
source: |-
cadenya objectives retrieve \
--api-key 'My API Key' \
--workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
--id obj_01HXKD2E5NQM3T9AYWCFQAZGFV
components:
schemas:
Objective:
required:
- metadata
- configSnapshot
- state
- systemPrompt
- firstUserMessage
type: object
properties:
metadata:
$ref: '#/components/schemas/OperationMetadata'
configSnapshot:
readOnly: true
allOf:
- $ref: '#/components/schemas/ObjectiveConfigSnapshot'
description: >-
The snapshot of the agent and the variation selected (either
explicitly or by sampling) will be set here. Cadenya stores
the point-in-time snapshot of the configuration used to start an objective and maintains it throughout the entire lifecycle
so that changes to agents and variations in the middle of a cycle don't impact the objective itself
state:
readOnly: true
enum:
- STATE_UNSPECIFIED
- STATE_PENDING
- STATE_RUNNING
- STATE_WAITING
- STATE_FAILED
- STATE_CANCELLED
- STATE_FINALIZED
- STATE_TIMED_OUT
type: string
description: The current lifecycle state of the objective.
format: enum
stateMessage:
readOnly: true
type: string
description: >-
Optional human-readable detail about the current state (e.g. a
failure reason).
info:
readOnly: true
allOf:
- $ref: '#/components/schemas/ObjectiveInfo'
description: Read-only aggregated info about this objective's execution
systemPrompt:
readOnly: true
type: string
description: >-
system_prompt is read-only, derived from the selected variation's
prompt
firstUserMessage:
type: string
description: >-
The first user message in the LLM chat history, either provided
explicitly at
creation or rendered from the variation's first_user_message_template.
parentObjectiveId:
readOnly: true
example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV
type: string
description: >-
A parent objective means the objective was spawned off using a
separate agent to complete an objective
secrets:
type: array
items:
$ref: '#/components/schemas/Objective_Secret'
description: >-
Secrets that can be used in the headers for tool calls using the
secret interpolation format.
systemPromptData:
readOnly: true
type: object
additionalProperties: true
description: Arbitrary data rendered into the variation's system_prompt_template
memoryCascade:
type: array
items:
$ref: '#/components/schemas/MemoryReference'
description: |-
Memory layers/entries layered over the baseline cascade inherited
from the selected variation — element-level rules over inherited
styles, in CSS terms.
Array order is resolution order: EARLIER elements are more specific
and are consulted first. Entries pinned via memory_entry_id behave
as single-entry layers at their position.
System-managed layers (e.g., episodic) cannot be referenced here;
they attach themselves automatically based on the episodic key.
Size cap: the TOTAL effective cascade (this field + the variation's
memory layer assignments) must not exceed 10 entries. A request
that would produce a larger cascade is rejected with
InvalidArgument.
output:
readOnly: true
type: object
additionalProperties: true
description: >-
The output of the objective, populated when the objective completes.
Will match the schema of output_json_schema or output_json_inferred.
This will only be set if the state of the objective is set to STATE_FINALIZED
firstUserMessageData:
readOnly: true
type: object
additionalProperties: true
description: >-
Arbitrary data rendered into the variation's
first_user_message_template
episodicMemory:
allOf:
- $ref: '#/components/schemas/ObjectiveEpisodicConfig'
description: >-
If the agent variation that is selected has episodic memory enabled,
then this key is used to create/update a memory layer
specific to the episodic memory. The layer may have a TTL configured by the variation.
pinnedParameters:
readOnly: true
type: object
additionalProperties:
type: string
description: |-
Parameters forced onto this objective's tool calls, as provided at
creation. See CreateObjectiveRequest.pinned_parameters for semantics.
description: >-
Objective is the data for an objective. It contains the snapshotted
fields for the selected agent and variation. Secrets are returned
only with their names, and the output definition is copied from the agent's configuration.
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).
OperationMetadata:
required:
- id
- accountId
- workspaceId
- profileId
- createdAt
type: object
properties:
id:
readOnly: true
type: string
description: >-
Unique identifier for the operation (prefixed ULID, e.g.,
"obj_01HXK...")
accountId:
readOnly: true
example: account_01HXKD2E5NQM3T9AYWCFTJHJVF
type: string
description: >-
Account this operation belongs to for multi-tenant isolation
(prefixed ULID)
workspaceId:
readOnly: true
example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
type: string
description: >-
Workspace this operation belongs to for organizational grouping
(prefixed ULID)
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: {"priority": "high", "source": "api", "workflow": "onboarding"}
createdAt:
readOnly: true
type: string
description: |-
Timestamp when this operation was created
ULID includes timestamp information, but this explicit field enables easier querying
format: date-time
externalId:
type: string
description: >-
External ID for the operation (e.g., a workflow ID from an external
system)
profileId:
readOnly: true
example: profile_01HXKD2E5NQM3T9AYWCFS0AP08
type: string
description: >-
ID of the actor (user or service account) that created this
operation
description: >-
Metadata for ephemeral operations and activities (e.g., objectives,
executions, runs)
ObjectiveConfigSnapshot:
type: object
properties:
agent:
$ref: '#/components/schemas/Agent'
agentVariation:
$ref: '#/components/schemas/AgentVariation'
agentSchedule:
$ref: '#/components/schemas/AgentSchedule'
description: >-
ObjectiveConfigSnapshot is the point-in-time snapshot of the agent,
variation, and
(when applicable) schedule that an objective was started with.
ObjectiveInfo:
required:
- totalEvents
- totalToolCalls
- totalInputTokens
- totalOutputTokens
- totalContextWindows
- totalIterations
- createdBy
- effectiveMemoryCascade
- agent
- agentVariation
- currentContextWindowId
type: object
properties:
totalEvents:
readOnly: true
type: integer
description: Total number of events generated during this objective's execution
format: int32
totalToolCalls:
readOnly: true
type: integer
description: Total number of tool calls made during execution
format: int32
totalInputTokens:
readOnly: true
type: integer
description: >-
Total input tokens consumed across all LLM completions across all
context windows
format: int32
totalOutputTokens:
readOnly: true
type: integer
description: >-
Total output tokens generated across all LLM completions across all
context windows
format: int32
totalContextWindows:
readOnly: true
type: integer
description: Total number of context windows that this objective has generated
format: int32
totalIterations:
readOnly: true
type: integer
format: int32
createdBy:
$ref: '#/components/schemas/Profile'
effectiveMemoryCascade:
readOnly: true
type: array
items:
$ref: '#/components/schemas/MemoryReference'
description: |-
The effective memory cascade at objective creation time: the
episodic layer (when present), then Objective.memory_cascade, then
the variation's baseline layers by ascending position. Order is
resolution order — index 0 is the most specific and is consulted
first; the first layer containing a key wins. Returned on reads so
clients can see exactly what the objective resolves against without
re-joining variation state.
agent:
readOnly: true
allOf:
- $ref: '#/components/schemas/ResourceMetadata'
description: Agent details (not snapshotted).
agentVariation:
readOnly: true
allOf:
- $ref: '#/components/schemas/ResourceMetadata'
description: Agent variation details (not snapshotted).
currentContextWindowId:
readOnly: true
example: objwin_01HXKD2E5NQM3T9AYWCFN7BSTR
type: string
description: >-
ID of the objective's current (most recent) context window. Hydrated
on
demand; empty when the objective has not yet produced a context window.
tenant:
readOnly: true
allOf:
- $ref: '#/components/schemas/TenantReference'
description: >-
The tenant this objective is associated with, when one was asserted
at
creation (directly or via a widget session).
subject:
readOnly: true
allOf:
- $ref: '#/components/schemas/SubjectReference'
description: |-
The subject (person within the tenant) this objective is associated
with, when one was asserted at creation.
widget:
readOnly: true
allOf:
- $ref: '#/components/schemas/BareMetadata'
description: |-
The widget this objective's conversation ran through, when it was
created via a widget session.
description: >-
ObjectiveInfo provides read-only aggregated statistics about an
objective's execution
Objective_Secret:
type: object
properties:
name:
type: string
MemoryReference:
required:
- memoryLayerId
type: object
properties:
memoryLayerId:
example: memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH
type: string
memoryEntryId:
example: mementry_01HXKD2E5NQM3T9AYWCF5E52Z0
type: string
description: >-
When set, inserts only this entry from memory_layer_id into the
cascade —
behaves as a single-entry layer (only this key resolves at this
position). The entry must belong to memory_layer_id; mismatches are
rejected with InvalidArgument.
description: |-
MemoryReference identifies a memory layer or a specific entry within
one, for composition into a memory cascade. Used on objectives (where
entry pinning is permitted).
memory_layer_id accepts both the canonical form (memlyr_…) and the
external-id form (external_id:my-custom-id). The same applies to
memory_entry_id when set.
ObjectiveEpisodicConfig:
required:
- key
type: object
properties:
key:
type: string
description: >-
The caller-supplied episodic key. Objectives created with the same
key
(for the same agent) share one episodic memory layer.
memoryLayerId:
readOnly: true
example: memlyr_01HXKD2E5NQM3T9AYWCFFFBMJH
type: string
description: |-
The episodic memory layer resolved (created or reused) for this
objective's key. Populated by the system at objective creation.
description: Episodic is used to configure the episodic memory for the objective
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.
Agent:
required:
- metadata
- spec
- state
type: object
properties:
metadata:
allOf:
- $ref: '#/components/schemas/ResourceMetadata'
description: Resource metadata
spec:
allOf:
- $ref: '#/components/schemas/AgentSpec'
description: Agent specification
info:
readOnly: true
allOf:
- $ref: '#/components/schemas/AgentInfo'
description: Agent information
state:
readOnly: true
enum:
- STATE_UNSPECIFIED
- STATE_DRAFT
- STATE_PUBLISHED
- STATE_ARCHIVED
type: string
description: >-
The current lifecycle state of the agent. Output only. Agents are
created
in STATE_DRAFT; use the :publish, :unpublish, :archive, and :unarchive
actions to transition between states.
format: enum
description: Agent resource
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
AgentSchedule:
required:
- metadata
- spec
- state
type: object
properties:
metadata:
$ref: '#/components/schemas/ResourceMetadata'
spec:
$ref: '#/components/schemas/AgentScheduleSpec'
info:
$ref: '#/components/schemas/AgentScheduleInfo'
state:
readOnly: true
enum:
- STATE_UNSPECIFIED
- STATE_ACTIVE
- STATE_PAUSED
- STATE_ARCHIVED
type: string
description: >-
The current lifecycle state of the schedule. Output only. Schedules
are
created STATE_ACTIVE; use the :pause, :resume, and :archive actions to
transition between states.
format: enum
description: |-
AgentSchedule resource — a recurring trigger attached to an agent that
creates objectives on its cadence.
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.
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)
TenantReference:
required:
- id
- externalId
type: object
properties:
id:
readOnly: true
example: tenant_01HXKD2E5NQM3T9AYWCF133E3Q
type: string
description: Cadenya's canonical tenant id.
externalId:
readOnly: true
example: acme-corp
type: string
description: The tenant identifier in the customer's namespace, as asserted.
name:
readOnly: true
example: Acme Corp
type: string
description: Human-readable name of the tenant, when one has been asserted.
description: >-
TenantReference is the read-only echo of a resource's tenant
association,
carrying both Cadenya's canonical id and the customer's own key.
SubjectReference:
required:
- id
- externalId
type: object
properties:
id:
readOnly: true
example: subj_01HXKD2E5NQM3T9AYWCFQAZGFV
type: string
description: Cadenya's canonical subject id.
externalId:
readOnly: true
example: customer-user-42
type: string
description: >-
The subject identifier in the customer's namespace, as asserted.
Unique
within the subject's tenant.
name:
readOnly: true
example: Jane Doe
type: string
description: Human-readable name of the subject, when one has been asserted.
description: >-
SubjectReference is the read-only echo of a resource's subject
association,
carrying both Cadenya's canonical id and the customer's own key.
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.
AgentSpec:
required:
- variationSelectionMode
type: object
properties:
description:
type: string
description: Description of the agent's purpose
webhookEventsUrl:
type: string
description: >-
The URL that Cadenya will send events for any objective assigned to
the agent.
variationSelectionMode:
enum:
- VARIATION_SELECTION_MODE_UNSPECIFIED
- VARIATION_SELECTION_MODE_RANDOM
- VARIATION_SELECTION_MODE_WEIGHTED
type: string
description: >-
Controls how variations are automatically selected when creating
objectives
Defaults to RANDOM when unspecified
format: enum
systemPromptDataSchema:
type: object
additionalProperties: true
description: >-
SystemPromptDataSchema enforces the shape of system_prompt_data when
objectives are created. This is valuable when using liquid
formatting in agent
variation system prompt templates. The schema is also used when the agent is attached as a sub-agent, as it becomes the tool's input parameter schema.
If omitted, the sub-agent schema will be loaded with a simple "prompt" free text string as its schema.
outputDefinition:
type: object
additionalProperties: true
description: |-
Optional output definition for objectives created for this agent.
When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here.
Use this option when you want structured data to be created by your objectives.
enableEpisodicMemory:
type: boolean
description: |-
Enable episodic memory for objectives created for this agent.
When true, objective creation requires an episodic_memory key and the
system finds or creates a memory layer for that (agent, key) pair, letting
the agent store and retrieve memories across objectives that share the key.
Memory is agent-level so all variations of the agent share the same layers.
episodicMemoryTtl:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: integer
description: |-
How long episodic memories should be retained.
Each new objective slides the layer's expiry forward by this duration, and
stored entries expire this long after they are written.
If not set, episodic memories are retained indefinitely.
description: Agent specification (user-provided configuration)
AgentInfo:
type: object
properties:
variationCount:
readOnly: true
type: integer
format: int32
createdBy:
$ref: '#/components/schemas/Profile'
description: >-
AgentInfo contains simple information about an agent for display or
quick reference
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
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
AgentScheduleSpec:
required:
- schedule
type: object
properties:
schedule:
allOf:
- $ref: '#/components/schemas/AgentScheduleSpec_Schedule'
description: When to fire. Required.
overlapPolicy:
enum:
- OVERLAP_POLICY_UNSPECIFIED
- OVERLAP_POLICY_ALLOW
- OVERLAP_POLICY_SKIP
type: string
description: >-
What to do when the previous run is still in flight. Defaults to
SKIP.
format: enum
firstUserMessage:
type: string
description: >-
Optional explicit first user message passed to CreateObjective on
each fire.
Becomes the first user message in the objective's chat history. When unset, the
fired objective defers to the selected variation's first_user_message_template.
variationId:
example: agentvar_01HXKD2E5NQM3T9AYWCF32BSPP
type: string
description: >-
Optional explicit variation. When unset, the agent's
variation_selection_mode
chooses per fire.
systemPromptData:
type: object
description: >-
Optional data rendered into the variation's system_prompt_template
when each
fired objective is created. If the agent has a system_prompt_data_schema,
this must satisfy it.
x-stainless-any: true
firstUserMessageData:
type: object
description: >-
Optional data rendered into the variation's
first_user_message_template when
each fired objective is created. Separate from `system_prompt_data`, which
renders the system prompt template.
x-stainless-any: true
description: AgentScheduleSpec is the user-provided configuration for a schedule.
AgentScheduleInfo:
type: object
properties:
nextFireAt:
readOnly: true
type: string
description: >-
When the schedule will next fire. Computed from the spec; absent
when
the schedule is STATE_PAUSED/STATE_ARCHIVED or has no future fire times.
format: date-time
lastFireAt:
readOnly: true
type: string
description: When the schedule last fired (regardless of objective outcome).
format: date-time
lastObjectiveId:
readOnly: true
example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV
type: string
description: ID of the most recent objective the schedule created.
lastSkippedAt:
readOnly: true
type: string
description: >-
When the schedule most recently skipped a fire (SKIP policy + prior
in flight).
format: date-time
lastSkipReason:
readOnly: true
type: string
description: >-
Reason for the most recent skip (e.g. "previous objective still
running").
totalFires:
readOnly: true
type: integer
description: Lifetime count of objectives created by this schedule.
format: int32
createdBy:
$ref: '#/components/schemas/Profile'
description: AgentScheduleInfo provides read-only runtime data about a schedule.
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.
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.
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.
AgentScheduleSpec_Schedule:
type: object
properties:
calendars:
type: array
items:
$ref: '#/components/schemas/Schedule_Calendar'
description: Wall-clock rules. May be empty if `intervals` is non-empty.
intervals:
type: array
items:
$ref: '#/components/schemas/Schedule_Interval'
description: Duration-based rules. May be empty if `calendars` is non-empty.
timezone:
type: string
description: >-
IANA tz name (e.g. "America/New_York"). Required. Applies to
calendars;
intervals fire on wall-clock cadence anchored in this zone.
description: >-
Schedule defines WHEN the schedule fires. Temporal-style structured
form:
a list of calendar rules (wall-clock) and/or interval rules (duration),
OR'd together. At least one rule is required.
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.
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
Schedule_Calendar:
type: object
properties:
second:
type: array
items:
$ref: '#/components/schemas/Schedule_Range'
minute:
type: array
items:
$ref: '#/components/schemas/Schedule_Range'
hour:
type: array
items:
$ref: '#/components/schemas/Schedule_Range'
dayOfMonth:
type: array
items:
$ref: '#/components/schemas/Schedule_Range'
month:
type: array
items:
$ref: '#/components/schemas/Schedule_Range'
dayOfWeek:
type: array
items:
$ref: '#/components/schemas/Schedule_Range'
comment:
type: string
description: |-
Calendar is a wall-clock rule. Empty field-list semantics:
- second/minute/hour: empty means [{start: 0}] (top of the unit)
- day_of_month/month/day_of_week: empty means "any value"
Fire times = cartesian product across all fields.
Schedule_Interval:
type: object
properties:
every:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
offset:
pattern: ^-?(?:0|[1-9][0-9]{0,11})(?:\.[0-9]{1,9})?s$
type: string
description: Phase shift within `every`. Must be < `every` (enforced at runtime).
description: |-
Interval is a duration-based rule. Fires every `every` from a stable
anchor (workspace epoch), optionally phase-shifted by `offset`.
Schedule_Range:
type: object
properties:
start:
type: integer
format: int32
end:
type: integer
format: int32
step:
type: integer
format: int32
description: |-
Inclusive numeric range with optional step.
{start: 9} → 9
{start: 9, end: 17} → 9..17
{start: 0, end: 59, step: 15} → 0,15,30,45
`end` defaults to `start`; `step` defaults to 1.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````