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

# Happy Scribe plugin

> Transcription, subtitle and meeting-notetaker platform with Happy Scribe - start transcriptions and translations, send the notetaker to meetings, export transcripts, read discovered contacts, and manage human-service orders.

Use **Happy Scribe** through Corsair: one client, typed API calls, and incoming webhooks.

Create an API key in Happy Scribe under My workspace, API access. Things to know before you call:

* **Credit-spending creates.** `transcriptions.create`, `translations.createTask` and `meetings.create` spend Happy Scribe credits. `orders.create` stays incomplete (unpaid) until `orders.confirm` or an explicit `confirm: true`; human orders are then irreversible.
* **Four async lifecycles.** Transcriptions report `state` until `automatic_done`; exports `state` until `ready` with a `download_link`; translation tasks `state` until `done`; meetings report `status` (a different field) until `completed`. The plugin declares jobs for all four, so the agent's get\_job follows them.
* **Rate limits.** The transcription-creation endpoint allows about 200 requests per user per hour; a 429 carries `retry_in_seconds` in the body and the plugin waits exactly that before retrying.
* **Pagination is inconsistent.** `transcriptions.list` pages from 0 with `perPage` default 5; `companies.list` and `people.list` page from 1 with `perPage` up to 100; `memberships.list` pages from 1, 25 at a time. All return `nextPageUrl` when another page exists.
* **Deleting.** `transcriptions.delete` moves the file to the Trash; pass `permanent: true` to delete it for good.
* **Intelligence API is enrollment-gated.** `companies`, `people` and the person/company filters on `transcriptions.list` answer 404 until the organization is enrolled; contact Happy Scribe support to enroll.
* **Local files.** `uploads.getSignedUrl` returns a pre-signed S3 URL; upload the file bytes there yourself, then pass a `tmpUrl` to `transcriptions.create`.
* **Webhooks.** Configure a meeting webhook in Settings, Webhooks and set its signing secret (`whsec_...`) as the plugin's `webhookSecret`. Deliveries are HMAC-signed twice; unsigned or stale deliveries are rejected. If your own route receives them, pass the raw body (`await request.text()`) to `processWebhook`, not `request.json()`: transcripts carry numbers like `0.0` that change when re-serialized, and the signature check then fails. The payload does not name the organization, so with multi-tenancy pass the tenant as `query.tenantId` (for example from `?tenantId=` on the endpoint URL).
* **Languages.** Language codes are BCP-47 (`en-GB`, `es`); human services are available only for some of them.

**What you get:**

* 28 typed API operations
* 7 incoming webhook event types

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/happyscribe better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/happyscribe better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/happyscribe better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/happyscribe better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { happyscribe } from '@corsair-dev/happyscribe';

export const corsair = createCorsair({
	plugins: [
		happyscribe(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> No setup required yet. When you make your first request as a tenant, Corsair prompts for the API key.
>
> ```ts theme={null}
> happyscribe()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'happyscribe',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**List transcriptions in an organization**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.happyscribe.api.transcriptions.list({ organizationId: 123, perPage: 25 });
```

**Transcribe media from a URL**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.happyscribe.api.transcriptions.create({
	organizationId: 123,
	name: 'My Interview',
	language: 'en-GB',
	tmpUrl: 'https://example.com/my_media.mp3',
});
```

See the full list on the [API](https://docs.corsair.dev/plugins/happyscribe/api.md) page.

## Webhooks

This plugin registers **7** webhook event types. Configure the provider to POST to your Corsair HTTP handler, then use `webhookHooks` on the plugin factory.

See [Webhooks](https://docs.corsair.dev/plugins/happyscribe/webhooks.md) for every event path and payload shape, and [Webhooks concept](https://docs.corsair.dev/concepts/webhooks.md) for routing.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/happyscribe/api.md)
>
> Every `happyscribe.api.*` operation with input and output types.

> [card] [Webhooks](https://docs.corsair.dev/plugins/happyscribe/webhooks.md)
>
> Event paths, payloads, and `webhookHooks` examples.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


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