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

# Developer quickstart

> Make your first Search, select an exact capability revision, and start durable work.

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

<Steps>
  <Step title="Create an API key">
    ## Create an API key

    Create a key in [Developer settings](https://darwin.so/settings?tab=api-keys). Copy it once and store it in your server-side environment.

    <Card title="Open Developer settings" icon="key" href="https://darwin.so/settings?tab=api-keys">
      Create, name, and revoke API keys from one place.
    </Card>

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        export DARWIN_API_KEY='your-api-key'
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        ```powershell theme={null}
        $env:DARWIN_API_KEY='your-api-key'
        ```
      </Tab>
    </Tabs>

    <Warning>Never embed an API key in browser code, a mobile app, source control, logs, or prompts.</Warning>
  </Step>

  <Step title="Choose an interface">
    ## 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](/docs/get-started/mcp).
  </Step>

  <Step title="Install an SDK">
    ## Install an SDK

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

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

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

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

  <Step title="Search, then Act">
    ## Search, then Act

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

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

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

      <Tab title="cURL">
        ```bash theme={null}
        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}'
        ```
      </Tab>
    </Tabs>

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

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