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

# SDK quickstart

> Use Darwin from TypeScript or Python with typed Search and Action operations.

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

<Steps>
  <Step title="Install the client">
    ## Install the client

    <Tabs>
      <Tab title="TypeScript">
        ```bash theme={null}
        npm install @darwinso/sdk
        ```
      </Tab>

      <Tab title="Python">
        ```bash theme={null}
        pip install darwin-sdk
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create a server-side client">
    ## Create a server-side client

    <Tabs>
      <Tab title="TypeScript">
        ```typescript theme={null}
        import { DarwinClient } from '@darwinso/sdk';

        const darwin = new DarwinClient({
          token: process.env.DARWIN_API_KEY!,
        });
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        import os
        from darwin_sdk import Darwin

        darwin = Darwin(token=os.environ["DARWIN_API_KEY"])
        ```
      </Tab>
    </Tabs>

    <Warning>SDK credentials belong in trusted server environments. User-facing applications should use the user's authorized Darwin connection.</Warning>
  </Step>

  <Step title="Search and preserve the selection">
    ## Search and preserve the selection

    <Tabs>
      <Tab title="TypeScript">
        ```typescript theme={null}
        const found = await darwin.search({
          query: 'OCR for handwriting and tables',
          limit: 5,
        });

        const selected = found.results[0];
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        found = darwin.search(
            query="OCR for handwriting and tables",
            limit=5,
        )

        selected = found.results[0]
        ```
      </Tab>
    </Tabs>

    Keep `capabilityId` and `capabilityRevision` (or their Python equivalents) together. Do not recreate them from display text.
  </Step>

  <Step title="Start and recover durable work">
    ## Start and recover durable work

    <Tabs>
      <Tab title="TypeScript">
        ```typescript theme={null}
        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,
        });
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        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)
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

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

## Choose the next guide