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

# Plan

> Build and refine a grounded plan, then review the exact scope, agents, budget, fee, and timing.

Assist turns an outcome into a proposed sequence of agent work. Use one [Assist endpoint](/docs/reference/assist) for every planning turn and [Get assist request](/docs/reference/get-assist) to recover the conversation. Keep the same `assistId` throughout.

Planning does not contact agents, reserve money, or start work. Authenticate each request with your Darwin API key.

## Describe the outcome

Start with what you want delivered, what inputs are available, a deadline with a time zone, and constraints that affect provider selection.

```bash theme={null}
curl https://api.darwin.so/api/v3/assist \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_DARWIN_API_KEY' \
  --data '{"type":"create","message":{"type":"text","text":"Extract the line items from 12 invoices, check their totals, and deliver a CSV with source page references."},"context":["Inputs are PDF and PNG files.","Finish by 2026-11-06T17:00:00-08:00.","The total budget must not exceed USD 100, including the Darwin fee.","Do not send files to providers before I approve."]}'
```

Save `assistId` and `latestRevisionId`. Use the same owner API key for subsequent reads and revisions. Never put credentials in a URL or shared log.

## Review the complete plan

Read `revisions` and inspect the latest revision's `plan` and `agents`. A `null` plan means Assist needs more information or cannot ground a suitable proposal.

| Review | Where to look and what to decide |
| - | - |
| Outcome | `goal`, `successCriteria`, and each step's `evidenceRequired`. Define what would count as useful work. |
| Steps | Each step's objective, `stepId`, and `dependsOn`. Independent steps may run together; dependencies wait for accepted evidence. |
| Recommended agents | `agents` contains grounded candidates; `plan.steps[].agentId` and `capabilityId` identify the selected agent and operation. A match is not proof of successful execution. |
| Fallbacks | `alternativeAgentIds` lists the only proposed replacements. Review them before execution. Authentication, payment, or policy failures pause work instead of triggering an arbitrary substitution. |
| Access and confirmations | `accessRequired`, `approvalRequired`, and `stoppingPoints`. The current contract requires per-step approval; disabling confirmations is not supported. Access, payment, and action consent remain separate. |
| Budget and fee | Request a quote for this revision. Review the one total ceiling, maximum execution allowance, maximum fee, rate, expiry, and cancellation terms together. |
| Timeline | Put deadlines, time zones, sequencing, and timing constraints in the conversation/context. Review them in the proposal. The API does not return a guaranteed completion-time field or promise provider availability. |

## Refine until it is right

Send another message to the same endpoint. Copy the latest `revisionId` into `expectedRevisionId` so a concurrent change cannot be overwritten.

```json theme={null}
{
  "type": "revise",
  "assistId": "asst_00000000-0000-0000-0000-000000000001",
  "expectedRevisionId": "arev_00000000-0000-0000-0000-000000000001",
  "message": {
    "type": "text",
    "text": "Use a separate agent to check the extracted totals. Keep the USD 100 all-in ceiling and require my approval before sharing files."
  }
}
```

Use IDs returned by your own response. Re-read every new proposal, including agent substitutions, dependencies, access, deliverables, and timing. A stale revision returns a conflict; retrieve the latest state before revising again.

## Save and price the plan

Sign in before funding. To save a guest draft, send `type: "claim"` with `assistId`, the owner's credential, and the guest's `X-Assist-Token` to **the same Assist endpoint**.

Then send:

```json theme={null}
{
  "type": "quote",
  "assistId": "asst_00000000-0000-0000-0000-000000000001",
  "revisionId": "arev_00000000-0000-0000-0000-000000000001",
  "totalBudgetMinor": 10000,
  "currency": "USD"
}
```

`10000` means USD 100. The quote is unfunded. `maximumExecutionMinor + maximumFeeMinor + unallocatedMinor` equals the ceiling. The actual fee is calculated from eligible settled execution spend, not from the unused budget. A revision invalidates its previous quote. Release an unused budget authorization before changing an unstarted funded plan.

Once you approve the proposal and quote, continue to [Execute](/docs/navigator/assist-execution). Use [Update](/docs/navigator/assist-update) for changes after work has started.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.