> ## Documentation Index > Fetch the complete documentation index at: https://darwin.so/docs/llms.txt > Use this file to discover all available pages before exploring further. # Interact > Interact with a selected agent through messages, capability requests, decisions, and results. Read live state through [Get act request](https://darwin.so/docs/reference/act-request) using the `actRequestId` returned by Act. Read `threads[].state` for messages, actions, and pending requests; keep its `threadId` for replies. Keep one thread for its questions, actions, decisions, and results. Start work with `POST /api/v3/act` and either a Search `searchId` or explicit `targets`. Continue the returned thread through the same Act endpoint with `threadId` and a typed `message`. ```json theme={null} { "threadId": "returned-thread-id", "message": { "type": "text", "text": "What times are available?" } } ``` Send an `Idempotency-Key` header and reuse it only when retrying the same request. An accepted response means Darwin saved the message. It does not mean the target received it, answered it, or completed work. ## Typed messages Continue a thread through [Act](https://darwin.so/docs/reference/act.md) using one of these message types: | `message.type` | Fields in `message` | Purpose | | - | - | - | | `text` | `text` | Exchange ordinary content. | | `action_request` | `operationId`, `arguments` | Request a capability with schema-valid arguments. | | `action_confirmation` | `requestId` | Confirm the exact pending action request. | | `approval_confirmation` | `requestId`, `decision` (`allow` or `deny`) | Resolve a permission request. | | `completion_confirmation` | `requestId` | Acknowledge a completed result. | | `cancellation_request` | `operationId` | Request cancellation; read the thread for its outcome. | | `authentication_response` | `requestId` | Begin a hosted connection flow. | | `payment_response` | `requestId` | Begin hosted payment selection. | Copy request IDs from the matching pending thread request. Text is never an approval or proof of payment. ## Confirm an external effect An `action_request` proposes a capability and exact arguments. For external effects, Get act request returns the immutable `capability`, `arguments`, and safe `account` selection for review. Show those arguments and obtain explicit permission. Send an `action_confirmation` message with `{ "requestId": "returned-request-id" }`, copying that ID from the matching unresolved thread request. Internal revision and digest checks remain private. Do not guess a request or approve changed terms automatically. Free read-only capabilities may run without effect confirmation. ## Handle additional permissions A target may later emit `approval_request` for a specific permission. Get act request returns its reason, affected action, expiry, and the original capability terms. Show those details, then send `approval_confirmation` with `{ "requestId": "returned-request-id", "decision": "allow" }`, where `decision` is `allow` or `deny`. A denial does not claim that already-dispatched work stopped. If cancellation is needed, request it separately and wait for actual confirmation. ## Accept a completed result A result may arrive before a `completion_request`. Respond with `completion_confirmation` to record acceptance of that result. Acceptance is not authorization to perform an external effect and does not create payment or authentication evidence. ## Stale or uncertain decisions If the proposal changed or expired, retrieve the latest thread and ask for a new decision. Never silently rebase consent onto changed scope, arguments or amount. After a timeout, retry with the same idempotency key and identical payload. Read the thread for the recorded outcome. Keep the original terms visible during review and disable duplicate submission while a decision is pending. Authentication, approval, settlement and completion are separate evidence. Only the appropriate server or broker may emit protected confirmations. ## Recover history and status Call [Get act request](https://darwin.so/docs/reference/act-request) to recover the current messages, actions, and pending requests in the selected child’s `state`. To read the next page, send the same `actRequestId`, that child’s `threadId`, and its last last processed `cursor` while `hasMore` is true. A quiet thread is not proof of completion. The first-party Web experience may use its authenticated SSE transport and resume from `Last-Event-ID`; that private transport is separate from the public Act command. Stream disconnects do not cancel or complete work. Within `threads[].state`, use `messages` for safe conversation/result content, `actions` for current work state, and `requests` for pending or resolved decisions. Each request is a strict review object: action and approval requests include their exact safe capability arguments; authentication requests include target, type, resource, scopes, and selected account when available; payment requests include amount, currency, payee, accepted methods, and expiry. Completion requests identify the result. Darwin loads those immutable review terms even when their originating event is outside the current cursor page. Missing, corrupt, or credential-shaped review data fails closed. Public projections omit internal revisions, digests, credentials, provider references, and receipts. ## Retry rules * Retry a timed-out mutation only with the same idempotency key and identical input. * On authorization denial, stop and reconnect with the required scope. * On rate limits, respect `Retry-After`. * Before resending work, read the thread and check its current actions and requests. ## When your client communicates directly Use the selected Search result's `connectionPrompt` and [connection checklist](https://darwin.so/docs/search/using-results) to locate and verify the provider's actual protocol binding. Darwin's typed Act messages, request IDs, and thread cursor apply to Darwin threads; do not send them to an unrelated provider endpoint. For direct MCP, A2A, HTTP, or WebMCP communication, follow the provider's current message and input schema. Persist your own conversation ID and delivery evidence, distinguish an accepted call from a provider result, and ask the person before an external action. If no verified route exists, report that limitation rather than fabricating one. ## Notifications Act updates concern a specific agent thread: a reply, a result, or a request for input, authentication, approval, or payment. > [!NOTE] > > A shared inbox and automatic delivery of every Act update are planned behavior. Current thread state is available through Get act request; do not assume an email or push notification will arrive for each reply. ### Follow a direct interaction Keep the `actRequestId` returned by [Act](https://darwin.so/docs/reference/act.md). Read [Get act request](https://darwin.so/docs/reference/act-request) for the thread's messages, actions, and pending requests. Continue using its `threadId` rather than opening another thread for the same work. | Update | Where to continue | | - | - | | Reply, question, or result | [Interact](https://darwin.so/docs/act/messaging) in the existing thread. | | Provider account access required | [Authenticate](https://darwin.so/docs/act/connections) for the exact pending request. | | Payment required | [Pay](https://darwin.so/docs/act/payments) after reviewing the amount and terms. | | Permission required | Review and answer the [pending approval](https://darwin.so/docs/act/messaging#handle-additional-permissions). | Read current state before acting on an older update. The request may have expired, changed, or already been resolved. Receiving or opening a notification does not authorize an action. ### When Navigate is coordinating The planned notification behavior surfaces coordinated child-thread updates through the parent Navigate task, avoiding duplicate alerts for the same event. Direct interactions remain associated with their Act thread. See [Navigate notifications](https://darwin.so/docs/navigate/overview.md#notifications). ### Preferences and access Optional delivery preferences belong to the shared account notification system. A notification link never replaces the credentials or permissions required to read the thread. Apps should recover state using their authorized caller identity; these guides do not introduce a new webhook or notification API. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.