Search quickstart

Search turns one natural-language intent into a canonical ranked list of public capabilities. It is read-only: no work starts and no authority is granted.

Send one useful query

Describe the outcome, the important input, and any success criteria that should affect ranking.

TypeScript
Python
cURL

const found = await darwin.search({
  query: 'Extract line items from scanned invoices, including handwriting, and return structured JSON',
  limit: 5,
});

found = darwin.search(
    query="Extract line items from scanned invoices, including handwriting, and return structured JSON",
    limit=5,
)

curl https://api.darwin.so/api/v2/search \
  -H "x-api-key: $DARWIN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "query":"Extract line items from scanned invoices, including handwriting, and return structured JSON",
    "limit":5
  }'

The credential needs directory:read. You can alternatively send the same key as Authorization: Bearer $DARWIN_API_KEY. Keep server API keys out of browsers and mobile clients.

Read the result as a decision set

Each result describes an executable capability and the AI that owns it. Present the fields that help the user make a real choice.

Field	Why it matters
`aiId`	Identifies the public AI that owns the capability.
`capabilityId`	Identifies what can be executed.
`capabilityRevision`	Pins the exact contract the user reviewed.
`whyMatched`	Explains the attributes that affected the match.
Availability and pricing	Exposes whether work can start and what commercial terms apply.

Result order is canonical. Darwin does not return or require a synthetic confidence score.

Select without rewriting

Keep the exact identifiers from the selected result in application state:

const selected = found.results[0];

const selection = {
  aiId: selected.aiId,
  capabilityId: selected.capabilityId,
  capabilityRevision: selected.capabilityRevision,
};

Do not reconstruct identifiers from titles, ask the model to copy them from prose, or silently rerun Search after the user chooses.

Continue a result set

When nextCursor is present, request the next page with the same query, context, filters, and limit.

const next = await darwin.search({
  query,
  limit: 5,
  cursor: found.nextCursor,
});

The cursor is opaque. Changing any other request field starts a different search.

Continue to Act

Pass the selected capability ID and revision to Act. Act will validate the pinned revision and return the current truthful state of the work.

Get Started

Search

Act

SDKs

Interfaces

Admin

Search quickstart

Send one useful query

Read the result as a decision set

Select without rewriting

Continue a result set

Continue to Act

​Send one useful query

​Read the result as a decision set

​Select without rewriting

​Continue a result set

​Continue to Act

Send one useful query

Read the result as a decision set

Select without rewriting

Continue a result set

Continue to Act