Overview

• A User-Agent is mandatory. tl;dv blocks default library agents before the key is read: a request sent as Python-urllib/3.11 gets a Cloudflare 403 with error code: 1010 and no JSON body. The plugin always sends Corsair-tldv-integration/1.0.
• The host is pasta.tldv.io, not api.tldv.io; the latter answers 404 for every /v1alpha1 path.
• API access depends on the organizer’s plan. Seeing a meeting in the web app does not grant API access: a meeting organized on a Free plan cannot be exported, and sharing does not change that. Organization-wide automation needs Enterprise.
• Two error shapes, split by status. A 400 carries { name: 'BadRequestError', message, errors: [{ property, constraints }] }; 401, 403, 404 and 500 carry { name, message }. The plugin throws a TldvAPIError. Its status is the HTTP status, its code is tl;dv’s name (for example NotFoundError) and its detail is the first constraint. error.name is always TldvAPIError, so compare error.code.
• Timestamps are ISO 8601 strings while duration and transcript offsets are numbers in seconds. duration can be fractional. The list endpoint itself answers happenedAt as a JavaScript date string (Tue Nov 10 2026 19:06:44 GMT+0000 (Coordinated Universal Time)); meetings.list converts it to ISO 8601 so it matches meetings.get.
• No recording download. GET /meetings/{id}/download answers a 302 to a signed URL, and the shared HTTP client follows redirects, so it would pull the whole file into memory. The meeting’s url field is the tl;dv web page for the meeting, not the media file. To get the recording, call GET https://pasta.tldv.io/v1alpha1/meetings/{id}/download yourself with the same x-api-key and User-Agent headers and redirects turned off, then read the signed URL from the Location header. It expires after 6 hours.
• Webhooks are not signed, so they carry a shared secret. tl;dv publishes no signature scheme for either trigger. The plugin accepts a delivery only when it carries your shared secret in an x-corsair-webhook-secret header, and it rejects every delivery when no secret is configured. tl;dv can send that header itself: in Integrations > Webhooks > Configure new webhook, set Authentication type to “API Key”, the header name to x-corsair-webhook-secret and the value to your secret. Set the same secret with tldv({ webhookSecret }) or keys.set_webhook_signature(secret). Webhooks need a Pro or Business plan, and the endpoint must be HTTPS and must not redirect.
• What the secret proves. The secret is the only thing that ties a delivery to tl;dv. Use a long random value, keep it out of logs and client code, and replace it in both places if it leaks.
• Answer within 10 seconds. tl;dv retries a delivery that gets no 2xx in that time, and a MeetingReady delivery with the transcript included can be several hundred KB. When the plugin rejects a delivery (wrong secret, a payload that does not parse), processWebhook returns response.success === false. Answer that with a non-2xx status.
• Tenant routing. Add ?tenantId=<id> to the endpoint URL you give tl;dv, and pass Object.fromEntries(new URL(request.url).searchParams) to processWebhook as its fourth argument. Without it a delivery runs under default. If your handler resolves the tenant from the payload instead, a MeetingReady delivery is matched by the organizer’s email, which you store with keys.set_tenant_external_id(email). A TranscriptReady delivery names no organizer, so only tenantId can route it.

• 6 typed API operations
• 2 incoming webhook event types

​

Setup

npm install corsair @corsair-dev/tldv better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/tldv better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/tldv better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/tldv better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { tldv } from '@corsair-dev/tldv';

export const corsair = createCorsair({
	plugins: [
		tldv(),
	],
	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!,
	},
});

tldv()

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

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.tldv.api.meetings.list({ limit: 10 });

const tenant = corsair.withTenant('acme');
await tenant.tldv.api.meetings.import({ url: 'https://example.org/call-recording.mp4', name: 'Discovery call' });

​

Webhooks

tldv({
    webhookHooks: {
        meetings: {
            meetingReady: {
                after: async (ctx, result) => {
                    console.log('Meeting ready:', result.data?.data.name, 'notes:', result.data?.data.notes?.structuredNotes?.length);
                }
            },
        },
    },
})

​

What’s next