Submit feedback for an objective

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const objectiveFeedback = await client.objectives.feedback.create(
  'obj_01HXKD2E5NQM3T9AYWCFQAZGFV',
  {
    workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
    data: {},
    metadata: {},
  },
);

console.log(objectiveFeedback.data);

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)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
	"go.cadenya.com/cadenya-go/shared"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	objectiveFeedback, err := client.Objectives.Feedback.New(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		cadenya.ObjectiveFeedbackNewParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
			Data:        cadenya.ObjectiveFeedbackDataParam{},
			Metadata:    shared.CreateOperationMetadataParam{},
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", objectiveFeedback.Data)
}

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)

cadenya objectives:feedback create \
  --api-key 'My API Key' \
  --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
  --objective-id obj_01HXKD2E5NQM3T9AYWCFQAZGFV \
  --data '{}' \
  --metadata '{}'

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}/feedback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {
    "labels": {},
    "externalId": "<string>"
  },
  "data": {
    "score": 123,
    "comment": "<string>"
  }
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}/feedback",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'metadata' => [
        'labels' => [
                
        ],
        'externalId' => '<string>'
    ],
    'data' => [
        'score' => 123,
        'comment' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

HttpResponse<String> response = Unirest.post("https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}/feedback")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {\n    \"labels\": {},\n    \"externalId\": \"<string>\"\n  },\n  \"data\": {\n    \"score\": 123,\n    \"comment\": \"<string>\"\n  }\n}")
  .asString();

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    "createdAt": "2023-11-07T05:31:56Z",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
    "labels": {},
    "externalId": "<string>"
  },
  "data": {
    "score": 123,
    "comment": "<string>"
  },
  "info": {
    "submittedBy": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "externalId": "<string>",
        "labels": {},
        "createdAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "email": "<string>",
        "name": "<string>"
      }
    },
    "objective": {
      "id": "<string>",
      "name": "<string>"
    },
    "agentVariation": {
      "id": "<string>",
      "name": "<string>"
    }
  }
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

POST

workspaces

{workspaceId}

objectives

{objectiveId}

feedback

JavaScript

import Cadenya from '@cadenya/cadenya';

const client = new Cadenya({
  apiKey: process.env['CADENYA_API_KEY'], // This is the default and can be omitted
});

const objectiveFeedback = await client.objectives.feedback.create(
  'obj_01HXKD2E5NQM3T9AYWCFQAZGFV',
  {
    workspaceId: 'workspace_01HXKD2E5NQM3T9AYWCF133E3Q',
    data: {},
    metadata: {},
  },
);

console.log(objectiveFeedback.data);

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)

package main

import (
	"context"
	"fmt"
	"go.cadenya.com/cadenya-go"
	"go.cadenya.com/cadenya-go/option"
	"go.cadenya.com/cadenya-go/shared"
)

func main() {
	client := cadenya.NewClient(
		option.WithAPIKey("My API Key"),
	)
	objectiveFeedback, err := client.Objectives.Feedback.New(
		context.TODO(),
		"obj_01HXKD2E5NQM3T9AYWCFQAZGFV",
		cadenya.ObjectiveFeedbackNewParams{
			WorkspaceID: cadenya.String("workspace_01HXKD2E5NQM3T9AYWCF133E3Q"),
			Data:        cadenya.ObjectiveFeedbackDataParam{},
			Metadata:    shared.CreateOperationMetadataParam{},
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", objectiveFeedback.Data)
}

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)

cadenya objectives:feedback create \
  --api-key 'My API Key' \
  --workspace-id workspace_01HXKD2E5NQM3T9AYWCF133E3Q \
  --objective-id obj_01HXKD2E5NQM3T9AYWCFQAZGFV \
  --data '{}' \
  --metadata '{}'

curl --request POST \
  --url https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}/feedback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "metadata": {
    "labels": {},
    "externalId": "<string>"
  },
  "data": {
    "score": 123,
    "comment": "<string>"
  }
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}/feedback",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'metadata' => [
        'labels' => [
                
        ],
        'externalId' => '<string>'
    ],
    'data' => [
        'score' => 123,
        'comment' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

HttpResponse<String> response = Unirest.post("https://api.cadenya.com/v1/workspaces/{workspaceId}/objectives/{objectiveId}/feedback")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"metadata\": {\n    \"labels\": {},\n    \"externalId\": \"<string>\"\n  },\n  \"data\": {\n    \"score\": 123,\n    \"comment\": \"<string>\"\n  }\n}")
  .asString();

{
  "metadata": {
    "id": "<string>",
    "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
    "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
    "createdAt": "2023-11-07T05:31:56Z",
    "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
    "labels": {},
    "externalId": "<string>"
  },
  "data": {
    "score": 123,
    "comment": "<string>"
  },
  "info": {
    "submittedBy": {
      "metadata": {
        "id": "<string>",
        "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
        "name": "<string>",
        "profileId": "profile_01HXKD2E5NQM3T9AYWCFS0AP08",
        "externalId": "<string>",
        "labels": {},
        "createdAt": "2023-11-07T05:31:56Z"
      },
      "spec": {
        "email": "<string>",
        "name": "<string>"
      }
    },
    "objective": {
      "id": "<string>",
      "name": "<string>"
    },
    "agentVariation": {
      "id": "<string>",
      "name": "<string>"
    }
  }
}

{
  "code": 123,
  "message": "<string>",
  "details": [
    {
      "@type": "<string>"
    }
  ]
}

Feedback closes the loop. Score an objective and, if its agent uses VARIATION_SELECTION_MODE_WEIGHTED, the variation 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.

await client.objectives.feedback.create(objectiveId, {
  workspaceId,
  metadata: {},
  data: { score: 1.0, comment: 'Short and on point.' },
});

_, 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."),
		},
	})

cadenya.objectives.feedback.create(
  objective_id,
  workspace_id: workspace_id,
  metadata: {},
  data: {score: 1.0, comment: "Short and on point."}
)

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.

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:

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.

// 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.

// 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.

Build an agent that improves

Two variations, live feedback, and selection shifting toward the winner.

Agents and variations

The lifecycle in code, including how selection mode is set.

Create an objective

Pin a variation to smoke-test it before it takes live traffic.

Use your own IDs

Score an objective by your ticket number, months later.

Authorizations

Authorization

string

header

required

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

Path Parameters

workspaceId

string

required

Example:

"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"

objectiveId

string

required

The ID of the objective. Supports "external_id:" prefix for external IDs.

Example:

"obj_01HXKD2E5NQM3T9AYWCFQAZGFV"

Body

application/json

Request to submit feedback for an objective

metadata

object

required

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.

Show child attributes

data

object

required

Show child attributes

Response

ObjectiveFeedback represents feedback submitted for an objective's execution. Feedback is used to score agent variations and improve agent performance over time.

metadata

object

required

Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

Show child attributes

data

object

required

Show child attributes

info

object

Show child attributes

​Score is evidence, not a rating

​Feedback appends

​How a score moves the odds

​Read feedback back

​Put it to work

​Related

Build an agent that improves

Agents and variations

Create an objective

Use your own IDs

Authorizations

Path Parameters

Body

Response

Score is evidence, not a rating

Feedback appends

How a score moves the odds

Read feedback back

Put it to work

Related