curl --request POST \
--url https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/annotations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"end_user": "<string>",
"turn_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"comment": "<string>",
"reason": "<string>",
"target": {},
"submitter_id": "<string>",
"feedback_key": "<string>"
}
'import requests
url = "https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/annotations"
payload = {
"end_user": "<string>",
"turn_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"comment": "<string>",
"reason": "<string>",
"target": {},
"submitter_id": "<string>",
"feedback_key": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
end_user: '<string>',
turn_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
comment: '<string>',
reason: '<string>',
target: {},
submitter_id: '<string>',
feedback_key: '<string>'
})
};
fetch('https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/annotations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"triage": {
"status": "<string>",
"owner": "<string>",
"reply": "<string>",
"revision": 123
},
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"instance_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"turn_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"rating": "good",
"source": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"end_user": "<string>",
"target": {},
"comment": "<string>",
"reason": "<string>",
"submitter_user_id": "<string>",
"submitter_id": "<string>",
"feedback_key": "<string>"
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "unauthorized",
"message": "Missing or invalid API key"
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "rate_limited",
"message": "Rate limit exceeded"
}{
"code": "internal_error",
"message": "Internal server error"
}{
"code": "auth_unavailable",
"message": "API key authentication is temporarily unavailable"
}{
"code": "request_timeout",
"message": "Request timed out"
}Annotate a turn
Rate one turn of a conversation, optionally with a comment and reason.
curl --request POST \
--url https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/annotations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"end_user": "<string>",
"turn_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"comment": "<string>",
"reason": "<string>",
"target": {},
"submitter_id": "<string>",
"feedback_key": "<string>"
}
'import requests
url = "https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/annotations"
payload = {
"end_user": "<string>",
"turn_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"comment": "<string>",
"reason": "<string>",
"target": {},
"submitter_id": "<string>",
"feedback_key": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
end_user: '<string>',
turn_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
comment: '<string>',
reason: '<string>',
target: {},
submitter_id: '<string>',
feedback_key: '<string>'
})
};
fetch('https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/annotations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"triage": {
"status": "<string>",
"owner": "<string>",
"reply": "<string>",
"revision": 123
},
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"instance_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"turn_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"rating": "good",
"source": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"end_user": "<string>",
"target": {},
"comment": "<string>",
"reason": "<string>",
"submitter_user_id": "<string>",
"submitter_id": "<string>",
"feedback_key": "<string>"
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "unauthorized",
"message": "Missing or invalid API key"
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "<string>",
"message": "<string>",
"details": "<unknown>"
}{
"code": "rate_limited",
"message": "Rate limit exceeded"
}{
"code": "internal_error",
"message": "Internal server error"
}{
"code": "auth_unavailable",
"message": "API key authentication is temporarily unavailable"
}{
"code": "request_timeout",
"message": "Request timed out"
}Authorizations
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
Conversation instance identifier slug (e.g. platform-assistant).
Body
The asserted end-user identity the conversation must belong to. Required; a mismatch is a 404.
The turn this annotation anchors to.
good, bad, neutral Optional free-text comment. At most 4,000 UTF-8 bytes.
Optional structured reason token (reason-chip taxonomy). At most 64 UTF-8 bytes.
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.
Stable consumer-side submitter identifier. Optional for backward compatibility with legacy annotation callers.
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.
64Response
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.
good, bad, neutral Capture surface, e.g. api or portal.
The conversation's end user; omitted when unset.
Optional JSON sub-target inside the turn; omitted when unset.
Optional free-text comment; omitted when unset.
Optional structured reason token; omitted when unset.
Portal (WorkOS) submitter; omitted for API submissions.
Consumer-side submitter identifier; omitted when unset.
Replay-safe logical signal key; omitted when unset.