Skip to main content
POST
Act
POST /api/v3/act starts one agent thread or continues it with a typed reply. Get act request reads current messages, pending requests, and progress; it does not start work. Your credential identifies the caller. You do not send an identity selector. An account-owner API key needs agent:write; an assistant acting for a person needs a live human:actions OAuth grant. Application-only keys cannot act as their owner or an end user.

Anonymous public Act (preview)

When guest access is enabled for Act (preview), you can start reviewed, free public work before signing in. Live route, read-only operation and provider readiness checks still apply. A first REST start without credentials returns an X-Act-Token response header. Keep it in private client storage and send it on every subsequent read, continuation and retry. The credential expires after 24 hours; a thread ID alone never grants access. Invalid API keys or bearer tokens are rejected rather than treated as anonymous requests. For sign-in, send your verified account credential together with the same X-Act-Token. Darwin transfers the existing thread and preserves its messages and retry identities. Continue that thread; signing in does not approve an action, pay, or repeat completed work. Application-bound guests require the same application. Private accounts, provider authentication, payment and private media still require sign-in and their normal approvals. The web keeps guest proof in an HttpOnly cookie. The MCP preview returns proof only in host-only result _meta["darwin/actToken"]; hosts opt in with X-Darwin-Guest-Act: true, store it per user, and forward it as an X-Act-Token HTTP header. Never put it in model arguments, messages, logs or URLs. MCP session IDs and unverified user metadata are not ownership proof. Hosts without per-user credential custody must use OAuth to continue. A short-lived browser claim link keeps an existing guest thread across an OAuth reconnect; it does not authorize payment or execution.

Start and continue

Send exactly one of searchId, targets, or threadId. Choose exactly one agent for a new thread. For a Search handoff, set agentIds to the chosen agent ID; use the same owner credential and, when handing off a first-party guest Search, its X-Search-Token as additional proof. Direct starts use one entry in targets; continuations use a threadId and a typed message.
The response returns a threadId and an actRequestId receipt. Read Get act request using actRequestId, then continue through this same Act endpoint:
Use an Idempotency-Key header and reuse it for retries of the same request. A new message uses a new key. A created thread is not a completed provider outcome. The request reader also supports historical batch receipts.

Authentication

Read the selected child’s state.requests from Get act request for entries with type: "authentication_request" or "authentication_required". Review the target, resource and scopes, then submit the exact request ID:
A user API key also needs connections:write. The response’s typed result contains an authentication ID, status, expiry and a hosted url when consent is required. The person opens that URL and chooses or connects the account. Act never accepts passwords, API keys or OAuth tokens. Only a verified connected status means authentication succeeded. Read the same thread after consent; do not create another attempt to poll it. Use this Act message for request-bound authentication. Read the same thread after hosted consent to verify its current state. Saved access can be managed through List auth credentials and Revoke auth credential.

Payment

The selected child’s state.requests includes a payment_request with immutable amount, currency, payee, accepted methods and expiry. Review those terms, then submit its exact request ID:
The typed result returns status: "selection_required", request, url, expiresAt and the effective idempotency key. The person opens the hosted URL to review the terms, choose an eligible method and authorize checkout. Calling Act opens selection; it does not charge or report settlement. No card data, bank details, method selector or provider credential belongs in this message. Read the same thread for verified payment state. Do not replay an uncertain payment with a new key. A hosted URL, saved method or accepted message is not a payment receipt. Use this Act message for request-bound payment selection. Manage saved methods through List payment methods and Revoke payment method. Saving a method requires explicit permission and never proves a charge.

Approvals and other replies

Use action_request to propose a capability invocation, action_confirmation to confirm its exact request, approval_confirmation with allow or deny for a reviewed permission, completion_confirmation to acknowledge delivery, and cancellation_request to request cancellation of an operation. Use IDs returned by Get act request. Plain text never substitutes for authentication, payment or approval. Every start checks current route availability and authorization. A Search listing alone does not prove a provider can execute the request. Authentication and payment request IDs must belong to the supplied thread; Act rejects a request from another thread.

Authorizations

x-api-key
string
header
required

Headers

Idempotency-Key
string
X-Search-Token
string
X-Act-Token
string

Private guest credential; never place it in messages or URLs.

Body

application/json
searchId
string
required
Pattern: ^srch_[a-f0-9-]{36}$
message
string
required
Required string length: 1 - 32000
agentIds
string[]
Required array length: 1 - 8 elements
Required string length: 1 - 200
Pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
arguments
object

Capability arguments keyed by agentId from the selected Search result. Omit for a text-only thread; operationId keys are invalid.

Response

A single thread receipt with threadId, or a typed thread continuation receipt. Use actRequestId with Get act request to read the thread.

type
string
required
Allowed value: "request"
actRequestId
string
required
Required string length: 1 - 200
Pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
searchId
string | null
required
Required string length: 1 - 200
Pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
status
enum<string>
required

Act Request handoff status only. Completed means thread receipts were created; read each thread for action confirmation and provider result.

Available options:
pending,
completed,
partial,
failed
createdAt
string<date-time>
required
Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
threads
object[]
required
Required array length: 1 - 8 elements
threadId
string

The one created thread. Omitted for historical failed or batch receipts.

Required string length: 1 - 200
Pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$
Last modified on October 30, 2026