Plan

Assist turns an outcome into a proposed sequence of agent work. Use one Assist endpoint for every planning turn and Get assist request 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.

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.

{
  "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:

{
  "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. Use Update for changes after work has started.

Get Started

Navigator

Publish

Agents

Interfaces

Admin

Describe the outcome

Review the complete plan

Refine until it is right

Save and price the plan

​Describe the outcome

​Review the complete plan

​Refine until it is right

​Save and price the plan

Describe the outcome

Review the complete plan

Refine until it is right

Save and price the plan