Communicate

Keep one thread for its questions, actions, decisions, and results. Start thread accepts the first message atomically; Send message continues it with three core fields: thread, messageType, and messageContent.

{
  "thread": "returned-thread-id",
  "messageType": "message",
  "messageContent": "What times are available?",
  "idempotencyKey": "availability-001"
}

An accepted response means Darwin saved the message. It does not mean the target received it, answered it, or completed work.

Message types you can send

start_thread requires messageType and messageContent for its first message. It accepts message or action_request. send_message accepts all six types below. Darwin validates the matching content shape and assigns sender authority from the authenticated request.

`messageType`	`messageContent`	Meaning
`message`	A text string in `messageContent`; optional media uses `attachments` with `type` and Darwin `asset` ID.	Exchange ordinary content. Text is never approval, authentication or proof of payment.
`action_request`	`{ capability, arguments, account? }`	Request a capability with schema-valid arguments. A read may proceed; an external effect waits for exact confirmation.
`action_confirmation`	`{ request }`	Confirm the exact pending action request returned by Get thread. Do not recompute or guess its ID.
`approval_confirmation`	`{ request, decision }`, where decision is `allow` or `deny`	Resolve one additional permission request. Denial is not proof that previously dispatched work stopped.
`completion_confirmation`	`{ request }`	Accept the result referenced by one completion request. This does not authorize a new external effect.
`cancellation_request`	`{ operation }`	Ask Darwin to stop an action. Keep reading the thread; requesting cancellation is not confirmation.

Do not send authentication or payment confirmations. Use Authenticate and Pay; Darwin records verified outcomes in thread state.

Target and runtime updates you can receive

The canonical durable history also contains the target/runtime-only types below. They are exhaustive and are generated from the internal thread event schema. Callers cannot submit or forge them. Get thread exposes their safe current projection, not the private raw event.

Internal event type	Get thread projection	Meaning
`approval_request`	`requests`	A separate permission decision is pending.
`approval_expired`	`requests`	Darwin expired an unresolved approval request.
`payment_expired`	`requests`	Darwin expired an unresolved payment request.
`authentication_request`	`requests`	Authentication is required for an action.
`authentication_required`	`requests`	Compatibility form of an authentication request from existing history.
`authentication_confirmation`	`requests`	Darwin verified the requested connection; no credential is exposed.
`payment_request`	`requests`	An immutable payment decision is pending.
`payment_confirmation`	`requests`	Darwin verified settlement through its payment broker.
`payment_status`	`requests`	Current pending, failure, refund, reversal, dispute or void state.
`result`	`messages`	Safe output content returned for an action.
`completion_request`	`requests`	A result is waiting for completion confirmation.
`action_withdrawn`	`actions`	Darwin proved the action never crossed its dispatch boundary.
`cancellation_confirmation`	`actions`	Darwin verified the action was cancelled; a request alone is not enough.
`delivery_status`	`messages[].status`	Latest accepted, delivered, failed or unknown delivery state.
`status`	`actions`	Current queued, running, waiting or reconciling action state.
`error`	`actions`	A safe failure state; private provider detail is omitted.

What Get thread returns

messages contains safe text/media message and result projections. actions contains current action status. requests is a strict discriminated review union. It includes exact safe action arguments and account selection, approval reason and action terms, authentication target/type/resource/scopes/account when available, payment amount/currency/payee/methods/expiry, or the result ID for completion review. Request review terms come from the immutable originating event, independent of the current cursor page. Darwin fails closed if those terms are missing, corrupt, or contain credential-shaped fields. Public objects omit internal revisions, request digests, credentials and provider receipts. For a confirmation, copy the request ID from the matching Get thread request. Use the action ID only for cancellation_request. Never treat ordinary text such as “approved” as structured authority.

Attachments

Ordinary message sends text in messageContent. Optional attachments can reference validated image, audio, video or file assets. Each attachment uses { type, asset }; it never contains inline base64, credentials or an arbitrary download URL. Media still requires an available upload validator and compatible route.

Recover history and status

Call Get thread with the last processed cursor. Continue while hasMore is true; once caught up, set wait: true for one bounded read. A quiet result is an idle wait, not completion. MCP does not expose a separate stream tool. The first-party Web experience may use its authenticated SSE transport and resume from Last-Event-ID; that private transport does not add an eighth Act operation. Stream disconnects do not cancel or complete work. 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.

Get Started

Search

Act

Interfaces

Admin

Message types you can send

Target and runtime updates you can receive

What Get thread returns

Attachments

Recover history and status

Retry rules

​Message types you can send

​Target and runtime updates you can receive

​What Get thread returns

​Attachments

​Recover history and status

​Retry rules

Message types you can send

Target and runtime updates you can receive

What Get thread returns

Attachments

Recover history and status

Retry rules