> For the complete documentation index, see [llms.txt](https://docs.fastn.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fastn.ai/reference/sdk.md).

# SDK

Call the fastn platform from your backend with the fastn SDK: install, set up the client, and learn the ids.

The fastn SDK is the fastn platform API as a library for your backend. It is for Node.js and TypeScript: `@fastn-ai/sdk` (version 0.5.1). A Python SDK, `fastn-ai` (also 0.5.1), offers the same client as `fastn.platform.FastnClient`, with `fastn.customer(ref)` for one customer; this section shows the Node.js SDK. You call normal typed methods (`customer.calendar.book(…)`, `customer.crm.contacts.find(…)`), you get plain objects back, and failures come back as typed errors. The SDK also picks the app the customer connected, and handles customer ids, retries and event signatures for you.

Use it from your **backend**. It needs your fastn API key, which must never reach a browser.

{% hint style="info" %}
This is not the widget SDK. `@fastn-ai/sdk` runs on your server and calls the fastn API. The browser package that shows the connect widget inside your app is `@fastn-ai/embed`: see [Embedding the widget: SDK](https://docs.fastn.ai/embed/embedding/sdk.md).
{% endhint %}

***

## Install

```bash
npm install @fastn-ai/sdk
```

| Item    | Value                                                                                                            |
| ------- | ---------------------------------------------------------------------------------------------------------------- |
| Runtime | Node.js 20 or newer. The SDK uses the built-in `fetch`.                                                          |
| Modules | ESM and CommonJS. TypeScript types are included.                                                                 |
| API key | Create one on [Embed → API keys and MCP](https://docs.fastn.ai/embed/api-keys.md). Keep it in your secret store. |

***

## Create the client

Create one client when your app starts, and reuse it. It caches the lookups it makes.

```typescript
import { FastnClient } from "@fastn-ai/sdk";

const fastn = new FastnClient({ apiKey: process.env.FASTN_API_KEY! });

// One object per customer, named by YOUR id for that customer
const customer = fastn.customer("acme_customer_42");
```

| Option               | Required | Meaning                                                                                                                                                                                                            |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `apiKey`             | Yes      | Your fastn API key. The SDK sends it on every call.                                                                                                                                                                |
| `baseUrl`            | No       | The API address. Default `https://api.fastn.dev`.                                                                                                                                                                  |
| `timeoutMs`          | No       | Time limit per request, in milliseconds. Default 60000.                                                                                                                                                            |
| `retries`            | No       | How many times a safe call is retried (see [Errors, retries and options](https://docs.fastn.ai/reference/sdk/errors-and-options.md)). Default 2.                                                                   |
| `defaults`           | No       | [Request options](https://docs.fastn.ai/reference/sdk/errors-and-options.md#request-options) applied to every call, for example `{ customer: { ref: "acme_customer_42" } }` to tie a whole client to one customer. |
| `onRequest`          | No       | A function called after every HTTP attempt, for your logs. It gets the operation, method, URL, status, duration, attempt number and request id. It never gets the API key.                                         |
| `tools`              | No       | Only for the optional [workspace tools](https://docs.fastn.ai/reference/sdk/workspace-tools.md) route.                                                                                                             |
| `fetch`, `userAgent` | No       | Your own `fetch` implementation, and a custom user agent.                                                                                                                                                          |

### Check the key

```typescript
const me = await fastn.me();
console.log(me.role, me.org?.id);
```

`fastn.me()` answers who the key is: `actor` (`api_key`), `role`, `org` (`id`, `name`, `type`, `externalRef`), `parentOrg`, `environment`, `permissions` and `apiKey` (`mode`, `environment`). The answer is cached for the life of the client.

***

## Your customers and their ids

You are the SaaS company using fastn; each business you serve is a **customer**. Each customer gets its own connections, records and events. See [Understanding tenancy](https://docs.fastn.ai/embed/embedding/understanding-tenancy.md) for the model.

You name each customer with **your own id**, for example the id it has in your database, and use it everywhere: `fastn.customer("acme_customer_42")`. Answers name the customer by your id too, as `orgId`.

{% hint style="warning" %}
To act for your customers, use a key that can act for your customers (one not pinned to a single customer).
{% endhint %}

### Every id you will see

| Id                              | Example                     | What it is                                                                                                                                                              | Who makes it                      |
| ------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| Your customer id                | `acme_customer_42`          | Your own id for a customer. Use it everywhere. The API calls it `orgId`; customer answers also show it as `externalRef`, and events as `tenantRef`: all the same value. | You                               |
| fastn's own id for the customer | `7c9e6679-…` (a UUID)       | Comes back as `id` in customer answers. You never need it: wherever the API takes a customer, your customer id (`acme_customer_42`) works.                              | fastn                             |
| `widgetId`                      | `wgt_…`                     | A widget: which apps a setup link or the embedded widget offers.                                                                                                        | You, in the dashboard             |
| `setupId`                       | `stp_…`                     | One setup link.                                                                                                                                                         | fastn                             |
| `installationId`                | `inst_…`                    | The finished setup made from a setup link or the widget.                                                                                                                | fastn                             |
| `connectionId`                  | `ucl:…:default`             | One connected account, for example one Google Calendar of one customer.                                                                                                 | fastn, when the customer connects |
| `connectorId`                   | a UUID                      | One app (connector) in the catalog.                                                                                                                                     | fastn                             |
| Connector slug                  | `hubspot`, `googleCalendar` | The app's short name. Used as `provider` and `connector` in calls.                                                                                                      | fastn                             |
| Action slug                     | `getContact`                | One action of an app.                                                                                                                                                   | fastn                             |
| Record id                       | `51234567890`               | A record (contact, meeting, deal) in the app itself.                                                                                                                    | The app                           |
| Subscription id                 | `esub_…`                    | One event subscription (your webhook).                                                                                                                                  | fastn                             |
| Delivery id                     | `evd_…`                     | One delivery of one event to your webhook.                                                                                                                              | fastn                             |
| Event id                        | `evt_…`                     | One event. It stays the same across retries.                                                                                                                            | fastn                             |
| Webhook secret                  | `whsec_…`                   | Signs the events fastn sends you. Shown once.                                                                                                                           | fastn                             |
| `idempotencyKey`                | `booking_123`               | Your key that makes a write safe to retry.                                                                                                                              | You                               |
| `correlationId`                 | `req_abc`                   | Your id for a request, to trace what fastn did for it.                                                                                                                  | You                               |
| `requestId`                     | from the error              | The id fastn gave one failed request. Quote it when you ask for help.                                                                                                   | fastn                             |

***

## What you get back

The generated methods (`fastn.<area>.<operation>()`) return answers exactly as the REST API sends them. The convenience methods reshape them for you:

* `fastn.webhooks.*` unwraps `data` and returns the subscription (or list) itself.
* `customer.connect(app)` returns `{ setupId, url, status, expiresAt, widgetId }`.
* `customer.links.get()` and `.cancel()`, `customer.callLog()` and `customer.watch()` return the item itself, without the `data` wrapper.
* `customer.find()` returns the customer row, or `undefined` when there is none.

Raw answers from the generated methods look like this:

| Kind of call                             | Answer                                                                                                                                         |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Customers, links, connections, events    | `{ data: { … } }` for one item, `{ data: [ … ] }` for a list. Some lists add `pagination` or `meta`.                                           |
| One unified record (create, get, update) | `{ id, provider, data: { …fields } }`. `id` is the record's id in the app.                                                                     |
| A list of unified records (list, search) | `{ records: [ { id, provider, data } ], nextCursor, hasMore, provider }`                                                                       |
| A failure                                | A thrown `FastnApiError` or `FastnNetworkError`. See [Errors, retries and options](https://docs.fastn.ai/reference/sdk/errors-and-options.md). |

Fields of unified records and their list options use `snake_case` (`start_time`, `page_size`). Everything else uses `camelCase` (`widgetId`, `connectionId`, `idempotencyKey`).

***

## The pages in this section

| Page                                                                                     | Covers                                                                                                                                            |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Build an integration, end to end](https://docs.fastn.ai/reference/sdk/end-to-end.md)    | One complete integration in the order you build it: set up once, onboard a customer, the calls during a conversation, events, retries and errors. |
| [Customers](https://docs.fastn.ai/reference/sdk/customers.md)                            | Register, find, read, list, change and remove customers.                                                                                          |
| [Connecting apps](https://docs.fastn.ai/reference/sdk/connecting-apps.md)                | Widgets, setup links, redirect addresses, embed tokens, and the connections a customer made.                                                      |
| [Unified records](https://docs.fastn.ai/reference/sdk/unified-records.md)                | One set of methods for every app: create, get, list, search, update and delete records, and how to find the fields.                               |
| [Calendar and CRM](https://docs.fastn.ai/reference/sdk/calendar-and-crm.md)              | The typed methods: free slots, book, find and cancel meetings; contacts, notes, tasks and deals.                                                  |
| [Direct app actions](https://docs.fastn.ai/reference/sdk/app-actions.md)                 | Run an app's own action when the unified API does not cover what you need.                                                                        |
| [Events](https://docs.fastn.ai/reference/sdk/events.md)                                  | Register your webhook, receive signed events, and watch a customer's app for changes.                                                             |
| [Errors, retries and options](https://docs.fastn.ai/reference/sdk/errors-and-options.md) | Retry keys, tracing, time limits, and the errors to handle.                                                                                       |
| [Workspace tools](https://docs.fastn.ai/reference/sdk/workspace-tools.md)                | The optional route: run your workspace's MCP tools by name, or generate typed methods for them.                                                   |
| [Any other operation](https://docs.fastn.ai/reference/sdk/any-operation.md)              | Every other API operation, by name.                                                                                                               |

The SDK has one method for every operation your key can call, under an area such as `fastn.orgs`, `fastn.embed`, `fastn.connections`, `fastn.unified`, `fastn.events` or `fastn.connectors`. Each method has the same name as the operation. For the plain HTTP calls, see [HTTP API](https://docs.fastn.ai/reference/api.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.fastn.ai/reference/sdk.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
