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

# TypeScript SDK Reference

> Complete API reference for the DataGen TypeScript SDK

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @datagen-dev/typescript-sdk
  ```

  ```bash yarn theme={null}
  yarn add @datagen-dev/typescript-sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @datagen-dev/typescript-sdk
  ```
</CodeGroup>

Requires Node.js 18+ and TypeScript 5.0+.

## Client Configuration

```typescript theme={null}
import { DatagenClient } from '@datagen-dev/typescript-sdk';

const client = new DatagenClient({
    apiKey: undefined,       // Default: reads from DATAGEN_API_KEY env var
    baseUrl: "https://api.datagen.dev",
    timeout: 30000,          // Request timeout in ms
    retries: 0,              // Retry attempts for failed requests
    backoffSeconds: 0.5      // Initial backoff for retries
});
```

| Parameter | Type | Default | Description |
| - | - | - | - |
| `apiKey` | `string?` | `undefined` | API key. Falls back to `DATAGEN_API_KEY` env var |
| `baseUrl` | `string` | `"https://api.datagen.dev"` | DataGen API base URL |
| `timeout` | `number` | `30000` | Request timeout in milliseconds |
| `retries` | `number` | `0` | Number of retry attempts |
| `backoffSeconds` | `number` | `0.5` | Initial backoff time for retries |

***

## Tool Execution

### `executeTool`

Execute an MCP tool by its alias name.

```typescript theme={null}
const result = await client.executeTool(
    toolAliasName: string,
    parameters?: Record<string, any>
): Promise<any>
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `toolAliasName` | `string` | Yes | Tool alias (e.g., `"mcp_Gmail_gmail_send_email"`) |
| `parameters` | `Record<string, any>` | No | Tool-specific parameters |

**Returns:** Tool execution result.

**Throws:** `DatagenAuthError`, `DatagenToolError`, `DatagenHttpError`

***

## Custom Tool Deployment

### `deployCustomTool`

Deploy a Python workflow as an API endpoint.

```typescript theme={null}
const result = await client.deployCustomTool({
    name: string,
    code: string,
    description?: string,
    inputSchema?: Record<string, any>,
    outputVars?: string[],
    expectedTools?: string[],
    additionalImports?: string[],
    deploymentType?: "private" | "public",
    defaultInputVars?: Record<string, any>,
    mcpServerNames?: string[],
    requiredSecrets?: string[],
}): Promise<DeploymentResult>
```

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `name` | `string` | Yes | -- | API name for the tool |
| `code` | `string` | Yes | -- | Python code to deploy |
| `description` | `string` | No | -- | Tool description |
| `inputSchema` | `object` | No | -- | OpenAPI/JSON Schema for inputs |
| `outputVars` | `string[]` | No | -- | Output variable names |
| `expectedTools` | `string[]` | No | -- | Required MCP tools |
| `additionalImports` | `string[]` | No | -- | Python packages |
| `deploymentType` | `string` | No | `"private"` | `"private"` or `"public"` |
| `defaultInputVars` | `object` | No | -- | Default input values |
| `mcpServerNames` | `string[]` | No | -- | MCP server names |
| `requiredSecrets` | `string[]` | No | -- | Required secret names |

**Returns:** Object with `deploymentUuid` and deployment details.

**Throws:** `DatagenDeploymentError`

### `updateCustomTool`

Update an existing custom tool. Only provided fields are updated.

```typescript theme={null}
const result = await client.updateCustomTool(
    deploymentUuid: string,
    updates: {
        name?: string,
        description?: string,
        code?: string,
        inputSchema?: Record<string, any>,
        outputVars?: string[],
        defaultInputVars?: Record<string, any>,
        additionalImports?: string[],
        expectedTools?: string[],
        requiredSecrets?: string[],
    }
): Promise<DeploymentResult>
```

### `getCustomTool`

```typescript theme={null}
const result = await client.getCustomTool(deploymentUuid: string): Promise<DeploymentDetails>
```

### `listCustomTools`

```typescript theme={null}
const result = await client.listCustomTools({
    sortBy?: string,    // Default: "created_at"
    orderBy?: string,   // Default: "desc"
    skip?: number,      // Default: 0
    limit?: number,     // Default: 100
}): Promise<DeploymentDetails[]>
```

***

## Custom Tool Execution

### `runCustomTool`

Run synchronously (blocks until complete).

```typescript theme={null}
const result = await client.runCustomTool(
    deploymentUuid: string,
    inputVars?: Record<string, any>,
    executionTimeout?: number    // Default: 120
): Promise<RunResult>
```

### `runCustomToolAsync`

Run asynchronously (returns immediately).

```typescript theme={null}
const result = await client.runCustomToolAsync(
    deploymentUuid: string,
    inputVars?: Record<string, any>,
    executionTimeout?: number    // Default: 120
): Promise<{ runUuid: string, status: "pending" }>
```

### `checkRunStatus`

```typescript theme={null}
const result = await client.checkRunStatus(runUuid: string): Promise<RunStatus>
```

### `getRun`

```typescript theme={null}
const result = await client.getRun(runUuid: string): Promise<RunResult>
```

### `waitForRun`

Poll until an async run completes.

```typescript theme={null}
const result = await client.waitForRun(
    runUuid: string,
    timeout?: number,        // Default: 300
    pollInterval?: number    // Default: 2.0
): Promise<RunResult>
```

***

## Secret Management

### `listSecrets`

```typescript theme={null}
const result = await client.listSecrets(): Promise<SecretMetadata[]>
```

### `setSecret`

```typescript theme={null}
const result = await client.setSecret({
    name: string,
    value: string,
    displayName?: string,
    description?: string,
    category?: string,     // Default: "api_key"
    force?: boolean,       // Default: false
}): Promise<SecretMetadata>
```

***

## Error Types

```typescript theme={null}
import {
    DatagenClient,
    DatagenError,
    DatagenAuthError,
    DatagenToolError,
    DatagenHttpError,
    DatagenDeploymentError,
    DatagenSecretError,
} from '@datagen-dev/typescript-sdk';
```

| Exception | Description |
| - | - |
| `DatagenError` | Base exception class |
| `DatagenAuthError` | Authentication failed (401/403) |
| `DatagenToolError` | Tool execution failed |
| `DatagenHttpError` | HTTP-level errors |
| `DatagenDeploymentError` | Deployment or run failed |
| `DatagenSecretError` | Secret management errors |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.