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

# API

> Use Search and explicit Action operations from REST, npm, or PyPI.

Darwin's primary public contract has seven focused endpoints:

* `POST /api/v2/search` finds executable public capabilities.
* `POST /api/v2/actions` starts durable work.
* `GET /api/v2/actions/{actionId}` gets its current state.
* `GET /api/v2/actions` lists current actions.
* `PATCH /api/v2/actions/{actionId}` updates an action.
* `POST /api/v2/actions/{actionId}/approve` applies an exact reviewed decision.
* `POST /api/v2/actions/{actionId}/stop` stops the current queued or running Turn.

The detailed goals, conversations, Turns, approvals, transactions, Host, and Account routes still support Darwin and compatibility clients. They are not part of the primary developer API.

<Warning>
  Keep API keys on a trusted server. Browser and mobile applications should use Darwin OAuth rather than embedding a
  server key.
</Warning>

## REST

```bash theme={null}
curl https://api.darwin.so/api/v2/search \
  -H "Authorization: Bearer $DARWIN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"query":"OCR for handwriting","limit":5}'
```

Use the returned `capabilityId` and `capabilityRevision` without re-searching from prose:

```bash theme={null}
curl https://api.darwin.so/api/v2/actions \
  -H "Authorization: Bearer $DARWIN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "capabilityId":"cap_456",
    "capabilityRevision":12,
    "inputs":{"file":"https://example.com/invoice.pdf"},
    "requestId":"req_123"
  }'
```

## npm

```bash theme={null}
npm install @darwinso/sdk
```

```typescript theme={null}
import { DarwinClient } from '@darwinso/sdk';

const darwin = new DarwinClient({ token: process.env.DARWIN_API_KEY! });
const found = await darwin.search({ query: 'OCR for handwriting' });
const outcome = await darwin.startAction({
  capabilityId: found.results[0].capabilityId,
  capabilityRevision: found.results[0].capabilityRevision,
  inputs: { file: 'https://example.com/invoice.pdf' },
  requestId: 'req_123',
});
```

## PyPI

```bash theme={null}
pip install darwin-sdk
```

```python theme={null}
from darwin_sdk import Darwin

darwin = Darwin(token="YOUR_DARWIN_API_KEY")
found = darwin.search(request={"query": "OCR for handwriting"})
outcome = darwin.start_action(
    capability_id=found.results[0].capability_id,
    capability_revision=found.results[0].capability_revision,
    inputs={"file": "https://example.com/invoice.pdf"},
    request_id="req_123",
)
```

## Action operations

Use `startAction`, `getAction`, `listActions`, `updateAction`, `approveAction`, or `stopAction` in TypeScript and the matching snake-case names in Python. Mutations require a stable `requestId`. An approval requires the exact revision and payload digest returned by Get action; stale or changed approvals fail closed.

See the [API Reference](/docs/reference/introduction) for the complete request and response schemas.