Developer quickstart

Get an API key, install an SDK, then follow Darwin’s one core loop: Search → select → Act.

Create an API key

Create a key in Developer settings. Copy it once and store it in your server-side environment.

Open Developer settings

Create, name, and revoke API keys from one place.

macOS / Linux
Windows PowerShell

export DARWIN_API_KEY='your-api-key'

$env:DARWIN_API_KEY='your-api-key'

Never embed an API key in browser code, a mobile app, source control, logs, or prompts.

Choose an interface

Every interface uses the same capability IDs, revisions, Action states, and approval rules.

Interface	Best for	Authentication
TypeScript SDK	Node.js and TypeScript services	Server API key
Python SDK	Python services, AIs, and notebooks	Server API key
REST API	Any trusted backend	Server API key
MCP	AI assistants and coding agents	User-scoped OAuth

This guide continues with an SDK. For a compatible AI client, follow the MCP quickstart.

Install an SDK

TypeScript
Python

npm install @darwinso/sdk

import { DarwinClient } from '@darwinso/sdk';

const darwin = new DarwinClient({
  token: process.env.DARWIN_API_KEY!,
});

pip install darwin-sdk

import os
from darwin_sdk import Darwin

darwin = Darwin(token=os.environ["DARWIN_API_KEY"])

Search, then Act

Describe the outcome once. Preserve the exact capability revision the user selects, then use it to start durable work.

TypeScript
Python
cURL

const found = await darwin.search({
  query: 'OCR that handles handwriting and tables',
  limit: 5,
});

const selected = found.results[0];

const action = await darwin.startAction({
  capabilityId: selected.capabilityId,
  capabilityRevision: selected.capabilityRevision,
  inputs: { file: 'https://example.com/invoice.pdf' },
  requestId: crypto.randomUUID(),
});

console.log(action.actionId, action.status);

from uuid import uuid4

found = darwin.search(
    query="OCR that handles handwriting and tables",
    limit=5,
)
selected = found.results[0]

action = darwin.start_action(
    capability_id=selected.capability_id,
    capability_revision=selected.capability_revision,
    inputs={"file": "https://example.com/invoice.pdf"},
    request_id=str(uuid4()),
)

print(action.action_id, action.status)

curl https://api.darwin.so/api/v2/search \
  -H "x-api-key: $DARWIN_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"query":"OCR that handles handwriting and tables","limit":5}'

Search is read-only. Starting an Action requires agent:write; it can still pause before any connection, payment, or exact approval.

Keep the durable handle

Store actionId as soon as Start action returns. Read that same Action after a timeout, redirect, process restart, or out-of-band interaction. Only completed and stopped are terminal.

Get Started

Search

Act

SDKs

Interfaces

Admin

Developer quickstart

Create an API key

Open Developer settings

Choose an interface

Install an SDK

Search, then Act

Keep the durable handle

​Create an API key

Open Developer settings

​Choose an interface

​Install an SDK

​Search, then Act

​Keep the durable handle

Create an API key

Choose an interface

Install an SDK

Search, then Act

Keep the durable handle