AI feedback
Thumbs up or down on Ken's output: one rating per person per output, with reason chips and an optional note that can earn the workspace credits. Served only when Ken-Version: 1.1, and dark behind the ai_feedback workspace flag (404 while it is off). Any workspace member, Client seats included (they rate and never earn).
Path parameters
The endpoints whose path names one of these take it as described here. An endpoint's own table lists a path parameter only when it describes it differently.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
feedbackId | path | integer (int64) | required |
Headers
The endpoints on this page take these headers. Each endpoint's curl shows the ones it sends.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Ken-Version | header | string, one of: 2026-11-02, 1.1 | optional | The API version, a date in YYYY-MM-DD form. 1.1 is another name for the first dated version. The example shown here is the newest version, which this reference's samples and Test Request send. Leave it out to use your API key's pinned version. Keys created in the Kenso app are pinned to the newest version; keys minted by the CLI login are not. A key with no pinned version and no header gets the legacy shape where the path has one, and 404 where the path exists only in this version. A date that is not a version answers 400 unsupported_version; any other value that is not a version is treated as legacy. |
X-Ken-Workspace-Id | header | integer (int64) | optional | The id of the workspace to act in. Leave it out when your API key reaches only one workspace. When the key reaches more than one, a request without this header answers 400 workspace_required. A workspace you are not a member of answers 404 not_found. |
List the caller's own ratings of some outputs
/v1/ai-feedbackai-feedback.list- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
ai_feedback feature on your workspace. Until it is on, calls answer 404.The caller's rating of each listed output on one surface, so the app shows the thumb a person picked after a reload. Query: surface (one surface key, required) and targetRef (an output's id on that surface, repeated: 1 to 100 values, repeats allowed). Each targetRef is looked up by its canonical spelling, the one the save stores (a number without a sign or leading zeros, a time in UTC round-trip O form, a hash in lower case), so wf_step:2026-11-04T12:00:00Z:7:9 finds the rating saved as wf_step:2026-11-04T12:00:00.0000000Z:7:9, and each item's targetRef is that stored spelling. At most one item per output; an output the caller has not rated is absent. Another person's rating, another workspace's, a cleared rating and an implicit signal never appear. One page: pagination.hasMore is false and there is no cursor. A missing or unknown surface is 400 on surface; no targetRef, more than 100, or one that does not fit the surface is 400 on targetRef. A read that fails is 503 service_unavailable: retry it. A credential with no member behind it is 403 forbidden, and a Network member seat is 403 permission_denied.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
surface | query | string | optional | |
targetRef | query | array of string | optional | |
limit | query | integer (int32) | optional | Items per page, from 1 to 200. Omit limit and cursor to get every item in one response, as before; with only cursor, 50 per page. |
cursor | query | string | optional | The nextCursor of the previous page. Omit it for the first page. |
curl -X GET "https://api.ken.so/v1/ai-feedback?limit=1" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a list of AiFeedback. Each item has these fields. The response also carries pagination.
Show the 8 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Rate an AI output
/v1/ai-feedbackai-feedback.create- Permission
- Any workspace member except a Network member
- Rate limit
- 60 requests a minute and 2,000 a day per user
ai_feedback feature on your workspace. Until it is on, calls answer 404.Saves the caller's thumbs on one output, or updates their rating of it: 201 for a new rating with a Location, 200 for an update. Body: surface (a surface key such as ken_chat, reply_draft, ai_line), targetRef (the output's id on that surface, such as ken_chat:12:turn_3:ken), rating (up or down), reasons (chip keys), note (optional, at most 4,000 characters: a longer one is 400 on note and nothing is saved), outputSnapshot (what the person saw, cut to 16,000 characters), traceId and context (campaignId, contactId, threadId). An unknown surface, a targetRef that does not fit it or another rating is 400 naming the field. The save never looks the output up and never waits for the reward check: reward.status is pending while the note is checked (poll GET /v1/ai-feedback/{feedbackId}), none when rewards do not apply to the caller. A note earns 10 credits at 8 words and 50 at 40 on a thumbs down (a thumbs up caps at 10), once per person per output. Changing the note or reasons updates the same rating and never pays twice. Accepts Idempotency-Key. 60 writes a minute and 2,000 a day per person: past either, 429 quota_exceeded with Retry-After. A rating is a person's: a credential with no member behind it is 403 forbidden, and a Network member seat is 403 permission_denied.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | optional | A unique value, such as a UUID, that makes a retry safe. Send the same key when you retry. For 24 hours, a repeat of the same request with the same key gets the first response again, with the Idempotent-Replayed: true header, and Kenso does not run the action twice. The same key with a different request answers 422 idempotency_key_reused. Keys are per workspace and at most 200 characters long. A repeat sent while the first request is still running can get 503 service_unavailable with Retry-After. Retry it with the same key. Kenso does not store a 5xx response, so a retry after one runs the action again. |
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
surface | string | optional | Where the output shows, a surface key such as ken_chat, reply_draft or ai_line. |
targetRef | string | optional | The output's id on that surface, such as ken_chat:12:turn_3:ken or reply_job:881. |
rating | string | optional | up or down. |
reasons | array of string | optional | Reason chip keys (snake_case), such as wrong_or_made_up. At most 12 are kept. |
note | string | optional | The person's note, at most 4,000 characters (a longer one is refused, never cut). |
outputSnapshot | string | optional | What the person saw (text, or an asset URL), cut to 16,000 characters. |
traceId | string | optional | The Langfuse / OTLP trace id of the run that produced the output, when the surface has one. |
context | SaveAiFeedbackContext | optional | Optional context of a rating, for filtering. |
curl -X POST "https://api.ken.so/v1/ai-feedback" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"surface": "ken_chat",
"targetRef": "ken_chat:12:turn_3:ken",
"rating": "up",
"reasons": [
"wrong_or_made_up"
],
"note": "string",
"outputSnapshot": "string",
"traceId": "string",
"context": {
"campaignId": 812,
"contactId": 812,
"threadId": "thr_ZW1haWw6NDAyMjg0LjFAZXhhbXBsZS5jb20"
}
}'Response 201
Also answers 200. data is a AiFeedback.
Show the 8 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Get one of the caller's ratings
/v1/ai-feedback/{feedbackId}ai-feedback.get- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
ai_feedback feature on your workspace. Until it is on, calls answer 404.The caller's own rating and its reward, for the poll after Send (every 1.5 s for up to 15 s). Another person's rating, another workspace's, a cleared rating or an unknown id is 404. A read that fails is 503 service_unavailable: retry it. A credential with no member behind it is 403 forbidden, and a Network member seat is 403 permission_denied.
curl -X GET "https://api.ken.so/v1/ai-feedback/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 200
data is a AiFeedback.
Show the 8 response fields and an example
The fields and an example are also on this endpoint's Markdown page.
Clear one of the caller's ratings
/v1/ai-feedback/{feedbackId}ai-feedback.delete- Permission
- Any workspace member except a Network member
- Rate limit
- 12,000 requests a minute per API key
ai_feedback feature on your workspace. Until it is on, calls answer 404.Removes the caller's thumbs from the output (204). A reward already granted or held on it stays, and a new rating of the same output earns nothing more. Another person's rating, another workspace's or an unknown id is 404; clearing a cleared rating again is 204. A credential with no member behind it is 403 forbidden, and a Network member seat is 403 permission_denied.
curl -X DELETE "https://api.ken.so/v1/ai-feedback/812" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID"Response 204
HTTP/1.1 204 No ContentRecord that the caller regenerated a Ken draft or suggestion
/v1/ai-feedback/signalsai-feedback.signal- Permission
- Any workspace member except a Network member
- Rate limit
- 60 requests a minute and 2,000 a day per user
ai_feedback feature on your workspace. Until it is on, calls answer 404.The one implicit signal only the client sees: Rewrite on a Ken reply draft or composer suggestion. Body: surface (reply_draft or reply_suggest), targetRef (the draft's or suggestion's id, such as reply_job:881 or reply_suggest:sug_12) and signal (regenerated). Recorded as a thumbs down that earns nothing (204); a repeat on the same output updates the one record. Anything else is 400 naming the field. Shares the rating write limit. A credential with no member behind it is 403 forbidden, and a Network member seat is 403 permission_denied.
Request body
application/json, optional.
| Field | Type | Required | Description |
|---|---|---|---|
surface | string | optional | reply_draft or reply_suggest. |
targetRef | string | optional | The draft's or suggestion's id, such as reply_job:881 or reply_suggest:sug_12. |
signal | string | optional | regenerated. |
curl -X POST "https://api.ken.so/v1/ai-feedback/signals" \
-H "Authorization: Bearer $KENSO_API_KEY" \
-H "Ken-Version: 2026-11-02" \
-H "X-Ken-Workspace-Id: $KENSO_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"surface": "reply_draft",
"targetRef": "reply_job:881",
"signal": "string"
}'Response 204
HTTP/1.1 204 No ContentMore in AI:AI runsAI linesAI line holdsAutonomous repliesAgent work settingsAgent permissionsAgent workAgent sandbox connectionsAgent sandbox runsAgent sandbox automatic runsAll resources