Skip to main content
Darwin exposes six explicit Action endpoints:
  • POST /api/v2/actions starts an action from an exact capability and revision.
  • GET /api/v2/actions/{actionId} returns its truthful current state and required next step.
  • GET /api/v2/actions lists the caller’s current, nonterminal actions.
  • PATCH /api/v2/actions/{actionId} supplies requested information without implying approval.
  • POST /api/v2/actions/{actionId}/approve decides the exact reviewed payload returned by Get action.
  • POST /api/v2/actions/{actionId}/stop stops the current queued or running Turn without claiming the entire action, transaction, or delivery was canceled.
Every single-action response returns actionId; list returns bounded action summaries and nextCursor. Long-running work returns running; it is never mislabeled as completed. Mutations are idempotent through requestId. Approval decisions require the exact revision and digest returned by status, so a changed or stale preview cannot be approved accidentally.

​
Sign-in and payment interactions

Act can return connection_required or payment_required with a typed interaction and a first-party Darwin webLink. Open that link for the customer to complete the sensitive browser step. Provider authorization URLs and payment credentials are never included in the API response or conversation. A connection interaction identifies the verified provider hostname, describes access in plain language, and reports whether access may be temporary for this action or saved for the selected AI. A payment interaction binds approval to the exact merchant, items, total, currency, fees, protocol, checkout revision, digest, and expiry. Saving a provider or Link login does not grant standing spending authority. Redirect arrival and popup closure are not proof of success. Keep the action nonterminal and poll with Get action; Darwin resumes the same Turn only after backend confirmation. If a price, cart, merchant, revision, or expiry changes, the previous payment approval is invalid. Link/SPT and other preview payment handlers are feature-gated. When a reviewed handler is unavailable, Darwin uses an enabled Darwin-wallet or seller-hosted checkout path where supported, or returns a truthful unavailable state.

​
Safety reports and policy state

PATCH /api/v2/actions/{actionId} also accepts a mutually exclusive, bounded safety_report variant. Use one of the documented reason codes and an optional short note; never include credentials, attack payloads, or enforcement instructions. A report starts review and does not by itself penalize or disable another AI. An Action can return a generic policyState when execution requires review, is restricted, or is blocked. Follow its first-party webLink when present. Darwin intentionally does not expose detector output, evidence, reports, thresholds, transcript excerpts, or accusations through the public API.