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

# TypeScript SDK

> Trigger EigenPal workflows and agents from TypeScript with @eigenpal/sdk.

`@eigenpal/sdk` is the official TypeScript SDK. It is a typed wrapper over the
EigenPal API, generated from the OpenAPI spec. Source is open at
[github.com/eigenpal/sdk-typescript](https://github.com/eigenpal/sdk-typescript).

## Install

```bash theme={null}
npm i @eigenpal/sdk
```

Requires a TypeScript-aware runtime: Bun, Deno, Node 22+ (native TS), `tsx`,
Next.js, Vite, or any modern bundler. Plain `node script.js` will not work.

Get an API key from the dashboard under **Settings → API Keys**.

## Quick start

```ts theme={null}
import { EigenpalClient, EigenpalValidationError } from '@eigenpal/sdk';

const client = new EigenpalClient({ apiKey: process.env.EIGENPAL_API_KEY });

// Pass a File / Blob / { content, filename, mimeType }. The SDK uploads the
// request as multipart/form-data, no base64 needed. `waitForCompletion` holds
// the request open (up to N seconds) and returns the finished run.
const result = await client.run(
  'workflows.extract-invoice',
  { contract_document: file },
  { waitForCompletion: 60 }
);

if (result.finished) {
  console.log(result.output);
}
```

## Authentication

Pass the key explicitly, or set `EIGENPAL_API_KEY` and let the SDK pick it up:

```ts theme={null}
const client = new EigenpalClient({ apiKey: process.env.EIGENPAL_API_KEY });
```

The `apiKey` option always wins over the environment fallback.

## Starting runs

`client.run(target, input?, options?)` starts a workflow or agent. Targets are
strings like `workflows.extract-invoice` or `agents.invoice-agent`, or structured
objects like `{ type: 'workflow', slug: 'extract-invoice' }`. Pass
`{ waitForCompletion }` (seconds) to block until the run finishes and return its
output; omit it to enqueue the run and poll later with `client.runs.get(id)`.

## Self-hosted

Point the SDK at your own deployment:

```ts theme={null}
const client = new EigenpalClient({
  apiKey: process.env.EIGENPAL_API_KEY,
  baseUrl: process.env.EIGENPAL_BASE_URL ?? 'https://eigenpal.acme.internal',
});
```

`baseUrl` wins over the `EIGENPAL_BASE_URL` fallback and defaults to the hosted
cloud.

## Errors

Catch `EigenpalValidationError` when inputs do not match the workflow schema; it
carries the field-level detail so you can surface it to the caller.

See the [API reference](/api-reference) for the endpoints the SDK calls.