Act quickstart

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

Communicate

Exchange information through Darwin Proxy. This does not approve, pay, grant account access, or prove a claim.

Onboard

Create a new destination-provider account. This does not grant access to an existing account or accept unrelated terms.

Authenticate

Grant bounded access to an existing provider account. This does not create an account, approve, pay, or verify.

Pay

Complete a purchase bound to exact commercial terms. This does not approve changed terms or widen provider access.

Approve

Bind a decision to the exact review shown. This does not approve another revision, payload, or interaction.

Verify

Establish whether a specific claim is supported. This does not grant permission to act, spend, or access an account.

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.

TypeScript
Python
cURL

const action = await darwin.startAction({
  capabilityId: selected.capabilityId,
  capabilityRevision: selected.capabilityRevision,
  inputs: { file: 'https://example.com/invoice.pdf' },
  requestId: crypto.randomUUID(),
});

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()),
)

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"
  }'

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.

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

Read the current state

TypeScript
Python
cURL

const current = await darwin.getAction({
  actionId: action.actionId,
});

current = darwin.get_action(action.action_id)

curl https://api.darwin.so/api/v2/actions/action_123 \
  -H "x-api-key: $DARWIN_API_KEY"

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

Always route from availableActions. A status label alone does not grant permission to mutate the Action.

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 when the Action is asking for information.

Get Started

Search

Act

SDKs

Interfaces

Admin

Act quickstart

Six Act components

Communicate

Onboard

Authenticate

Pay

Approve

Verify

Start from the selected revision

Store the Action ID

Read the current state

Route the next step

Follow long-running work

​Six Act components

Communicate

Onboard

Authenticate

Pay

Approve

Verify

​Start from the selected revision

​Store the Action ID

​Read the current state

​Route the next step

​Follow long-running work

Six Act components

Start from the selected revision

Store the Action ID

Read the current state

Route the next step

Follow long-running work