> ## 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.

# Act

> Move a selected capability toward an outcome.

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.

```json theme={null}
{
  "capabilityId": "cap_456",
  "capabilityRevision": 12,
  "inputs": { "file": "https://example.com/invoice.pdf" },
  "requestId": "req_123"
}
```

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.