Stop a turn

curl --request POST \
  --url https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/turns/{turn_id}/stop \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "end_user": "<string>"
}
'

import requests

url = "https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/turns/{turn_id}/stop"

payload = { "end_user": "<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>'})
};

fetch('https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/turns/{turn_id}/stop', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "turn": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "running",
    "started_at": "2023-11-07T05:31:56Z",
    "stop_requested_at": "2023-11-07T05:31:56Z",
    "ended_at": "2023-11-07T05:31:56Z",
    "stop_reason": "<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": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

POST

api

conversation-instances

{instance_slug}

conversations

{conversation_id}

turns

{turn_id}

stop

Stop a turn

curl --request POST \
  --url https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/turns/{turn_id}/stop \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "end_user": "<string>"
}
'

import requests

url = "https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/turns/{turn_id}/stop"

payload = { "end_user": "<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>'})
};

fetch('https://api.usenexio.com/api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/turns/{turn_id}/stop', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "turn": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "running",
    "started_at": "2023-11-07T05:31:56Z",
    "stop_requested_at": "2023-11-07T05:31:56Z",
    "ended_at": "2023-11-07T05:31:56Z",
    "stop_reason": "<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": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

{
  "code": "<string>",
  "message": "<string>",
  "details": "<unknown>"
}

Behavior

Served only when turn control is on for your environment; until then the route answers 404 not_found. You know it is on when conversation detail carries the turn key or the conversation frame carries "turn_control": true. Stop answers within two seconds with the turn, stopped or stopping. It is safe to repeat: a turn at rest is returned unchanged. It works on an archived conversation. It never undoes a step that ran, never cuts a write, and cancels no run. How to show Stop, read a stopped turn, and handle late results is on Stop a 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 /records, /actions, /operations, /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

turn_id

string<uuid>

required

The turn id, from the turn_id of the conversation frame or of a stored message.

Body

application/json

end_user

string

required

The asserted end-user identity the conversation must belong to. A missing assertion is a 400, a mismatch a 404.

Maximum string length: 256

Response

The turn, stopped or stopping, or unchanged when it was already at rest.

The body of the turn read and of Stop.

turn

object

required

One turn of a conversation, as served by conversation detail, the turn read and Stop. status is derived when it is read: a turn not at rest whose stop was requested is stopping, and a handoff paused 10 minutes or more with no stop requested is failed with stop_reason handoff_lost. completed, stopped and failed are at rest.

Hide child attributes

turn.id

string<uuid>

required

The turn id, equal to turn_id on the conversation frame and on every stored message of the turn.

turn.status

enum<string>

required

Available options:

running,

waiting_on_tools,

waiting_on_confirmation,

stopping,

completed,

stopped,

failed

turn.started_at

string<date-time>

required

When the turn's user message was stored.

turn.stop_requested_at

string<date-time> | null

required

When Stop was first requested. A repeated Stop does not move it.

turn.ended_at

string<date-time> | null

required

When the turn came to rest.

turn.stop_reason

string | null

required

Null until the turn is at rest. Then the model's stop reason (such as end_turn), stopped (the user stopped it), handoff_lost (client tool results never arrived within 10 minutes), segment_lost (the segment running it died), or the error code of a failed turn.

Last modified on September 29, 2026

Overview

Engines

Environments

Conversations

Webhooks

Events

Records

Connections

Graph

Platform

Stop a turn

Behavior

Authorizations

Path Parameters

Body

Response

​Behavior

Authorizations

Path Parameters

Body

Response

Behavior