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

# TypeScript SDK

> Run prompts and workflows, manage knowledge bases, and verify webhooks from TypeScript.

The PromptJuggler TypeScript SDK is a thin, typed wrapper over the public REST API. You
call flat, async methods and get back typed objects — authentication, request building,
and JSON (de)serialization are handled for you. It runs in Node.js and any runtime with a
global `fetch`.

## Requirements

* Node.js 22 or newer

## Installation

```bash theme={null}
npm install @promptjuggler/sdk
```

## Set up the client

Create an API key in [Settings](https://promptjuggler.com/settings), then construct the
client once and reuse it:

```ts theme={null}
import { PromptJuggler } from '@promptjuggler/sdk';

const pj = new PromptJuggler('your-api-key');
```

The key is sent as a Bearer token to `https://promptjuggler.com`. Point the SDK at another
host (e.g. for testing) with the `baseUrl` option, or inject a custom `fetch`.

## Per-endpoint usage

Every endpoint in the [API reference](/api/overview) includes a **TypeScript SDK** code
sample showing the exact call — that's the place to look for how to invoke each operation
and what it returns. A typical flow:

```ts theme={null}
import { RunStatus } from '@promptjuggler/sdk';

// Trigger a run (async — returns immediately with the run ID)
const created = await pj.runPrompt('greeting', 'production', { name: 'Ada' });

// Poll for the result
const run = await pj.getPromptRun(created.id);
if (run.status === RunStatus.Completed) {
  console.log(run.output);
}
```

<Note>
  Methods return generated model objects with typed fields. They are plain, read-only
  data — read the fields, don't write them back.
</Note>

## Error handling

When the API responds with an error status, the SDK throws an `ApiError` carrying the HTTP
status code and the server's message. When the request never reaches the API (DNS failure,
timeout, offline), it throws a `ConnectionError`. Both extend the `PromptJugglerError` base
class, so you can catch the whole surface at once.

```ts theme={null}
import { ApiError } from '@promptjuggler/sdk';

try {
  const run = await pj.getPromptRun('does-not-exist');
} catch (error) {
  if (error instanceof ApiError) {
    error.statusCode; // e.g. 404
    error.message; // the server's error message
  }
}
```

You never catch a generated-client error — the SDK translates the underlying client's
errors into its own.

## Webhooks

PromptJuggler signs every webhook with the `PromptJuggler-Signature` header. Verify it
against the **raw** request body, before any JSON parsing:

```ts theme={null}
import { verifyWebhookSignature } from '@promptjuggler/sdk';

const payload = await request.text(); // the raw body
const signature = request.headers.get('PromptJuggler-Signature') ?? '';

if (!(await verifyWebhookSignature(payload, signature, 'your-webhook-secret'))) {
  // reject the delivery (e.g. respond 403)
}

const event = JSON.parse(payload);
```

`verifyWebhookSignature` recomputes the HMAC-SHA256 of `{timestamp}.{raw_body}`, compares
it in constant time, and rejects deliveries whose timestamp falls outside a tolerance
window (default 300s) to prevent replay. Widen or narrow it with the `tolerance` argument.
It uses the Web Crypto API, so it runs in Node, edge runtimes, and browsers alike.