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.

POSThttps://api.tldrpods.com/api/jobs

Quickstart

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_KEY
Keep keys on the server. Do not put them in browser code, mobile bundles, public repositories, URLs, or logs.

Request

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.

FieldTypeRequiredDescription
querystringYes3-400 characters. Name the person, show, or topic as specifically as you can.
maxEpisodesintegerNoDefaults 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.

StatusMeaning
queuedThe job is saved and waiting to start.
runningThe job is active. Continue polling with a short delay.
succeededThe response includes your answer in the report field.
failedRead job.error. Failed jobs restore the answer allowance they used.
canceledThe 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

StatusAction
400Fix the JSON body, query length, or episode value.
401Replace an unknown or revoked API key.
402Activate a paid plan, reduce maxEpisodes, or wait for the plan allowance to reset.
409Use a new idempotency key, or retry it with the original request body.
429Wait before retrying. The account is rate-limited or another answer is being researched.
503Retry 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.