tl;dv API (v1alpha1)

tl;dv: [email protected] URL: https://tldv.io

Introduction

Greetings and welcome to the documentation of the tl;dv API! This API is designed to seamlessly integrate tl;dv functionalities into your applications, making it easier for your users to access transcripts, notes, or import your meetings. Let's explore the details together.

Versioning

Current API Version: v1alpha1 (v1 Alpha 1).

You are pioneering the tl;dv API, and we're excited to have you on board! Embark with us on the alpha phase adventure! Expect upcoming changes as we sculpt this API masterpiece, evolving towards the stable v1 release. Your invaluable feedback during this period will be our guiding star. Anticipate a slew of updates, and maybe a surprise or two – who said versioning can't be thrilling?

Environment & Endpoint

In the tl;dv API universe, we're currently all about that production data. So there is no alternate realities or sandbox just yet. We're working on it, though, so stay tuned!

Production API Endpoint: https://pasta.tldv.io (brace yourselves, this endpoint may choose to change its pasta shape, but we will keep you updated)

Authentication

To unlock the tl;dv Public API's treasure trove, you need the key – THE API key - that's it. It's the golden ticket to seamless integration.

Obtaining an API Key

Navigate to https://tldv.io/app/settings/personal-settings/api-keys – you'll need to be logged in to access this page.
Generate a new API Key.
Guard your API key (like you would your morning coffee – don't spill it, and definitely don't share it with strangers)

Including the API Key in Requests

Once you have your API key, you can include it in the header of all your API requests.

x-api-key: YOUR_API_KEY

Replace YOUR_API_KEY with the actual key. If you're using a client library, it should be as simple as setting the header value.

Authorization

All API requests must be made over HTTPS. Requests made over plain HTTP will be rejected.

Each request must include a valid API key. Requests without a valid key will return an authentication error.

The tl;dv Public API follows the same underlying permission model as the web application, with additional plan-based constraints applied to automation and export capabilities.

UI Access vs API Access

Seeing a meeting in the web app does not automatically guarantee programmatic (API) access.

Sharing enables collaboration and visibility in the UI.
API exportability depends on the plan of the meeting organizer.

Meeting Ownership

Meeting ownership is determined by the calendar invite organizer or the meeting organizer (if the meeting was created spontaneously)

If you rely on API access, make sure:

Paying users are the actual organizers of the calendar invites.
The correct user schedules the meeting.

To summarize:

Sharing a meeting does not grant API export rights.
Programmatic access depends on the organizer's plan.
Organization-wide automation requires an Enterprise plan (more to come soon)

Meeting Organizer Plan	UI Access	API Access
Free	✅ Yes (if shared)	❌ No
Pro / Business	✅ Yes	✅ Yes
Enterprise	✅ Yes	✅ Yes

Webhook Feature

Webhooks allow you to receive real-time notifications from tl;dv when key events occur in your workspace.

Available Triggers

Trigger	Fires when …
MeetingReady	A meeting has finished processing and is ready to be used in your applications.
TranscriptReady	A meeting transcript has been generated and is available.

Scope & Configuration

Webhooks can be configured at different levels, depending on your needs:

User level – only events for that individual user
Team level – events for all users in a specific team
Organization level – all events across your entire organization

You can enable one or both triggers ("MeetingReady", "TranscriptReady") at the level that makes the most sense for your setup. This gives you control over how broadly you want setup your webhooks.

Support & Feature Requests

Need assistance, have a brilliant idea, or just want to say hello? Our support team is ready and waiting at support@tldv.io. Alternatively, drop by via the Intercom Widget.

Have fun! 🎉

Meetings

Meetings (or recordings) related endpoints. With tl;dv you can manage your meetings. So far you can only import new ones, but more functionalities are coming soon.

Import a meeting from a URL

Import a meeting, recording, or other media from a URL. The URL must be publicly accessible, and the media must be in a supported format.

Authorizations:

Api Key Authentication

Request Body schema: application/json
required

MeetingImportControllerBody

name required	string The name of the meeting/recording imported
url required	string <url> The url of the meeting/recording imported. Important: the url must be publicly accessible and the media must be in a supported format. Supported formats are: .mp3, .mp4, .wav, .m4a, .mkv, .mov, .avi, .wma, .flac.
happenedAt	string\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d.... The date of the meeting/recording. If not provided, the current date will be used
dryRun	boolean For testing purposes: whether to run the import as a dry run. If true, the import will not be persisted to the database, and nothing will be run.
participants	Array of strings An array of emails of the invited participants to the meeting/recording

Responses

Request samples

Payload
JavaScript
Shell

Content type

application/json

{"name": "string",
"url": "string",
"happenedAt": "string",
"dryRun": true,
"participants": ["string"
]
}

Response samples

Content type

application/json

{"success": true,
"jobId": "string",
"message": "string"
}

Get a list of meetings

Authorizations:

Api Key Authentication

query Parameters

query	string The query to search for
page	number > 0 The page number to return. Default is 1
limit	number ( 0 .. 100 ] The number of results to return per page. Default is 50. Max is 100. The total number of results cannot exceed 10,000. If this limit is exceeded, refine the date range or period.
	string or string The date to search from
	string or string The date to search to
onlyParticipated	boolean Whether to only return meetings the user participated in. Default is false
meetingType	string Enum: "internal" "external" Filters meetings by type: internal (all participants from the same organization) or external (includes at least one participant from another organization). Defaults to both if not provided

Responses

Request samples

JavaScript
Shell


const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://pasta.tldv.io/v1alpha1/meetings?<query-params>',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '••••••'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response samples

Content type

application/json

{"page": 0,
"pages": 0,
"total": 0,
"pageSize": 0,
"results": [{"id": "string",
"name": "string",
"happenedAt": "string",
"url": "string",
"duration": 0,
"organizer": {"name": "string",
"email": "string"
},
"invitees": [{"name": "string",
"email": "string"
}
],
"template": "string",
"extraProperties": {"conferenceId": "string"
}
}
]
}

Get a meeting by its id

Get a meeting by its id. The meeting is returned in a human readable format

Authorizations:

Api Key Authentication

path Parameters

meetingId

required

string[^\/#\?]+?

Responses

Request samples

JavaScript
Shell


const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://pasta.tldv.io/v1alpha1/meetings/653663ac7c8dbd00130f11d9',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '••••••'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response samples

Content type

application/json

{"id": "string",
"name": "string",
"happenedAt": "string",
"url": "string",
"duration": 0,
"organizer": {"name": "string",
"email": "string"
},
"invitees": [{"name": "string",
"email": "string"
}
],
"template": "string",
"extraProperties": {"conferenceId": "string"
}
}

Transcripts

Transcripts related endpoints. With tl;dv you can get the transcript of a meeting, in a structured format.

Get transcript by meeting id

Get the transcript of a meeting by its id. The transcript is returned in a human readable format. The transcript is returned only if it is complete

Authorizations:

Api Key Authentication

path Parameters

meetingId

required

string[^\/#\?]+?

Responses

Request samples

JavaScript
Shell


const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://pasta.tldv.io/v1alpha1/meetings/653663ac7c8dbd00130f11d9/transcript',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '••••••'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response samples

Content type

application/json

{"id": "string",
"meetingId": "string",
"data": [{"speaker": "string",
"text": "string",
"startTime": 0,
"endTime": 0
}
]
}

Highlights

Highlights (or notes) related endpoints. With tl;dv you can get the highlights of your meetings.

Get meetings notes by meeting id

Get the meetings notes of a meeting, by its id. The meetings notes are returned in a human readable format and they are returned only if the transcript is complete

Authorizations:

Api Key Authentication

path Parameters

meetingId

required

string[^\/#\?]+?

Responses

Request samples

JavaScript
Shell


const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://pasta.tldv.io/v1alpha1/meetings/653663ac7c8dbd00130f11d9/highlights',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': '••••••'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Response samples

Content type

application/json

{"meetingId": "string",
"data": [{"text": "string",
"startTime": 0,
"source": "manual",
"topic": {"title": "string",
"summary": "string"
}
}
]
}

Health check

Authorizations:

Api Key Authentication

Responses

Webhooks

Webhook payloads that tl;dv sends to your configured endpoints when events occur.

MeetingReady Webhook Webhook

Authorizations:

Api Key Authentication

Request Body schema: application/json
required

id required	string non-empty Unique identifier for the webhook payload
event required	string Value: "MeetingReady" The event type that triggered this webhook
required	object (Meeting)
executedAt required	string non-empty The date and time the webhook was executed

Request samples

Payload

Content type

application/json

{"id": "webhook-123",
"event": "MeetingReady",
"data": {"id": "meeting-123",
"name": "Team Standup Meeting",
"happenedAt": "2024-01-15T10:00:00Z",
"organizer": {"name": "John Doe",
"email": "[email protected]"
},
"invitees": [{"name": "Jane Smith",
"email": "[email protected]"
}
],
"url": "https://app.tldv.io/meetings/meeting-123",
"template": {"id": "template-1",
"label": "Standup Template"
},
"extraProperties": {"conferenceId": "conf-123"
},
"duration": 1800
}
}

TranscriptReady Webhook Webhook

This webhook is sent when a meeting transcript is ready. You can configure this webhook to receive notifications when transcripts are successfully generated.

Authorizations:

Api Key Authentication

Request Body schema: application/json
required

id required	string non-empty Unique identifier for the webhook payload
event required	string Value: "TranscriptReady" The event type that triggered this webhook
required	object (GetTranscriptByMeetingIdResponse)
executedAt required	string non-empty The date and time the webhook was executed

Request samples

Payload

Content type

application/json

{"id": "webhook-456",
"event": "TranscriptReady",
"data": {"id": "meeting-123",
"meetingId": "meeting-123",
"data": {"transcript": "Hello everyone, welcome to our standup meeting. Today we will discuss our progress and any blockers...",
"segments": [{"startTime": 0,
"endTime": 5,
"text": "Hello everyone, welcome to our standup meeting."
}
]
}
}
}

tl;dv API (v1alpha1)

Introduction

Versioning

Environment & Endpoint

Authentication

Obtaining an API Key

Including the API Key in Requests

Authorization

UI Access vs API Access

Meeting Ownership

Webhook Feature

Available Triggers

Scope & Configuration

Support & Feature Requests

Meetings

Import a meeting from a URL

Authorizations:

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get a list of meetings

Authorizations:

query Parameters

Responses

Request samples

Response samples

Get a meeting by its id

Authorizations:

path Parameters

Responses

Request samples

Response samples

Transcripts

Get transcript by meeting id

Authorizations:

path Parameters

Responses

Request samples

Response samples

Highlights

Get meetings notes by meeting id

Authorizations:

path Parameters

Responses

Request samples

Response samples

Health check

Health check

Authorizations:

Responses

Webhooks

MeetingReady Webhook Webhook

Authorizations:

Request Body schema: application/jsonrequired

Request samples

TranscriptReady Webhook Webhook

Authorizations:

Request Body schema: application/jsonrequired

Request samples

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required