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

# TypeScript SDK

> Install @flowra/sdk and call tools, workflows, skills, and the generated raw client.

This guide walks through `@flowra/sdk` for Node.js backends. Overview and package status: [SDKs](/guides/sdk).

## Install

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

From the Flowra monorepo (if unpublished):

```bash theme={null}
cd sdks/typescript && pnpm install && pnpm build
# then depend on the local package from your app
```

## Create a client

```ts theme={null}
import { Flowra } from '@flowra/sdk';

const flowra = new Flowra({
  apiKey: process.env.FLOWRA_API_KEY!,
});
```

Options:

| Option         | Meaning                                   |
| -------------- | ----------------------------------------- |
| `apiKey`       | Project API key (`x-api-key`) — required  |
| `baseUrl`      | API origin (default `https://flowra.dev`) |
| `username`     | Optional external user (`x-username`)     |
| `throwOnError` | Throw on non-2xx (default `true`)         |

Scope to another end user without rebuilding options:

```ts theme={null}
const alice = flowra.asUser('customer_alice');
await alice.connections.list();
```

## List tools and run a workflow

```ts theme={null}
const tools = await flowra.tools.list({ limit: 10 });

const run = await flowra.workflows.run(workflowId, {
  input: { message: 'hello from the SDK' },
});
```

Execute a single tool by slug:

```ts theme={null}
const result = await flowra.tools.execute('slack_send_message', {
  arguments: { /* tool inputs */ },
  // connectedAccountId: '...', // when required
});
```

## Skills and MCP

```ts theme={null}
const skills = await flowra.skills.list();
const servers = await flowra.mcp.list();
```

## Knowledge (per end user)

```ts theme={null}
const forAlice = flowra.asUser('customer_alice');
const collections = await forAlice.knowledge.list();
```

See [Multi-tenancy](/guides/multi-tenancy) for when to pass `username`.

## Escape hatch: `flowra.raw`

Every API-key operation from the OpenAPI spec is on `flowra.raw` (generated). Use it when a facade helper is missing:

```ts theme={null}
import { Flowra } from '@flowra/sdk';

const flowra = new Flowra({ apiKey: process.env.FLOWRA_API_KEY! });

// Example: call a generated operation directly with the shared client
const res = await flowra.raw.toolsControllerGetTools({
  client: flowra.client,
  query: { limit: 5 },
});
```

Prefer the typed facade (`flowra.tools`, `flowra.workflows`, …) when it exists. Full HTTP detail: [API reference](/api-reference).

## Errors

With `throwOnError: true` (default), failed responses throw. Catch and inspect:

```ts theme={null}
try {
  await flowra.getProfile();
} catch (err) {
  console.error(err);
}
```

## Next

* [Python SDK](/guides/sdk-python)
* [Run a workflow](/recipes/run-a-workflow)
* [Connect an account](/recipes/connect-an-account)
* [API reference](/api-reference)