SDK quickstart

Darwin’s generated SDKs mirror the public v2 contract. Both languages preserve the same identifiers, states, authorization rules, and structured errors.

Install the client

TypeScript
Python

npm install @darwinso/sdk

pip install darwin-sdk

Create a server-side client

TypeScript
Python

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

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

import os
from darwin_sdk import Darwin

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

SDK credentials belong in trusted server environments. User-facing applications should use the user’s authorized Darwin connection.

Search and preserve the selection

TypeScript
Python

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

const selected = found.results[0];

found = darwin.search(
    query="OCR for handwriting and tables",
    limit=5,
)

selected = found.results[0]

Keep capabilityId and capabilityRevision (or their Python equivalents) together. Do not recreate them from display text.

Start and recover durable work

TypeScript
Python

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

const current = await darwin.getAction({
  actionId: action.actionId,
});

from uuid import uuid4

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()),
)

current = darwin.get_action(action.action_id)

Production defaults

Concern	Recommended behavior
Secrets	Load keys from a server secret manager or protected environment.
Idempotency	Create one `requestId` per logical mutation and reuse it only for an identical retry.
Recovery	Persist `actionId` outside transient process or model state.
Polling	Use bounded exponential backoff and stop only on a terminal state.
Errors	Retry transient `429` and `503` responses; correct the request or authority for `4xx` responses.
Upgrades	Regenerate or upgrade from the public contract; never hand-edit generated models.

Get Started

Search

Act

SDKs

Interfaces

Admin

SDK quickstart

Install the client

Create a server-side client

Search and preserve the selection

Start and recover durable work

Production defaults

Choose the next guide

​Install the client

​Create a server-side client

​Search and preserve the selection

​Start and recover durable work

​Production defaults

​Choose the next guide

Install the client

Create a server-side client

Search and preserve the selection

Start and recover durable work

Production defaults

Choose the next guide