> ## Documentation Index
> Fetch the complete documentation index at: https://getoverlay.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations

> Create, update, run, and stop web conversations.

Use the typed `@overlay/api-client` conversation methods when possible.

Typical flow:

1. Create or load a conversation with `/api/v1/conversations`.
2. Add user-visible messages with `/api/v1/conversations/message`.
3. Run an Act turn with `/api/v1/conversations/act`.
4. On reconnect, read `/api/v1/conversations/run` and reload the authoritative conversation state; AgentRun decides whether a turn is still active.
5. Stop an active turn with `/api/v1/conversations/stop`.

Personal Act requests use one Chat experience and a durable AgentRun. Backend capability selects the Overlay Harness when available; a successful readiness response from an older backend selects the existing durable personal workflow. Readiness failures remain fail-closed. New personal runs use `mode: "chat"` and preserve authorization, approval, billing, and usage-limit checks.

For compatibility, `/api/v1/conversations/act` still accepts the optional `personalChatMode: "chat" | "work"` field. It is deprecated and ignored; it does not select execution behavior. Existing stored preferences and AgentRuns are left untouched.

Conversation messages may contain text, file references, generated UI data, and tool invocation parts. Keep generated and persisted message shapes aligned with `@overlay/app-core`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.