Skip to main content
POST
Annotate a conversation turn

Authorizations

Authorization
string
header
required

Send the key as Authorization: Bearer <key>. Two kinds of key exist.

Organization keys are issued in the portal (Settings, then API keys), each bound to one environment, shaped nx_<environment slug>_<64 hex>. They carry no capabilities and pass every capability check, with one exception: routes under /api/v1/records, /api/v1/engines/{id}/opportunities, /api/v1/graph and /api/v1/catalog/documents accept an organization key only when its environment is live, and refuse any other with 403 scoped_key_required. Revocation takes effect within 60 seconds.

Scoped keys are issued by Nexio on request, shaped nxsk_v1_<24 hex key id>_<43 character secret>. Each is bound to one org, one environment, a set of engines and a set of capabilities. A malformed, unknown or revoked nxsk_ key fails with 401 and is never retried as an organization key. Revocation takes effect on the next request. A scoped key without a route's capability gets 403 insufficient_capability; a scoped key not bound to the engine gets 403 engine_binding_forbidden.

Key-grantable capabilities: engines:read, runs:write, runs:read, runs:defensibility:read, runs:test, catalog:read, catalog:documents:read, webhooks:manage, conversations:use, conversations:export, records:read, records:opportunities:run, actions:write, actions:read, graph:read, records:analyze.

Routes that accept organization keys only (every scoped key gets 403 insufficient_capability): environment management, engine create, update, configuration and publish, and conversation instance authoring. Each operation description names the capability a scoped key needs.

Path Parameters

instance_slug
string
required

Conversation instance identifier slug (e.g. platform-assistant).

conversation_id
string<uuid>
required

Body

application/json
end_user
string
required

The asserted end-user identity the conversation must belong to. Required; a mismatch is a 404.

turn_id
string<uuid>
required

The turn this annotation anchors to.

rating
enum<string>
required
Available options:
good,
bad,
neutral
comment
string

Optional free-text comment. At most 4,000 UTF-8 bytes.

reason
string

Optional structured reason token (reason-chip taxonomy). At most 64 UTF-8 bytes.

target
object

Optional JSON object naming a sub-target inside the turn, at most 4096 bytes as sent. Any other JSON value, null included, answers invalid_target.

submitter_id
string

Stable consumer-side submitter identifier. Optional for backward compatibility with legacy annotation callers.

feedback_key
string

Optional consumer-defined logical signal key. When paired with submitter_id, replaying the same conversation turn and feedback key updates one live annotation. Omitting it preserves the legacy append-only annotation contract.

Maximum string length: 64

Response

The created annotation, or the updated one when submitter_id and feedback_key match a live annotation on the same turn. An update that changes rating, comment or reason resets triage.status to new and adds 1 to triage.revision.

Explicit human signal recorded against one conversation turn.

triage
object
required

How the platform team is handling this feedback: status, owner, reply and revision. Read-only and always present. A new annotation reads {"status": "new", "owner": "", "reply": "", "revision": 0}.

id
string<uuid>
required
conversation_id
string<uuid>
required
instance_id
string<uuid>
required
turn_id
string<uuid>
required
rating
enum<string>
required
Available options:
good,
bad,
neutral
source
string
required

Capture surface, e.g. api or portal.

created_at
string<date-time>
required
updated_at
string<date-time>
required
end_user
string

The conversation's end user; omitted when unset.

target
object

Optional JSON sub-target inside the turn; omitted when unset.

comment
string

Optional free-text comment; omitted when unset.

reason
string

Optional structured reason token; omitted when unset.

submitter_user_id
string

Portal (WorkOS) submitter; omitted for API submissions.

submitter_id
string

Consumer-side submitter identifier; omitted when unset.

feedback_key
string

Replay-safe logical signal key; omitted when unset.

Last modified on September 25, 2026