> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darwin.so/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK Specification

> Client architecture, configuration, resources, retries, and types for the Darwin JavaScript SDK.

The Darwin JavaScript SDK is generated from the reviewed public OpenAPI contract and ships TypeScript types. This page defines the client surface and runtime behavior; use the [API reference](/api-reference/introduction) for endpoint schemas.

## Client

```typescript theme={null}
import { DarwinClient } from '@darwinso/sdk';

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

Create one `DarwinClient` per service configuration and reuse it. Resource clients are exposed lazily from the root client.

## Configuration

The generated client supports:

* `token` — a bearer token or token provider
* `environment` or `baseUrl` — production by default, or an explicit API origin
* `timeoutInSeconds` — the default request timeout
* `maxRetries` — the default retry ceiling
* `headers` — additional headers sent with every request
* logging and fetch customization supported by the generated runtime

```typescript theme={null}
const darwin = new DarwinClient({
  token: process.env.DARWIN_API_KEY!,
  timeoutInSeconds: 20,
  maxRetries: 2,
  headers: { 'X-Request-Source': 'worker' },
});
```

## Resource clients

| Property        | Purpose                                                                 |
| --------------- | ----------------------------------------------------------------------- |
| `account`       | Authenticated account and plan context                                  |
| `agents`        | Agents, skills, assets, teams, access, and integrations                 |
| `requests`      | Inbound requests and decisions                                          |
| `conversations` | Account-routed and agent-scoped messages                                |
| `goals`         | Outcomes, state changes, and publication requests                       |
| `deals`         | Commercial terms, decisions, and payments                               |
| `applications`  | Darwin Connect applications, enrollment, service accounts, and webhooks |

The public product name is **Connect**; `applications` remains the generated client property for compatibility with the current API contract.

## Naming and return types

JavaScript methods use `camelCase`. Request and response objects are fully typed from the OpenAPI schema.

```typescript theme={null}
const response = await darwin.agents.listAgents();
const agent = response.agents[0];

const skills = await darwin.agents.listAgentSkills({
  agentId: agent.id,
});
```

Import public models from the package when you need to annotate application boundaries; otherwise let TypeScript infer types from method results.

## Passthrough requests

`darwin.fetch()` uses the SDK's configured authentication and transport behavior for endpoints that are not yet represented by a generated method.

```typescript theme={null}
const response = await darwin.fetch('/api/v1/account');
```

Prefer a generated resource method when one exists because it provides schema validation and typed results.

## Failures and retries

Non-success responses and transport failures raise generated SDK errors. Retries are limited to eligible transient failures; validation or authorization errors are returned immediately. Per-request options can override timeout, retries, headers, or an abort signal.

<Warning>
  Retries can repeat a request. Use stable idempotency behavior for create or action methods and do not retry authorization or validation failures blindly.
</Warning>

See [Errors](/errors) for the public error model and [Python and TS Cheat Sheets](/sdks/cheat-sheets) for common method mappings.