---
title: "Clarify"
method: POST
path: "/auto-agent/clarify"
tags: ["auto-agent"]
---

# Clarify

`POST /auto-agent/clarify`

Stream the clarification agent response as Server-Sent Events.

Each event is a JSON object preceded by ``data: `` and terminated by two
newlines.  Two event types are emitted:

- ``{"type": "delta", "content": "..."}`` — streamed token(s).
- ``{"type": "complete", ...}`` — final summary with answer, interrupt
  data, and run_id / results_url if the agent triggered a run.

When a run is triggered, a background task is scheduled via
``spawn_background_task`` (FastAPI BackgroundTasks is incompatible with
StreamingResponse).

Args:
    request: FastAPI request (required by rate limiter).
    body: Chat request with message, optional resume_value, and history.
    auth: Authenticated user.

Returns:
    StreamingResponse with ``text/event-stream`` content type.

Raises:
    HTTPException: 400 if neither message nor resume_value is provided.

## Request body

- AutoAgentClarifyRequest — Request body for a clarification agent turn. Either `message` (new turn) or `resume_value` (MCQ selection resume) must be set. Args: message: The user's text input for a new turn. resume_value: The option the user selected from an MCQ (resumes interrupted graph). conversation_id: Conversation ID (required for resume; generated on first call). history: Optional conversation history [{role, content}].
  - `message` string, nullable — User text input (for new turns)
  - `resume_value` string, nullable — MCQ option selected by user (resumes interrupted graph)
  - `conversation_id` string, nullable — Existing conversation ID
  - `history` object[], nullable — Conversation history [{role, content, tool_calls?, tool_call_id?, name?}]
  - `project_id` string, nullable — Project ID selected by the user. Hidden from the chat UI and used to scope any resources created by a triggered Auto Agent run.
  - `client_metadata` object, nullable — Optional client trace metadata for observability.

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/pioneer/apis/brain-api.md) · [All operations](https://skmtc.net/pioneer/apis/brain-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pioneer/brain-api/versions/31dfe831e079/schema)