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

# SDK quickstart

> Install the SDK, connect your workspace and run your first request

This guide starts with a read request. Once your connection works, you can make an outbound call from a separate script.

<Steps>
  <Step title="Install the package">
    In your server project, run:

    ```bash theme={null}
    npm install famulor-sdk
    ```

    Use Node.js 22 or newer. The package supports TypeScript and JavaScript, with both ESM `import` and CommonJS `require`.
  </Step>

  <Step title="Create a workspace API key">
    Select the intended workspace in Famulor, open **Settings → API & MCP** and create a key. Copy it while the full value is visible; it is shown only once.

    The workspace needs **API Access** through its plan or an add-on. A dashboard-created key has full scopes; if your integration needs fewer permissions, see [API key hygiene](/api-reference/introduction#key-hygiene).
  </Step>

  <Step title="Store the key on your server">
    For local development, put the key in a `.env` file:

    ```dotenv theme={null}
    FAMULOR_API_KEY=fam_your_workspace_key
    ```

    Add `.env` to `.gitignore`. For hosted applications, use your host's secret manager or server environment settings. The SDK receives the key explicitly; it does not load `.env` files or choose a workspace automatically.
  </Step>

  <Step title="Read your assistants">
    Save this file as `sdk-read.mjs`:

    ```javascript sdk-read.mjs theme={null}
    import { Famulor } from 'famulor-sdk';

    if (!process.env.FAMULOR_API_KEY) {
      throw new Error('Set FAMULOR_API_KEY before running this script.');
    }

    const client = new Famulor({ apiKey: process.env.FAMULOR_API_KEY });
    const { data } = await client.assistants.list({ limit: 10 });

    for (const assistant of data) {
      console.log(assistant.id, assistant.name);
    }
    ```

    Run it with Node's environment-file support:

    ```bash theme={null}
    node --env-file=.env sdk-read.mjs
    ```

    An empty list is a successful connection when your workspace has no assistants yet. If the request fails, see [Troubleshooting](/sdk/reference#troubleshooting).
  </Step>
</Steps>

## Start one outbound call

Choose an active assistant and an outbound-capable phone number assigned to it. Use a destination you intend to call, in E.164 format such as `+4915123456789`.

<Warning>
  Running this next script places a real outbound call and can consume workspace credits. Replace both command arguments with your own assistant ID and intended destination.
</Warning>

Save this file as `sdk-call.mjs`:

```javascript sdk-call.mjs theme={null}
import { Famulor } from 'famulor-sdk';

if (!process.env.FAMULOR_API_KEY) {
  throw new Error('Set FAMULOR_API_KEY before running this script.');
}

const [assistantId, toNumber] = process.argv.slice(2);
if (!assistantId || !toNumber) {
  throw new Error('Usage: node sdk-call.mjs <assistant-id> <E.164-number>');
}

const client = new Famulor({ apiKey: process.env.FAMULOR_API_KEY });
const { data: call } = await client.calls.create({
  assistant_id: assistantId,
  to_number: toNumber,
});

console.log({ id: call.id, status: call.status });
```

```bash theme={null}
node --env-file=.env sdk-call.mjs <assistant-id> <E.164-number>
```

The response contains the created call's ID and initial status. A successful creation response does not mean the recipient has answered. Save the ID and read the result later:

```typescript theme={null}
const { data: call } = await client.calls.get('call-id');
console.log(call.status, call.summary);
```

Prefer the assistant's conversation-ended webhook for the final result; see [Webhooks](/assistants/webhooks). The CLI equivalents are:

```bash theme={null}
famulor create-call --assistant-id <assistant-id> --to-number <E.164-number>
famulor get-call <call-id>
```

## Use your own domain

For a white-label workspace, use the domain you sign in to and include `/api/v1`:

```typescript theme={null}
import { Famulor } from 'famulor-sdk';

const client = new Famulor({
  apiKey: process.env.FAMULOR_API_KEY,
  baseUrl: 'https://app.example.com/api/v1',
});
```

Each API key belongs to one workspace. Use a separate key and client for each workspace. A custom domain does not add permissions or change the API paths.

Continue with [Use the SDK](/sdk/usage) for pagination and complete API access, or [Configuration and errors](/sdk/reference) for reliable request handling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.