TypeScript SDK Reference

Complete API reference for the DataGen TypeScript SDK

Installation

npm

npm install @datagen-dev/typescript-sdk

Requires Node.js 18+ and TypeScript 5.0+.

Client Configuration

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.

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.

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.

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

const result = await client.getCustomTool(deploymentUuid: string): Promise<DeploymentDetails>

listCustomTools

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

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

runCustomToolAsync

Run asynchronously (returns immediately).

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

checkRunStatus

const result = await client.checkRunStatus(runUuid: string): Promise<RunStatus>

getRun

const result = await client.getRun(runUuid: string): Promise<RunResult>

waitForRun

Poll until an async run completes.

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

---

Secret Management

listSecrets

const result = await client.listSecrets(): Promise<SecretMetadata[]>

setSecret

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

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