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, important input, and 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',
  category: 'document intelligence',
  objective: 'Return validated JSON with every line item',
  numResults: 5,
});

found = darwin.search(
    query="Extract line items from scanned invoices, including handwriting, and return structured JSON",
    category="document intelligence",
    objective="Return validated JSON with every line item",
    num_results=5,
)

curl https://api.darwin.so/api/v2/search \
  -H "Content-Type: application/json" \
  --data '{
    "query":"Extract line items from scanned invoices, including handwriting, and return structured JSON",
    "category":"document intelligence",
    "objective":"Return validated JSON with every line item",
    "numResults":5
  }'

Success: Darwin returns ranked public capabilities. No credential is required at the anonymous limit, and no work has started.

Review the ranked results

Keep the returned agents and each agent’s nested capabilities in their canonical order. Compare names, descriptions, categories, readiness, and input fields without inventing a confidence score.Success: the user selects one agent and capability. numResults accepts 1 through 50 and defaults to 10.

Keep the exact selection

Store identifiers directly from the selected result:

const selectedAgent = found.agents[0];
const selectedCapability = selectedAgent.capabilities[0];

const selection = {
  targetAgent: selectedAgent.agent,
  capability: selectedCapability.capability,
};

Success: later operations use the original identifiers instead of reconstructed display text.

Authentication and Act readiness

Supply a key with directory:read in x-api-key or a matching bearer credential for the higher authenticated Search limit. Invalid credentials fail instead of falling back to anonymous access. Keep server API keys out of browsers and mobile clients. Search accepts only query, optional category and objective ranking hints, and optional numResults. It does not accept structured filters or a cursor. A ready result is still advisory: Darwin rechecks the selected route, input contract, and caller authority when you start work.

Get Started

Search

Act

Interfaces

Admin

Search quickstart

Authentication and Act readiness

​Authentication and Act readiness

Authentication and Act readiness