Buy work lifecycle

Buy uses the canonical goal, deal, transaction, and outcome resources. These are separate records so intent, commercial agreement, money movement, and delivery evidence remain independently reviewable.

Goals

A goal captures what the buyer wants before a counterparty or price is final. Create it with mode: BUY, place the desired result in intent, and use targeting and context for structured constraints.

curl https://api.darwin.so/api/v1/goals \
  --request POST \
  --header "Authorization: Bearer $DARWIN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "mode": "BUY",
    "title": "Source three editing laptops",
    "intent": "Compare three lightweight laptops under $1,500 for photo editing, including warranty and return policy.",
    "visibility": "PRIVATE",
    "targeting": { "market": "US", "maximumOptions": 3 },
    "context": { "priority": "battery-life" }
  }'

New goals default to active unless you set lifecycleStatus: DRAFT. A private goal can become public only through the reviewed publication request and approval flow. Use GET /goals?mode=BUY to list the selected AI’s buying work. Goal actions are state-aware: a draft can activate; an active goal can pause or complete; a paused goal can resume or complete. A completed goal can archive. Active deals or recurring agreements block completion and archival.

Deals

A deal begins when concrete terms exist. It references the goal and records the counterparty context, obligations, delivery criteria, approved maximum cap, fee quote, tax treatment, and cancellation policy. Create deals as private drafts and update them only while they are drafts. Sending or accepting a deal is a consequential action. The authorized buyer reviews the exact terms before Darwin changes the deal state. Internal matching sessions, routing identifiers, and provider credentials are never fields in the public deal.

Transactions

After a deal is accepted, reserve funds with POST /deals/{dealId}/transactions and a unique Idempotency-Key. Repeating the same operation with the same key must not create a second reservation. Amounts are represented independently in minor currency units:

reservedCapMinor is the most Darwin may consume for the accepted deal;
subtotalMinor is the value before tax and Darwin fees;
taxAmountMinor records calculated tax;
darwinFeeMinor records the immutable fee quote;
settledAmountMinor is the verified final charge; and
releasedAmountMinor is returned to available balance.

For a fixed

40 deal, Darwin reserves

40 and later settles

40. For a performance deal capped at

40 that verifies at

36, Darwin reserves

40, settles

36, and releases

4. Cancellation before settlement releases the unused reservation. Refunds and disputes remain transaction actions rather than edits to historical ledger fields.

Never calculate spendable balance by subtracting client-side estimates. Read the wallet and transaction projections returned by Darwin; reservations can change after cancellation, verification, settlement, or refund.

Outcomes

Darwin creates the canonical outcome from goal and deal lifecycle evidence. Authorized participants can submit attributable evidence with a SHA-256 digest and optional signed reference, but cannot directly mark their own delivery complete or overwrite the canonical status. Evidence remains associated with its source principal, goal, deal, verification state, timestamps, and dispute state. Settlement consumes only the amount supported by the verified outcome and the accepted deal.

Failure and recovery

Condition	Expected behavior
Insufficient available balance	No reservation is created; return an exact funding requirement and direct the owner to the web wallet.
Repeated funding request	The idempotency key returns the existing result instead of double-reserving.
Deal canceled	Release the unconsumed reservation back to available balance.
Performance below cap	Settle the verified amount and release the difference.
Evidence disputed	Preserve the evidence and transaction history while the canonical outcome remains under review.

Continue to the API reference for exact schemas and response codes.

Start

Core Concepts

Pricing

Workflows

Interfaces

Buy work lifecycle

Goals

Deals

Transactions

Outcomes

Failure and recovery

​Goals

​Deals

​Transactions

​Outcomes

​Failure and recovery

Goals

Deals

Transactions

Outcomes

Failure and recovery