> ## Documentation Index > Fetch the complete documentation index at: https://docs.usenexio.com/llms.txt > Use this file to discover all available pages before exploring further. # Stop a turn > Stop a turn while the assistant works. Nothing new starts; a write already started finishes and is kept. ## 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](/conversations/stop). ## OpenAPI ````yaml POST /api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/turns/{turn_id}/stop openapi: 3.1.0 info: title: Nexio API version: '1.0' description: | The Nexio public API. Submit runs to configured engines and read their results, hold conversations with configured assistants, make authorized reads over the planes and families of a connected system of record, and manage webhooks and environments. Six engine types are registered: comparison, matching, entity_analysis, diligence, triage, and opportunity. Every route under /api/v1/ requires `Authorization: Bearer `, except inbound event ingest (`POST /api/v1/events/ingest/{source_key}`), which authenticates each request against its ingest source instead: an HMAC-SHA256 signature for `nexio` and `github` sources, or a shared authentication code for an `ams360_ons` source. Error bodies share the `Error` schema. Call the API from servers only: it sends no CORS headers. contact: email: support@usenexio.com url: https://docs.usenexio.com servers: - url: https://api.usenexio.com description: >- Nexio API. Sandbox or live is chosen by the API key's environment, not by the host. security: - BearerAuth: [] tags: - name: EngineManagement description: >- Create, configure, version and manage engines. An engine is a configuration of one registered engine type. - name: Engines description: Engine-scoped endpoints for submitting runs and retrieving results. - name: Runs description: Retrieve and reconcile submitted runs. - name: Records description: >- Typed, authorized reads of the collections a connected system of record serves, and governed writes to the action ledger. - name: Connections description: >- The source tables registered on a connection, read by their own names: the estate surface, for lineage, operators and proofs. Product code reads collections under Records. - name: Graph description: >- The organization's data graph: a read-only map of connections and the derivations scheduled on them. Node kinds are a closed registry of 16; the API serves 14. - name: Environments description: >- The live environment and up to 5 sandbox environments in your org. Organization keys only. - name: Webhooks description: >- Manage webhook endpoints that receive terminal run events (run.completed, run.failed, run.cancelled) and run corrections (run.superseded). - name: Events description: >- Send inbound events to your organization's event log through an ingest source. Source kinds are nexio, github, ams360_ons and inbound_mail; a nexio source sends event types from your own vocabulary. - name: Converse description: The raw stateless conversational model turn (caller-owned state). - name: Conversations description: >- Conversation instances (orchestrators over engines) and their managed conversations, turns, annotations, evals, and exports. - name: Platform description: Service health. No key needed. paths: /api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/turns/{turn_id}/stop: parameters: - $ref: '#/components/parameters/InstanceSlug' - name: conversation_id in: path required: true schema: type: string format: uuid - name: turn_id in: path required: true description: >- The turn id, from the `turn_id` of the `conversation` frame or of a stored message. schema: type: string format: uuid post: tags: - Conversations summary: Stop a turn description: | Stops the named turn. Nothing new starts after it. A write already dispatched finishes and its result is kept; a model reply or a platform read in progress is cut short. Stop never cuts a write, never undoes a step that ran, and cancels no run. Every step that was opened gets a stored result that says it was stopped, and text already streamed is kept when it passes the instance's output checks. Answers within two seconds with the turn: `stopped` when it came to rest, or `stopping` when a running step still has to finish (its stream ends with `turn_end` and `stop_reason: "stopped"`; read the turn until it is at rest, and call Stop again if it reads `stopping` for more than three seconds). Safe to repeat: a turn at rest is returned unchanged. Allowed on an archived conversation. Requires `conversations:use`. The `end_user` assertion is REQUIRED and the lookup is scoped to it. Served only when turn control is on for the environment (conversation detail carries the `turn` key, and the `conversation` frame carries `turn_control: true`). Until then the route answers `404 not_found`. operationId: stopConversationTurn requestBody: required: true content: application/json: schema: type: object required: - end_user properties: end_user: type: string maxLength: 256 description: >- The asserted end-user identity the conversation must belong to. A missing assertion is a 400, a mismatch a 404. responses: '200': description: >- The turn, `stopped` or `stopping`, or unchanged when it was already at rest. content: application/json: schema: $ref: '#/components/schemas/ConversationTurnEnvelope' '400': description: >- `invalid_request`: the body is not JSON, or `end_user` is missing, blank, or over 256 characters. `missing_instance_slug`: the slug in the path is blank. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- A scoped key lacks the capability (`insufficient_capability`), or the instance is archived (`instance_archived`). content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: | `not_found` (turn control is not on for this environment), `instance_not_found`, `conversation_not_found` (malformed or unknown id, or another end user, key environment, or instance), `turn_not_found` (malformed or unknown turn id, a turn of another conversation, or a turn with no record because it started before turn control was on). content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/RateLimited' '500': description: >- `internal_error`: the stop could not be recorded. Nothing changed; call Stop again. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: | Converse is not enabled in this deployment (`converse_unavailable`), or `auth_unavailable`: API key authentication was briefly unavailable before the route ran. content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: InstanceSlug: name: instance_slug in: path required: true description: Conversation instance identifier slug (e.g. `platform-assistant`). schema: type: string schemas: ConversationTurnEnvelope: type: object description: The body of the turn read and of Stop. required: - turn properties: turn: $ref: '#/components/schemas/ConversationTurn' Error: type: object required: - code - message properties: code: type: string description: > Stable snake_case error identifier. Safe to match programmatically. New codes are added over time; treat an unknown code by its HTTP status. Known codes include: `invalid_request`, `invalid_input`, `unauthorized`, `auth_unavailable`, `rate_limited`, `missing_run_id`, `invalid_run_id`, `run_not_found`, `invalid_offerings`, `missing_input`, `queue_unreachable`, `engine_not_found`, `engine_slug_conflict`, `engine_archived`, `instance_not_found`, `instance_slug_conflict`, `instance_archived`, `instance_follows_canonical`, `instance_not_published`, `invalid_engine_type`, `validation_error`, `webhook_not_found`, `webhook_limit_exceeded`, `invalid_url`, `invalid_events`, `invalid_description`, `invalid_auth_token`, `missing_endpoint_id`, `invalid_endpoint_id`, `missing_delivery_id`, `invalid_delivery_id`, `delivery_not_found`, `delivery_not_resendable`, `insufficient_capability`, `engine_version_required`, `engine_version_exact_required`, `engine_version_not_found`, `engine_version_invalid_format`, `engine_version_draft_requires_sandbox_key`, `engine_version_none_released`, `test_scenario_sandbox_only`, `test_scenario_forbidden`, `test_scenario_exact_version_required`, `test_scenario_version_not_supported`, `invalid_test_scenario`, `request_bound_exceeded`, `run_cap_exceeded`, `scoped_key_required`, `engine_binding_forbidden`, `request_timeout`, `internal_error`, `idempotency_key_reused`, `invalid_idempotency_key`, `acting_principal_mismatch`, `run_requires_acting_principal`, `environment_slug_invalid`, `environment_slug_reserved`, `environment_slug_taken`, `environment_name_invalid`, `environment_limit_reached`, `environment_live_immutable`, `environment_not_found`, `environment_in_use`, `environment_operation_failed`, `list_environments_failed`, `engine_release_unservable`, `engine_config_hash_inconsistent`, `engine_config_hash_unavailable`, `engine_config_version_unavailable`, `engine_version_resolve_failed`, `engine_config_version_load_failed`, `engine_version_publish_mismatch`, `engine_version_schema_change_requires_major`, `engine_config_hash_missing`, `engine_config_changed`, `invalid_engine_config`, `cold_start_gate_not_met`, `cold_start_gate_failed`, `cold_start_gate_regressed`, `cancel_run_failed`, `event_id_reused`, `invalid_event_id`, `missing_event_id`, `invalid_event_type`, `invalid_payload`, `reason_text_too_long`, `reason_taxonomy_version_unknown`, `invalid_rating`, `missing_comment`, `invalid_target`, `invalid_time_on_task`, `scoped_annotation_required`, `missing_instance_slug`, `invalid_instance_config`, `invalid_eval_waiver`, `instance_config_hash_missing`, `config_changed_during_publish`, `scenario_set_changed_during_publish`, `conversation_eval_regressed`, `conversation_eval_execution_failed`, `conversation_eval_gate_unavailable`, `publish_failed`, `conversation_not_found`, `conversation_archived`, `invalid_cursor`, `message_not_found`, `invalid_turn_request`, `message_too_long`, `invalid_tool_result`, `invalid_confirmation`, `invalid_edit_target`, `turn_in_progress`, `pending_turn`, `turn_state_conflict`, `confirmation_environment_unpinned`, `instance_config_missing`, `instance_config_invalid`, `instance_model_unavailable`, `guardrail_evaluation_failed`, `guardrail_config_invalid`, `invalid_conversation_history`, `streaming_unsupported`, `converse_unavailable`, `provider_error`, `provider_unavailable`, `unknown_model`, `too_many_messages`, `too_many_tools`, `invalid_max_tokens`, `invalid_message_role`, `invalid_message`, `invalid_content_block`, `invalid_tool`, `attachments_not_enabled`, `attachments_unavailable`, `attachment_rejected`, `attachment_too_large`, `attachments_too_large`, `too_many_attachments`, `attachment_not_accepted`, `attachment_not_found`, `attachment_changed`, `attachment_read_failed`, `attachment_member_delete`, `attachment_not_reservable`, `invalid_offset`, `invalid_turn_id`, `invalid_comment`, `invalid_reason`, `invalid_feedback_key`, `turn_not_found`, `annotation_not_found`, `annotation_not_promotable`, `invalid_eval_scenario`, `conversation_eval_scenario_not_found`, `conversation_eval_scenario_cap`, `conversation_eval_run_not_found`, `conversation_eval_baseline_not_found`, `conversation_eval_unavailable`, `instance_version_invalid_format`, `instance_version_not_found`, `document_class_not_open`, `presign_failed`, `markets_directory_unavailable`, `book_unavailable`, `book_connection_ambiguous`, `identity_unmapped`, `identity_needs_review`, `identity_suspended`, `identity_stale`, `scope_unavailable`, `assertion_invalid`, `assertion_stale`, `cursor_filter_mismatch`, `cursor_expired`, `action_schema_unknown`, `action_payload_invalid`, `action_out_of_scope`, `action_list_too_large`, `overlay_read_only`, `unsupported_node_type`, `acting_principal_required`, `action_denied`, `appetite_read_denied`, `approval_required`, `catalog_access_denied`, `catalog_connection_ambiguous`, `create_webhook_failed`, `dataset_denied`, `delivery_id_reused`, `document_type_not_servable`, `document_unclassified`, `egress_manifest_version_mismatch`, `egress_manifest_version_required`, `event_type_not_allowed`, `event_type_reserved`, `execution_confirm_required`, `execution_prohibited`, `ingest_source_disabled`, `ingest_source_misconfigured`, `ingest_source_not_found`, `invalid_acting_assertion`, `invalid_active`, `invalid_credentials`, `invalid_payload_mode`, `invalid_signature`, `load_run_failed`, `load_solutions_failed`, `load_work_items_failed`, `missing_engine_slug`, `not_found`, `object_store_unconfigured`, `provider_not_approved`, `resolve_retry_exhausted`, `run_lookup_failed`, `service_identity_unknown`, `stale_timestamp`, `surface_denied`, `unresolved_market_question`, `unsupported_market_filter`. The full list with causes and fixes is at https://docs.usenexio.com/reference/errors. message: type: string description: Human-readable error message. May change between versions. details: description: | Optional request-specific details. Request-bound failures use the `RequestBoundDetails` object. Validation failures may use an array of field issues or another documented object. `409 environment_in_use` is the one exception to this envelope: it carries a top-level `blockers` object (see `EnvironmentInUseError`) instead of `details`. ConversationTurn: type: object description: | 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. required: - id - status - started_at - stop_requested_at - ended_at - stop_reason properties: id: type: string format: uuid description: >- The turn id, equal to `turn_id` on the `conversation` frame and on every stored message of the turn. status: type: string enum: - running - waiting_on_tools - waiting_on_confirmation - stopping - completed - stopped - failed started_at: type: string format: date-time description: When the turn's user message was stored. stop_requested_at: type: - string - 'null' format: date-time description: When Stop was first requested. A repeated Stop does not move it. ended_at: type: - string - 'null' format: date-time description: When the turn came to rest. stop_reason: type: - string - 'null' description: | 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. responses: Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: unauthorized message: Missing or invalid API key RateLimited: description: Rate limit exceeded. Retry after the window resets. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limited message: Rate limit exceeded headers: RetryAfter: description: Whole seconds to wait before retrying, at least 1. schema: type: integer minimum: 1 securitySchemes: BearerAuth: type: http scheme: bearer description: > Send the key as `Authorization: Bearer `. Two kinds of key exist. Organization keys are issued in the portal (Settings, then API keys), each bound to one environment, shaped `nx__<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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.