Feeds

Feeds allow you to organize and distribute your pods as podcasts. On this page, we'll explore the different feed endpoints you can use to manage feeds programmatically.

The feed model

The feed model contains all the information about the feeds you create and manage in Lettercast.

Properties

Name
id
Type
string
Description
Unique identifier for the feed.
Name
title
Type
string
Description
The title of the feed.
Name
description
Type
string
Description
A description of the feed's content.
Name
created_at
Type
string
Description
The date and time when the feed was created.
Name
lookup_key
Type
string
Description
Optional. A custom identifier for the feed.
Name
slug
Type
string
Description
Optional. A URL-friendly version of the feed title.

GET/v1/feeds

List all feeds

This endpoint allows you to retrieve a list of all your feeds.

Request

GET

/v1/feeds

export default async function handler(req, res) {
  const API_KEY = process.env.LETTERCAST_API_KEY;

  try {
    const response = await fetch('https://app.lettercast.ai/v1/feeds', {
      headers: { Authorization: `Bearer ${API_KEY}` },
    });
    if (!response.ok) throw new Error('API request failed');
    const data = await response.json();
    res.status(200).json(data);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

Response

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "My Tech Podcast",
    "description": "Weekly discussions about technology",
    "created_at": "2024-01-01T12:00:00Z",
    "lookup_key": "tech-weekly",
    "slug": "my-tech-podcast"
  }
]

POST/v1/feeds

Create a feed

This endpoint allows you to create a new feed.

Required Parameters

Name
title
Type
string
Description
The title of the feed.

Optional Parameters

Name
description
Type
string
Description
A description of the feed's content.
Name
lookup_key
Type
string
Description
A custom identifier for the feed.
Name
slug
Type
string
Description
A URL-friendly version of the feed title.
Name
image
Type
File
Description
An image file for the feed's artwork.

Request

POST

/v1/feeds

export default async function handler(req, res) {
  const API_KEY = process.env.LETTERCAST_API_KEY;

  const formData = new FormData();
  formData.append('title', 'My Tech Podcast');
  formData.append('description', 'Weekly discussions about technology');
  formData.append('lookup_key', 'tech-weekly');
  formData.append('slug', 'my-tech-podcast');
  
  // Optional: Add image if available
  if (req.files?.image) {
    formData.append('image', req.files.image);
  }

  try {
    const response = await fetch('https://app.lettercast.ai/v1/feeds', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
      },
      body: formData,
    });
    if (!response.ok) throw new Error('API request failed');
    const data = await response.json();
    res.status(200).json(data);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

Response

{
  "feed_id": "123e4567-e89b-12d3-a456-426614174000"
}

GET/v1/feeds/:id

Retrieve a feed

This endpoint allows you to retrieve a specific feed by providing its ID.

The response can be returned in two formats:

JSON (default)
XML (RSS feed format) - request with Accept: application/xml header or .xml extension

Request

GET

/v1/feeds/123e4567-e89b-12d3-a456-426614174000

export default async function handler(req, res) {
  const API_KEY = process.env.LETTERCAST_API_KEY;
  const { id } = req.query;

  try {
    const response = await fetch(`https://app.lettercast.ai/v1/feeds/${id}`, {
      headers: { 
        Authorization: `Bearer ${API_KEY}`,
        Accept: 'application/json'  // or 'application/xml' for RSS feed
      },
    });
    if (!response.ok) throw new Error('API request failed');
    const data = await response.json();
    res.status(200).json(data);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

JSON Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "My Tech Podcast",
  "description": "Weekly discussions about technology",
  "created_at": "2024-01-01T12:00:00Z",
  "lookup_key": "tech-weekly",
  "slug": "my-tech-podcast"
}

PUT/v1/feeds/:id

Update a feed

This endpoint allows you to update an existing feed.

Optional Parameters

Name
title
Type
string
Description
The new title for the feed.
Name
description
Type
string
Description
The new description for the feed.
Name
lookup_key
Type
string
Description
A new custom identifier for the feed.
Name
image
Type
File
Description
A new image file for the feed's artwork.

Request

PUT

/v1/feeds/123e4567-e89b-12d3-a456-426614174000

curl -X PUT https://app.lettercast.ai/v1/feeds/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Tech Podcast",
    "description": "Daily discussions about technology",
    "lookup_key": "tech-daily"
  }'

Response

{
  "status": "success"
}