API

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.

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

REST

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:

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

npm install @darwinso/sdk

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

pip install darwin-sdk

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 for the complete request and response schemas.

Getting Started

Tools

REST

npm

PyPI

Action operations

​REST

​npm

​PyPI

​Action operations

REST

npm

PyPI

Action operations