Quickstart

This guide will get you all set up and ready to use the Lettercast API. We'll cover how to authenticate and make your first API request. We'll also look at where to go next to find all the information you need to take full advantage of our powerful REST API.

Authentication

Lettercast uses an API key for authentication. You'll need to include your access token in the Authorization header of your requests:

const headers = {
  Authorization: `Bearer API_KEY`,
}

Making your first API request

Now that you have your API key, you're ready to make your first call to the Lettercast API. Let's start by sending a GET request to the Pods endpoint to get a list of all your pods.

// JS implementation using fetch
fetch('https://app.lettercast.ai/v1/pods', {
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
})
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`)
    }
    return response.json()
  })
  .then((data) => {
    console.log(data)
  })
  .catch((error) => {
    console.error('Error:', error)
  })

This request will return a list of all your pods, including their IDs, titles, sources, and other details as defined in the pod schema.

Creating a new pod

To create a new pod, you can send a POST request to the Pods endpoint. You can create a pod from a URL, a PDF file, or HTML content:

// JS implementation for creating a pod from a URL
const data = {
  url: 'https://example.com/article',
  pod_type: 'summary_discussion'
}

fetch('https://app.lettercast.ai/v1/pods', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(data),
})
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`)
    }
    return response.json()
  })
  .then((data) => {
    console.log(data)
  })
  .catch((error) => {
    console.error('Error:', error)
  })

// JS implementation for creating a pod from HTML content
const data = {
  html_content: '<h1>Sample Header</h1><p>This is a sample paragraph for pod creation.</p>',
  pod_type: 'summary_single_host'
}

fetch('https://app.lettercast.ai/v1/pods', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(data),
})
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`)
    }
    return response.json()
  })
  .then((data) => {
    console.log(data)
  })
  .catch((error) => {
    console.error('Error:', error)
  })

// JS implementation for creating a pod from a PDF file
const form = new FormData()
form.append(
  'file',
  new Blob(
    [await fetch('/path/to/document.pdf').then((res) => res.arrayBuffer())],
    { type: 'application/pdf' },
  ),
  'document.pdf',
)
form.append('pod_type', 'full_discussion')

fetch('https://app.lettercast.ai/v1/pods', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
  },
  body: form,
})
  .then((response) => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`)
    }
    return response.json()
  })
  .then((data) => {
    console.log(data)
  })
  .catch((error) => {
    console.error('Error:', error)
  })

This will return the details of the newly created pod, including its ID. Note that the pod creation process may take some time to complete.

Checking pod status

After creating a new pod, you'll need to poll the API to check its status. Here's an example of how to do this:

async function checkPodStatus(podId) {
  while (true) {
    try {
      const response = await fetch(
        `https://app.lettercast.ai/v1/pods/${podId}`,
        {
          headers: { Authorization: `Bearer ${API_KEY}` },
        },
      )

      if (!response.ok) {
        throw new Error(`HTTP error! status: ${response.status}`)
      }

      const pod = await response.json()

      if (pod.generation_status === 'completed') {
        console.log('Pod is ready!')
        return pod
      } else if (pod.generation_status === 'failed') {
        console.log('Pod creation failed.')
        return null
      } else {
        console.log(
          `Pod is still being created. Status: ${pod.generation_status}`,
        )
        await new Promise((resolve) => setTimeout(resolve, 10000)) // Wait for 10 seconds
      }
    } catch (error) {
      console.error('Error checking pod status:', error.message)
      return null
    }
  }
}

// Usage example:
async function example() {
  try {
    const podId = 'pod_id_returned_from_creation'
    const pod = await checkPodStatus(podId)
    if (pod) {
      console.log('Pod details:', pod)
    } else {
      console.log('Pod not available. Try again later.')
    }
  } catch (error) {
    console.error('An error occurred:', error.message)
  }
}

example()

Understanding the pod structure

When you retrieve a pod, it will have the following structure:

Javascript

{
  id: string,
  title: string,
  source: string,
  content_publication_date: string | null,
  created_at: string | null,
  generation_status: string,
  table_of_contents: array,
  authors: array | null,
  summary: string,
  instructions: string
}

Let's break down these fields:

id: Unique identifier for the pod
title: Title of the pod
source: Source of the pod content
content_publication_date: Publication date of the content (ISO format)
created_at: Creation date of the pod (ISO format)
generation_status: Current status of the pod generation process
table_of_contents: Array of objects with timestamp_s (number) and description (string)
authors: Array of authors (if available)
summary: Summary of the pod content
instructions: User input query or instructions for pod creation

Make sure to handle these fields appropriately in your application.

Downloading Pod Audio and Video

Before downloading the audio and video files of a pod, it's important to ensure that the pod generation is complete. We'll use the status checking function from earlier to wait until the pod is ready before attempting to download.

async function downloadPodMedia(podId, mediaType) {
  try {
    const pod = await checkPodStatus(podId)
    if (!pod) {
      console.log(`Cannot download ${mediaType}. Pod is not ready.`)
      return
    }

    const response = await fetch(
      `https://app.lettercast.ai/v1/pods/${podId}/${mediaType}`,
      {
        headers: { Authorization: `Bearer ${API_KEY}` },
      },
    )

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`)
    }

    const blob = await response.blob()
    const url = window.URL.createObjectURL(blob)
    const a = document.createElement('a')
    a.style.display = 'none'
    a.href = url
    a.download = `pod_${mediaType}.${mediaType === 'audio' ? 'mp3' : 'mp4'}`
    document.body.appendChild(a)
    a.click()
    window.URL.revokeObjectURL(url)
    console.log(`${mediaType} downloaded successfully.`)
  } catch (error) {
    console.error(`Error downloading ${mediaType}:`, error.message)
  }
}

// Usage
async function main() {
  await downloadPodMedia('your_pod_id_here', 'audio')
  await downloadPodMedia('your_pod_id_here', 'video')
}

main()

These examples demonstrate how to check the pod status before attempting to download both audio and video files for a specific pod. The download function will only proceed if the pod status is "completed". Make sure to replace API_KEY with your actual API key and your_pod_id_here with the ID of the pod you want to download.

What's next?

Great! You're now set up with an API key and have made your first requests to the Lettercast API. Here are a few links that might be handy as you explore further:

Read the docs for the Pods endpoint