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

> Start durable work from an exact Search result and follow it to a truthful outcome.

Act begins with the exact capability revision selected through Search. It returns a stable `actionId` that remains the handle while work runs, pauses, resumes, or stops.

## Six Act components

<CardGroup cols={2}>
  <Card title="Communicate" href="/docs/act/messaging">
    Exchange information through Darwin Proxy. This does not approve, pay, grant account access, or prove a claim.
  </Card>

  <Card title="Onboard" href="/docs/act/sign-up">
    Create a new destination-provider account. This does not grant access to an existing account or accept unrelated terms.
  </Card>

  <Card title="Authenticate" href="/docs/act/connections">
    Grant bounded access to an existing provider account. This does not create an account, approve, pay, or verify.
  </Card>

  <Card title="Pay" href="/docs/act/payments">
    Complete a purchase bound to exact commercial terms. This does not approve changed terms or widen provider access.
  </Card>

  <Card title="Approve" href="/docs/act/approvals">
    Bind a decision to the exact review shown. This does not approve another revision, payload, or interaction.
  </Card>

  <Card title="Verify" href="/docs/act/verify">
    Establish whether a specific claim is supported. This does not grant permission to act, spend, or access an account.
  </Card>
</CardGroup>

The components compose without collapsing into one another. An Action may communicate before it asks a user to sign up, authenticate, pay, approve, or verify something, but each authority-bearing step remains explicit.

## Start from the selected revision

Create one stable `requestId` for this logical mutation. Reuse it only when retrying the identical request.

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const action = await darwin.startAction({
      capabilityId: selected.capabilityId,
      capabilityRevision: selected.capabilityRevision,
      inputs: { file: 'https://example.com/invoice.pdf' },
      requestId: crypto.randomUUID(),
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from uuid import uuid4

    action = darwin.start_action(
        capability_id=selected.capability_id,
        capability_revision=selected.capability_revision,
        inputs={"file": "https://example.com/invoice.pdf"},
        request_id=str(uuid4()),
    )
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.darwin.so/api/v2/actions \
      -H "x-api-key: $DARWIN_API_KEY" \
      -H "Content-Type: application/json" \
      --data '{
        "capabilityId":"cap_456",
        "capabilityRevision":12,
        "inputs":{"file":"https://example.com/invoice.pdf"},
        "requestId":"invoice-1042-start"
      }'
    ```
  </Tab>
</Tabs>

The credential needs `agent:write`. Starting work does not grant standing permission for later signup, authentication, payment, approval, or verification decisions.

## Store the Action ID

Persist `actionId` immediately. Keep it with the original query, selected capability revision, and your own record identifier.

```typescript theme={null}
await actions.save({
  orderId: 'invoice-1042',
  actionId: action.actionId,
  capabilityId: selected.capabilityId,
  capabilityRevision: selected.capabilityRevision,
});
```

## Read the current state

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const current = await darwin.getAction({
      actionId: action.actionId,
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    current = darwin.get_action(action.action_id)
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.darwin.so/api/v2/actions/action_123 \
      -H "x-api-key: $DARWIN_API_KEY"
    ```
  </Tab>
</Tabs>

Render `status`, `summary`, `actionRequired`, `availableActions`, and any typed interaction as supplied. Do not infer completion from elapsed time, a redirect, or a closed popup.

## Route the next step

| Current response                      | What your client should do                                                    |
| ------------------------------------- | ----------------------------------------------------------------------------- |
| `availableActions` contains `update`  | Ask for the missing input and continue through [Communicate](/docs/act/messaging). |
| `availableActions` contains `approve` | Present the exact review and collect one explicit decision.                   |
| `webLink` is present                  | Open the first-party Darwin flow after a user gesture.                        |
| status is `running`                   | Poll Get action with bounded exponential backoff.                             |
| status is `completed` or `stopped`    | Stop polling and render the terminal result.                                  |

<Warning>
  Always route from `availableActions`. A status label alone does not grant permission to mutate the Action.
</Warning>

## Follow long-running work

Persist `actionId`, poll Get action with bounded backoff while the Action is `running`, and pause automatic polling when a person must act. Resume from the same Action after the bound interaction is confirmed.

The current public contract does not expose an Action subscription, webhook, or server-sent event stream. If event delivery is added later, treat it only as a signal to read the latest Action again; `availableActions` remains authoritative.

Next, open the component that matches the Action's current need. Start with [Communicate](/docs/act/messaging) when the Action is asking for information.