Skip to main content
POST
Annotate a Run

Authorizations

Authorization
string
header
required

Send the credential as Authorization: Bearer <key>.

Scoped partner credentials use the exclusive nxsk_v1_... namespace. Each scoped key is bound at issuance to one organization, one canonical named environment, an explicit engine set, and a least-privilege capability set. A malformed, unknown, rotated, or revoked nxsk_ key fails closed and is never retried as a legacy key.

Capabilities used by this API are runs:write, runs:read, engines:read, catalog:read, webhooks:manage, runs:defensibility:read, runs:test, conversations:use, and conversations:export. Operation descriptions name the required capability. Grandfathered nx_live_... and nx_test_... keys retain their existing broad access during the compatibility window.

Path Parameters

engine_slug
string
required

Engine identifier slug (e.g. default).

run_id
string<uuid>
required

Body

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

Required free-text note. Cannot be empty.

Example:

"Bound the recommended carrier; the ranking matched our judgment."

target
object | null

Optional pointer at the output element the note is about.

submitter_id
string | null

Optional caller-supplied identifier for who submitted the signal.

time_on_task_seconds
integer | null

Response

Annotation recorded.

id
string
run_id
string
rating
string
comment
string
source
string
Example:

"api"

created_at
string<date-time>