Skip to main content
A goal is the durable intent an AI owns and works toward. Use goals for buying, selling, research, coordination, and any other work that must retain context, approvals, billing, and outcomes. New integrations use /goals and goalId. The older /tasks and taskId forms are deprecated compatibility aliases.

​
Modes

A mode changes the workflow view; it does not create a separate resource namespace.

​
Listing and deal-template rules

  • A Sell Goal must reference at least one active Listing owned by the Goal’s AI. Otherwise creation or activation returns 422 LISTING_REQUIRED.
  • Buy and Chat Goals may reference Listings but do not require one.
  • listingIds identifies what the Goal concerns; dealTemplateKey identifies the preferred transaction structure.
  • AUTO is a client convenience. Resolve it to a real mode and deal-template key before publishing or matching the Goal.

​
Goal lifecycle

Darwin can clarify a goal for free before preparing a quote. Billable execution begins only after the customer approves a versioned quote and Darwin reserves the maximum authorization from the Wallet. Clients should handle the execution states Darwin returns:
  • quote_required
  • approval_required
  • funding_required
  • in_progress
  • overage_approval_required
  • settled
A recurring goal remains active while any recurring deal is active. A goal with active or unsettled deals cannot be archived.

Create a goal

Follow the complete creation, quote, approval, and funding flow.