> ## 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.
# Submit feedback for an objective
> Score a finished objective from -1.0 to 1.0. Under Feedback Driven selection, that score teaches the agent which variation to reach for next.
Feedback closes the loop. Score an objective and, if its agent uses `VARIATION_SELECTION_MODE_WEIGHTED`, the [variation](/docs/guides/sdk/agents#add-candidates-and-control-selection) that ran it becomes more or less likely to run the next one. No retraining, no redeploy. This is the endpoint behind that.
`metadata` and `data` are both required. An empty `metadata` object is fine.
```typescript TypeScript theme={null}
await client.objectives.feedback.create(objectiveId, {
workspaceId,
metadata: {},
data: { score: 1.0, comment: 'Short and on point.' },
});
```
```go Go theme={null}
_, err := client.Objectives.Feedback.New(ctx, objectiveID,
cadenya.ObjectiveFeedbackNewParams{
WorkspaceID: cadenya.String(workspaceID),
Metadata: shared.CreateOperationMetadataParam{},
Data: cadenya.ObjectiveFeedbackDataParam{
Score: cadenya.Float(1.0),
Comment: cadenya.String("Short and on point."),
},
})
```
```ruby Ruby theme={null}
cadenya.objectives.feedback.create(
objective_id,
workspace_id: workspace_id,
metadata: {},
data: {score: 1.0, comment: "Short and on point."}
)
```
```bash cURL theme={null}
curl -X POST "https://api.cadenya.com/v1/workspaces/${WORKSPACE_ID}/objectives/${OBJECTIVE_ID}/feedback" \
-H "Authorization: Bearer ${CADENYA_API_KEY}" \
-H "Content-Type: application/json" \
-d '{ "metadata": {}, "data": { "score": 1.0, "comment": "Short and on point." } }'
```
Unlike most of the API, this endpoint validates strictly. Omit `metadata` and you get a `400`. Send a score outside `[-1.0, 1.0]` and you get a `400`.
## Score is evidence, not a rating
A score is a number from `-1.0` to `1.0`. Think of it as a vote on whether this variation should run again, not as a star rating you are averaging for a dashboard.
| Score | Meaning |
| ------ | --------------------------- |
| `1.0` | The best possible outcome. |
| `0.0` | Neutral. |
| `-1.0` | The worst possible outcome. |
A score of `0.0` is neutral evidence. It adds `0.5` to both sides of the variation's Beta posterior, pulling its mean toward `0.5` without favoring success or failure. Omitting `score` defaults to this neutral update.
## Feedback appends
Every submission inserts a new record. There is no upsert, and nothing stops you from scoring the same objective twice.
```typescript theme={null}
await client.objectives.feedback.create(objectiveId, {
workspaceId, metadata: {}, data: { score: 1.0, comment: 'Great.' },
});
await client.objectives.feedback.create(objectiveId, {
workspaceId, metadata: {}, data: { score: -0.5, comment: 'Second reviewer disagrees.' },
});
const all = await client.objectives.feedback.list(objectiveId, { workspaceId });
// Two records. Both moved the variation's odds.
```
That is a feature when several reviewers weigh in, and a bug when your retry logic fires twice. Each submission compounds into selection, so make the call idempotent on your side, or set `metadata.externalId` to your own review ID and check before you resubmit.
## How a score moves the odds
Weighted selection is Thompson Sampling over a Beta distribution. Each variation carries two numbers, both starting at `1.0`, which together describe how good Cadenya currently believes that variation is.
* A **positive** score adds its magnitude to the variation's success count.
* A **negative** score adds its magnitude to the failure count.
* A **zero** score adds `0.5` to both counts.
To pick a variation, Cadenya draws one random sample from each variation's distribution and runs the highest draw. A variation with a strong record usually draws high; one with a weak record usually draws low, but not always, so it keeps earning occasional chances to prove itself. That is the exploration you want: the agent commits to the winner without ever shutting out a contender.
With no feedback, every variation holds an identical uniform distribution, so early runs spread evenly.
You can watch the belief update. Score one objective `+1.0`, another `-0.5`, and a third `0.0`, then read the variation:
```typescript theme={null}
const variation = await client.agents.variations.retrieve(
agentId,
variationId,
{ workspaceId },
);
console.log(variation.info?.score); // 0.5555555
console.log(variation.info?.feedbackCount); // 3
```
`info.score` is the variation's current believed quality, and it runs from `0.0` to `1.0`, **not** from `-1.0` to `1.0`. A brand new variation reads `0.5`. Here the posterior is `Beta(2.5, 2.0)`, so the score reads about `0.556`. The neutral submission contributed `0.5` to both sides, and `feedbackCount` counted all three records.
Two different numbers get called "score". The one on a feedback record is your raw `-1.0` to `1.0` vote. The one on `variation.info` is the agent's belief, `0.0` to `1.0`. Analytics charts average the former.
## Read feedback back
Two views. Per objective, and across an agent.
```typescript theme={null}
// Everything submitted for one objective.
const forObjective = await client.objectives.feedback.list(objectiveId, { workspaceId });
// Everything submitted across every objective this agent has run.
const forAgent = await client.agents.feedback.list(agentId, {
workspaceId,
sentiment: 'FEEDBACK_SENTIMENT_NEGATIVE',
includeInfo: true,
});
for await (const record of forAgent) {
console.log(record.data.score, record.info?.agentVariation?.name);
}
```
The agent-level list is the interesting one, because it is where you find out *which variation* earned a score. Pass `includeInfo: true` and each record carries its `objective` and `agentVariation`. Without it you get `submittedBy` and nothing else, which tells you who complained but not about what.
It also takes real filters, and they work: `sentiment`, `agentVariationId`, `query` (a case-insensitive substring search over comments), `createdAfter`, `createdBefore`, and `labels`.
`FEEDBACK_SENTIMENT_POSITIVE` matches scores above zero and `FEEDBACK_SENTIMENT_NEGATIVE` matches scores below it. A `0.0` score matches neither, so neutral feedback disappears from both views. Use `FEEDBACK_SENTIMENT_UNSPECIFIED`, or omit the filter, to see everything.
The per-objective list is thinner: it takes only `cursor`, `limit`, and `labels`, with no `includeInfo`.
## Put it to work
Score from the place that knows whether the agent succeeded, which is rarely the place that started the objective. A support agent's real signal is whether the ticket reopened. A code agent's is whether the pull request merged.
```typescript theme={null}
// A day later, when you know how it went.
await client.objectives.feedback.create('external_id:ticket-4521', {
workspaceId,
metadata: { externalId: 'review-4521', labels: { source: 'csat' } },
data: {
score: ticket.reopened ? -0.8 : 0.9,
comment: ticket.reopened ? 'Customer came back within 24h.' : 'Resolved first contact.',
},
});
```
Set `metadata.externalId` on the objective and you never have to store the `obj_` ID to score it later. Labels ride along, so you can slice feedback by source and separate a human reviewer's judgment from an automated signal.
## Related
Two variations, live feedback, and selection shifting toward the winner.
The lifecycle in code, including how selection mode is set.
Pin a variation to smoke-test it before it takes live traffic.
Score an objective by your ticket number, months later.
## OpenAPI
````yaml post /v1/workspaces/{workspaceId}/objectives/{objectiveId}/feedback
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/{objectiveId}/feedback:
post:
tags:
- ObjectiveService
- Objectives
summary: Submit feedback for an objective
description: >-
Submits feedback for an objective's execution. Feedback scores are used
by the agent variation scoring system to evaluate and rank variation
performance.
operationId: ObjectiveService_CreateObjectiveFeedback
parameters:
- name: workspaceId
in: path
required: true
schema:
type: string
example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
- name: objectiveId
in: path
description: >-
The ID of the objective. Supports "external_id:" prefix for external
IDs.
required: true
schema:
example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateObjectiveFeedbackRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ObjectiveFeedback'
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 objectiveFeedback = await client.objectives.feedback.create(
'obj_01HXKD2E5NQM3T9AYWCFQAZGFV',
{
workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
data: {},
metadata: {},
},
);
console.log(objectiveFeedback.data);
- 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_feedback = client.objectives.feedback.create(
objective_id="obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
workspace_id="workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
data={},
metadata={},
)
print(objective_feedback.data)
- 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\t\"go.cadenya.com/cadenya-go/shared\"\n)\n\nfunc main() {\n\tclient := cadenya.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tobjectiveFeedback, err := client.Objectives.Feedback.New(\n\t\tcontext.TODO(),\n\t\t\"obj_01HXKD2E5NQM3T9AYWCFQAZGFV\",\n\t\tcadenya.ObjectiveFeedbackNewParams{\n\t\t\tWorkspaceID: cadenya.String(\"workspace_01HXKD2E5NQM3T9AYWCF133E3Q\"),\n\t\t\tData: cadenya.ObjectiveFeedbackDataParam{},\n\t\t\tMetadata: shared.CreateOperationMetadataParam{},\n\t\t},\n\t)\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", objectiveFeedback.Data)\n}\n"
- lang: Ruby
source: |-
require "cadenya"
cadenya = Cadenya::Client.new(api_key: "My API Key")
objective_feedback = cadenya.objectives.feedback.create(
"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
workspace_id: "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
data: {},
metadata: {}
)
puts(objective_feedback)
- lang: CLI
source: |-
cadenya objectives:feedback create \
--api-key 'My API Key' \
--workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
--objective-id obj_01HXKD2E5NQM3T9AYWCFQAZGFV \
--data '{}' \
--metadata '{}'
components:
schemas:
CreateObjectiveFeedbackRequest:
required:
- metadata
- data
type: object
properties:
workspaceId:
readOnly: true
example: workspace_01HXKD2E5NQM3T9AYWCF133E3Q
type: string
objectiveId:
readOnly: true
example: obj_01HXKD2E5NQM3T9AYWCFQAZGFV
type: string
description: >-
The ID of the objective. Supports "external_id:" prefix for external
IDs.
metadata:
$ref: '#/components/schemas/CreateOperationMetadata'
data:
$ref: '#/components/schemas/ObjectiveFeedbackData'
description: Request to submit feedback for an objective
ObjectiveFeedback:
required:
- metadata
- data
type: object
properties:
metadata:
$ref: '#/components/schemas/OperationMetadata'
data:
$ref: '#/components/schemas/ObjectiveFeedbackData'
info:
$ref: '#/components/schemas/ObjectiveFeedbackInfo'
description: >-
ObjectiveFeedback represents feedback submitted for an objective's
execution.
Feedback is used to score agent variations and improve agent performance over time.
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).
CreateOperationMetadata:
type: object
properties:
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"}
externalId:
type: string
description: >-
External ID for the operation (e.g., a workflow ID from an external
system)
description: |-
CreateOperationMetadata contains the user-provided fields for creating
an operation. Read-only fields (id, account_id, workspace_id, created_at, profile_id)
are excluded since they are set by the server.
ObjectiveFeedbackData:
type: object
properties:
score:
type: number
description: >-
A score between -1.0 and 1.0 representing the quality of the
objective's execution.
-1.0 is the worst possible score, 0.0 is neutral, and 1.0 is the best.
format: float
comment:
type: string
description: Optional human-readable comment explaining the feedback
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)
ObjectiveFeedbackInfo:
type: object
properties:
submittedBy:
readOnly: true
allOf:
- $ref: '#/components/schemas/Profile'
description: The profile that submitted the feedback
objective:
readOnly: true
allOf:
- $ref: '#/components/schemas/BareMetadata'
description: The objective the feedback was submitted for.
agentVariation:
readOnly: true
allOf:
- $ref: '#/components/schemas/BareMetadata'
description: >-
The agent variation that executed the objective this feedback is
about.
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.
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.
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.
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.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````