Use assistant conversations and events

How-to guideApplies to: Unified engine deployments

Create a conversation, submit one read-scope turn, watch its events, and read the final result. The assistant must be configured and its provider available.

Ask through the assistant API

The assistant must be configured. This example uses read scope and may make a model request.

Placeholder	Value
`{{conversation_submission}}`	A new UUID for this request; reuse it when recovering the same submission.
`{{turn_submission}}`	A new UUID for this request; reuse it when recovering the same submission.

Replace the placeholders in your client. Keep returned IDs for later requests. Paths below use the native API prefix; adjust it for your deployment.

1. Check assistant availability

GET /api/v1/assistant/capabilities
Host: <ENGINE_HOST>

Endpoint reference.

2. Create a conversation

POST /api/v1/assistant/conversations
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "submission_id": "{{conversation_submission}}",
  "title": "HTTP docs question"
}

From the response, keep conversation_id from /conversation_id. Endpoint reference.

3. Ask a question

POST /api/v1/assistant/conversations/{{conversation_id}}/turns
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "submission_id": "{{turn_submission}}",
  "message": "Explain how a Manual workload runs.",
  "scope": "read"
}

From the response, keep turn_id from /turn_id. Endpoint reference.

4. Watch events

GET /api/v1/assistant/conversations/{{conversation_id}}/turns/{{turn_id}}/events/stream
Host: <ENGINE_HOST>

Endpoint reference.

5. Read the final turn

GET /api/v1/assistant/conversations/{{conversation_id}}/turns/{{turn_id}}
Host: <ENGINE_HOST>

Endpoint reference. Read scope asks the assistant to inspect and explain. Draft and execute scopes have separate behavior. Model requests can incur provider usage. Check assistant capabilities before submitting the turn. The stream carries sequence IDs. Reconnect with the supported cursor rather than creating a new turn to recover an interrupted stream. Stop watching only closes the browser’s stream; cancellation uses the turn cancel API. Inspect action requests and approval state before using the action-approval endpoint. The response and event APIs return public turn data; internal model messages are not part of the public response.

Transformation Engine

Learn Laminar

Workloads

SQL reference

HTTP API

Recipes

Operations

Use assistant conversations and events

Ask through the assistant API

1. Check assistant availability

2. Create a conversation

3. Ask a question

4. Watch events

5. Read the final turn

​Ask through the assistant API

​1. Check assistant availability

​2. Create a conversation

​3. Ask a question

​4. Watch events

​5. Read the final turn

Ask through the assistant API

1. Check assistant availability

2. Create a conversation

3. Ask a question

4. Watch events

5. Read the final turn