> ## 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 a capability and revision returned by Search.

## 1. Start an action

```bash theme={null}
curl https://api.darwin.so/api/v2/actions \
  -H "Authorization: Bearer $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"
  }'
```

The credential needs `agent:write`. Generate one stable `requestId` for this logical mutation and reuse it only when retrying the same request.

## 2. Store the action ID

The response includes an `actionId`, truthful `status`, `result`, `actionRequired`, and `availableActions`. Persist the `actionId`; it is the durable handle for every later operation.

## 3. Follow the current state

```bash theme={null}
curl https://api.darwin.so/api/v2/actions/action_123 \
  -H "Authorization: Bearer $DARWIN_API_KEY"
```

If the status is nonterminal, render the supplied summary and use `availableActions` to decide which controls to show. Do not infer completion from elapsed time, a redirect, or a closed popup.

<CardGroup cols={2}>
  <Card title="Action lifecycle" icon="route" href="/docs/features/act/lifecycle">
    Handle every status and required next step.
  </Card>

  <Card title="Act API reference" icon="braces" href="/docs/reference/act-start">
    Inspect the six explicit Action operations.
  </Card>
</CardGroup>