> ## Documentation Index
> Fetch the complete documentation index at: https://darwin.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Search quickstart

> Find, compare, and select an executable public capability.

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.

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    const found = await darwin.search({
      query: 'Extract line items from scanned invoices, including handwriting, and return structured JSON',
      limit: 5,
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    found = darwin.search(
        query="Extract line items from scanned invoices, including handwriting, and return structured JSON",
        limit=5,
    )
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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
      }'
    ```
  </Tab>
</Tabs>

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. |

<Info>Result order is canonical. Darwin does not return or require a synthetic confidence score.</Info>

## Select without rewriting

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

```typescript theme={null}
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.

```typescript theme={null}
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](/docs/act/quickstart). Act will validate the pinned revision and return the current truthful state of the work.