TLDR Pods API
Get answers from podcasts through an API.
Send a question from your server. TLDR Pods researches relevant podcast episodes and returns a written answer with source links and timestamps. API usage shares your website account's plan, allowance, and saved answers.
https://api.tldrpods.com/api/jobsQuickstart
Create a key in Account, store it as a server-side secret, and submit the question once. A successful request returns 202 Accepted with a status URL. Poll that URL until the job succeeds, fails, or is canceled.
curl --include https://api.tldrpods.com/api/jobs \
--request POST \
--header "Authorization: Bearer $TLDRPODS_API_KEY" \
--header "Idempotency-Key: report-20260713-hormozi-offers" \
--header "Content-Type: application/json" \
--data '{"query":"How has Alex Hormozi explained offers on Modern Wisdom?","maxEpisodes":8}'Creating answers requires an active Pro or Research subscription. Each completed answer uses one from your account allowance. If a job fails before producing an answer, that allowance is restored.
Authentication
Send the key as a bearer token. Keys begin with tldr_sk_, are shown once when created, and can be revoked from your account at any time.
Authorization: Bearer tldr_sk_YOUR_KEYRequest
Send a JSON object with the question and an optional episode cap.
Every submission also needs an Idempotency-Keyheader of 8 to 160 letters, numbers, underscores, or hyphens. Reuse the key only when retrying the exact same request. Use a new key for a new answer.
| Field | Type | Required | Description |
|---|---|---|---|
query | string | Yes | 3-400 characters. Name the person, show, or topic as specifically as you can. |
maxEpisodes | integer | No | Defaults to 3. The maximum is 8 on all current paid plans. |
Write a useful query
Include the person and what you want to know. "Alex Hormozi appearances on Modern Wisdom" is valid; "How has Alex Hormozi explained offers on Modern Wisdom?" gives the research a specific question to answer.
Job lifecycle
A successful submission returns 202. Read the relative status URL from job.statusUrl or theLocation response header, then poll it with the same bearer token. Clients should ignore unknown fields.
| Status | Meaning |
|---|---|
queued | The job is saved and waiting to start. |
running | The job is active. Continue polling with a short delay. |
succeeded | The response includes your answer in the report field. |
failed | Read job.error. Failed jobs restore the answer allowance they used. |
canceled | The job stopped without producing an answer. |
Send DELETE to the same status URL to cancel a queued or running job. Closing your process or losing the network connection does not cancel it.
{
"job": {
"id": "018f47a2-01be-7f4d-92b7-74a3fe1024f8",
"query": "How has Alex Hormozi explained offers on Modern Wisdom?",
"status": "succeeded",
"stage": "done",
"reportId": "41ae676a-badd-42d3-9d3f-21d93f2168e0",
"canCancel": false
},
"report": {
"markdown": "## The core idea\n...",
"person": "Alex Hormozi",
"topic": "offers",
"citations": [
{
"title": "Alex Hormozi: The Business Advice That Made Me $100M",
"show": "Modern Wisdom",
"timestampS": 834,
"link": "https://example.com/episode#t=834"
}
]
}
}Node.js example
const apiKey = process.env.TLDRPODS_API_KEY;
const response = await fetch("https://api.tldrpods.com/api/jobs", {
method: "POST",
headers: {
authorization: `Bearer ${apiKey}`,
"content-type": "application/json",
"idempotency-key": crypto.randomUUID(),
},
body: JSON.stringify({
query: "How has Alex Hormozi explained offers on Modern Wisdom?",
maxEpisodes: 8,
}),
});
if (response.status !== 202) {
throw new Error(`TLDR Pods request failed: ${response.status}`);
}
const queued = await response.json();
const statusUrl = new URL(queued.job.statusUrl, response.url);
while (true) {
await new Promise((resolve) => setTimeout(resolve, 3000));
const statusResponse = await fetch(statusUrl, {
headers: { authorization: `Bearer ${apiKey}` },
});
if (!statusResponse.ok) {
throw new Error(`Status request failed: ${statusResponse.status}`);
}
const result = await statusResponse.json();
if (result.job.status === "succeeded") {
console.log(result.report.markdown, result.report.citations);
break;
}
if (["failed", "canceled"].includes(result.job.status)) {
throw new Error(result.job.error?.message ?? `Answer job ${result.job.status}`);
}
}Errors & limits
| Status | Action |
|---|---|
400 | Fix the JSON body, query length, or episode value. |
401 | Replace an unknown or revoked API key. |
402 | Activate a paid plan, reduce maxEpisodes, or wait for the plan allowance to reset. |
409 | Use a new idempotency key, or retry it with the original request body. |
429 | Wait before retrying. The account is rate-limited or another answer is being researched. |
503 | Retry later with backoff. The service is temporarily unavailable. |
API and website usage share one allowance. Avoid automatic retries for 400, 401, or 402. For transient failures, use exponential backoff and cap retries.
Privacy & permitted use
Answers created through the API are saved privately to the API key owner's account. The API returns the answer in the report field with source references, never a raw transcript. Do not submit secrets, sensitive personal data, or material you do not have the right to process.
Use of the API is subject to the Terms of Service, Acceptable Use Policy, and Privacy Notice.