Skip to main content
POST

Authorizations

​
Authorization
string
header
required

OAuth 2.0 / OIDC bearer token.

​
Tenant-Name
string
header
required

The tenant the request operates within.

Path Parameters

​
contextId
string<context-id>
required

Context identifier (prefixed UUIDv7). Context identifier. Accepts ctx.<uuidv7> or a bare UUIDv7 on input; always returned prefixed.

Pattern: ^(ctx\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Example:

"ctx.0192f4c8-3d6b-7c4f-a02b-4d9e7f3c8b51"

​
taskId
string<task-id>
required

Task identifier (prefixed UUIDv7). Task identifier. Accepts task.<uuidv7> or a bare UUIDv7 on input; always returned prefixed.

Pattern: ^(task\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Example:

"task.0192f4c8-4e7c-7d50-b13c-5eaf8a4d9c62"

Body

application/json

The feedback to submit.

Request body for submitting task feedback.

​
rating
object
required

The original rating supplied by the customer.

Example:
​
labels
enum<string>[]

Structured observations about the result. Defaults to an empty array. Positive and negative labels may be combined. Duplicate labels are rejected. A maximum of five labels may be submitted.

Maximum array length: 5

Structured observation about the result. Positive and negative labels share one taxonomy so customers can represent mixed feedback.

  • correct — factually and contextually correct (positive).
  • complete — included the important expected information (positive).
  • helpful — materially helped the user complete their task (positive).
  • wellPresented — clear, readable, appropriately structured (positive).
  • efficient — reached a useful result without unnecessary content (positive).
  • incorrect — one or more claims, conclusions, or actions were wrong (negative).
  • missingInformation — important or expected information was omitted (negative).
  • irrelevant — included content that did not address the request (negative).
  • misunderstoodRequest — the system responded to the wrong intent (negative).
  • unsupportedClaim — a claim not supported by available information (negative).
  • unsafeOrInappropriate — unsafe, disallowed, or unsuitable (negative).
  • poorlyPresented — difficult to read or unsuitably structured (negative).
  • tooVerbose — substantially more detail than useful (negative).
  • other — another observation described in reason (both).
Available options:
correct,
complete,
helpful,
wellPresented,
efficient,
incorrect,
missingInformation,
irrelevant,
misunderstoodRequest,
unsupportedClaim,
unsafeOrInappropriate,
poorlyPresented,
tooVerbose,
other
​
reason
string

The user's explanation of the rating or labels. Required when labels contains other.

Maximum string length: 1000
Examples:

"The response stated the patient had diabetes"

"but this was not present in the available data."

​
target
object

Identifies the specific user-visible response being evaluated. If omitted, the feedback applies to the task as a whole.

​
metadata
object

Customer-provided provenance and correlation information.

Response

Feedback created.

A stored feedback resource.

​
id
string<feedback-id>
required

Feedback identifier. Accepts fb.<uuidv7> or a bare UUIDv7 on input; always returned prefixed.

Pattern: ^(fb\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Example:

"fb.0192f4c8-7e2a-7b3c-9d4e-5f6a7b8c9d01"

​
taskId
string<task-id>
required

Task identifier. Accepts task.<uuidv7> or a bare UUIDv7 on input; always returned prefixed.

Pattern: ^(task\.)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
Example:

"task.0192f4c8-4e7c-7d50-b13c-5eaf8a4d9c62"

​
rating
object
required

The original rating supplied by the customer.

Example:
​
normalizedScore
number<double>
required

Corti-derived internal score between 0 and 1. The original scale and value are always retained alongside this score.

Required range: 0 <= x <= 1
Example:

1

​
labels
enum<string>[]
required

Structured observations about the result.

Structured observation about the result. Positive and negative labels share one taxonomy so customers can represent mixed feedback.

  • correct — factually and contextually correct (positive).
  • complete — included the important expected information (positive).
  • helpful — materially helped the user complete their task (positive).
  • wellPresented — clear, readable, appropriately structured (positive).
  • efficient — reached a useful result without unnecessary content (positive).
  • incorrect — one or more claims, conclusions, or actions were wrong (negative).
  • missingInformation — important or expected information was omitted (negative).
  • irrelevant — included content that did not address the request (negative).
  • misunderstoodRequest — the system responded to the wrong intent (negative).
  • unsupportedClaim — a claim not supported by available information (negative).
  • unsafeOrInappropriate — unsafe, disallowed, or unsuitable (negative).
  • poorlyPresented — difficult to read or unsuitably structured (negative).
  • tooVerbose — substantially more detail than useful (negative).
  • other — another observation described in reason (both).
Available options:
correct,
complete,
helpful,
wellPresented,
efficient,
incorrect,
missingInformation,
irrelevant,
misunderstoodRequest,
unsupportedClaim,
unsafeOrInappropriate,
poorlyPresented,
tooVerbose,
other
Example:
​
createdAt
string<date-time>
required
read-only

When the feedback was created.

Example:

"2026-05-19T12:00:00Z"

​
reason
string

Free-text explanation of the rating or labels.

Maximum string length: 1000
Examples:

"The response stated the patient had diabetes"

"but this was not present in the available data."

​
target
object

Identifies the specific user-visible response being evaluated. If omitted, the feedback applies to the task as a whole.

​
metadata
object

Customer-provided provenance and correlation information.