# Refresh Podcast

> Pod Engine API endpoint reference, optimized for LLM consumption.
> Auto-generated from the source-of-truth endpoint registry.
>
> Category: Podcasts
> Source: https://www.podengine.ai/api-docs/refresh-podcast.md
> Interactive HTML docs: https://www.podengine.ai/api-docs/refresh-podcast
> Full API reference (all endpoints): https://www.podengine.ai/api-docs/llms.txt

**Base URL:** `http://localhost:4000`
**Auth:** Requires a Bearer token: `Authorization: Bearer YOUR_API_KEY`

---

#### GET /api/v1/podcasts/:podcastIdOrSlug/refresh
**Refresh Podcast**

Refresh podcast metadata and thumbnail from RSS feed. Rate limited to once per minute per podcast.

```bash
curl -X GET "http://localhost:4000/api/v1/podcasts/this-week-in-startups/refresh?updatePodcastThumbnail=true" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Path parameters schema:**
```json
{
  "type": "object",
  "properties": {
    "podcastIdOrSlug": {
      "type": "string",
      "description": "Podengine ID, Apple ID, or slug"
    }
  },
  "required": [
    "podcastIdOrSlug"
  ],
  "additionalProperties": false
}
```

**Query schema:**
```json
{
  "type": "object",
  "properties": {
    "updatePodcastThumbnail": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}
```

**Response schema:**
```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "OK"
      ]
    },
    "data": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "success": {
              "type": "boolean",
              "enum": [
                true
              ]
            },
            "podcast": {
              "type": "object",
              "properties": {
                "author": {
                  "nullable": true,
                  "type": "string"
                },
                "authorityScore": {
                  "nullable": true,
                  "type": "object",
                  "properties": {
                    "calculatedAt": {},
                    "authorityScore": {
                      "type": "number",
                      "description": "This is the weighted total authority score of the podcast, out of 100"
                    },
                    "qualityScore": {
                      "type": "number",
                      "description": "This is the quality score of the podcast, out of 100"
                    },
                    "youtubeScore": {
                      "type": "number",
                      "description": "This is the YouTube score of the podcast, out of 100"
                    },
                    "socialScore": {
                      "type": "number",
                      "description": "This is the social score of the podcast, out of 100"
                    },
                    "engagementScore": {
                      "type": "number",
                      "description": "This is the engagement score of the podcast, out of 100"
                    }
                  },
                  "required": [
                    "calculatedAt",
                    "authorityScore",
                    "qualityScore",
                    "youtubeScore",
                    "socialScore",
                    "engagementScore"
                  ],
                  "additionalProperties": false
                },
                "genres": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "id": {
                  "type": "string"
                },
                "imageUrl": {
                  "nullable": true,
                  "type": "string"
                },
                "language": {
                  "type": "string"
                },
                "lastEpisodePublishedAt": {},
                "slug": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "titleLatest": {
                  "type": "string"
                },
                "appleId": {
                  "type": "number"
                },
                "blocked": {
                  "type": "object",
                  "properties": {
                    "blockedDate": {},
                    "blockedReason": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "blockedDate"
                  ],
                  "additionalProperties": false
                },
                "description": {
                  "nullable": true,
                  "type": "string"
                },
                "emails": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "explicitRss": {
                  "nullable": true,
                  "type": "boolean"
                },
                "hostNames": {
                  "nullable": true,
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "ignore": {
                  "type": "boolean"
                },
                "ignoreReason": {
                  "type": "string"
                },
                "neverTranscribe": {
                  "type": "boolean"
                },
                "neverTranscribeReason": {
                  "type": "string"
                },
                "isClaimed": {
                  "type": "boolean"
                },
                "podcastAffiliation": {
                  "nullable": true,
                  "type": "object",
                  "properties": {
                    "affiliateOrganizationName": {
                      "nullable": true,
                      "description": "The name of the affiliate organization",
                      "type": "string"
                    },
                    "affiliationType": {
                      "nullable": true,
                      "description": "The type of affiliation from the list: academic, branded, celebrity, government, independent, legacy media, podcast company, new media, not for profit, religious, other, unknown",
                      "type": "string",
                      "enum": [
                        "academic",
                        "branded",
                        "celebrity",
                        "government",
                        "independent",
                        "legacy media",
                        "podcast company",
                        "new media",
                        "not for profit",
                        "religious",
                        "other",
                        "unknown"
                      ]
                    }
                  },
                  "additionalProperties": false
                },
                "podcastDirectoryLinks": {
                  "type": "object",
                  "properties": {
                    "amazonmusic": {
                      "type": "string",
                      "format": "uri"
                    },
                    "anchor": {
                      "type": "string",
                      "format": "uri"
                    },
                    "antennapod": {
                      "type": "string",
                      "format": "uri"
                    },
                    "anytimeplayer": {
                      "type": "string",
                      "format": "uri"
                    },
                    "apollo": {
                      "type": "string",
                      "format": "uri"
                    },
                    "apple": {
                      "type": "string",
                      "format": "uri"
                    },
                    "audible": {
                      "type": "string",
                      "format": "uri"
                    },
                    "breez": {
                      "type": "string",
                      "format": "uri"
                    },
                    "castamatic": {
                      "type": "string",
                      "format": "uri"
                    },
                    "castbox": {
                      "type": "string",
                      "format": "uri"
                    },
                    "castro": {
                      "type": "string",
                      "format": "uri"
                    },
                    "curiocaster": {
                      "type": "string",
                      "format": "uri"
                    },
                    "fountain": {
                      "type": "string",
                      "format": "uri"
                    },
                    "goodpods": {
                      "type": "string",
                      "format": "uri"
                    },
                    "google": {
                      "type": "string",
                      "format": "uri"
                    },
                    "gpodder": {
                      "type": "string",
                      "format": "uri"
                    },
                    "iheartradio": {
                      "type": "string",
                      "format": "uri"
                    },
                    "listennotes": {
                      "type": "string",
                      "format": "uri"
                    },
                    "lnbeats": {
                      "type": "string",
                      "format": "uri"
                    },
                    "moonfm": {
                      "type": "string",
                      "format": "uri"
                    },
                    "overcast": {
                      "type": "string",
                      "format": "uri"
                    },
                    "playerfm": {
                      "type": "string",
                      "format": "uri"
                    },
                    "pocketcasts": {
                      "type": "string",
                      "format": "uri"
                    },
                    "podbean": {
                      "type": "string",
                      "format": "uri"
                    },
                    "podcastaddict": {
                      "type": "string",
                      "format": "uri"
                    },
                    "podcastguru": {
                      "type": "string",
                      "format": "uri"
                    },
                    "podcastrepublic": {
                      "type": "string",
                      "format": "uri"
                    },
                    "podchaser": {
                      "type": "string",
                      "format": "uri"
                    },
                    "podfriend": {
                      "type": "string",
                      "format": "uri"
                    },
                    "podknife": {
                      "type": "string",
                      "format": "uri"
                    },
                    "podlp": {
                      "type": "string",
                      "format": "uri"
                    },
                    "podnews": {
                      "type": "string",
                      "format": "uri"
                    },
                    "podscan": {
                      "type": "string",
                      "format": "uri"
                    },
                    "podscribe": {
                      "type": "string",
                      "format": "uri"
                    },
                    "podstation": {
                      "type": "string",
                      "format": "uri"
                    },
                    "podurama": {
                      "type": "string",
                      "format": "uri"
                    },
                    "podverse": {
                      "type": "string",
                      "format": "uri"
                    },
                    "radiopublic": {
                      "type": "string",
                      "format": "uri"
                    },
                    "rephonic": {
                      "type": "string",
                      "format": "uri"
                    },
                    "sonnet": {
                      "type": "string",
                      "format": "uri"
                    },
                    "spotify": {
                      "type": "string",
                      "format": "uri"
                    },
                    "stenofm": {
                      "type": "string",
                      "format": "uri"
                    },
                    "truefans": {
                      "type": "string",
                      "format": "uri"
                    },
                    "tunein": {
                      "type": "string",
                      "format": "uri"
                    },
                    "youtubemusic": {
                      "type": "string",
                      "format": "uri"
                    }
                  },
                  "additionalProperties": false
                },
                "podcastHasGuests": {
                  "nullable": true,
                  "type": "boolean"
                },
                "podcastHasSponsors": {
                  "nullable": true,
                  "type": "boolean"
                },
                "podcastLocations": {
                  "nullable": true,
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "primaryContactEmail": {
                  "nullable": true,
                  "type": "string"
                },
                "rssFeedUrl": {
                  "type": "string"
                },
                "socialMediaLinks": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "socialMediaType": {
                        "type": "string",
                        "enum": [
                          "beehiiv",
                          "behance",
                          "bluesky",
                          "discord",
                          "facebook",
                          "github",
                          "instagram",
                          "linkedin",
                          "linktree",
                          "mastodon",
                          "medium",
                          "patreon",
                          "pinterest",
                          "reddit",
                          "snapchat",
                          "soundcloud",
                          "substack",
                          "threads",
                          "tiktok",
                          "tumblr",
                          "twitch",
                          "twitter",
                          "vimeo",
                          "whatsapp",
                          "youtube"
                        ]
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      },
                      "sources": {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "apple-podcasts",
                            "bright-data-dataset",
                            "google-search",
                            "linktree",
                            "podcast-website",
                            "podchaser",
                            "rephonic",
                            "rss"
                          ]
                        }
                      }
                    },
                    "required": [
                      "socialMediaType",
                      "url",
                      "sources"
                    ],
                    "additionalProperties": false
                  }
                },
                "spotifyId": {
                  "nullable": true,
                  "type": "string"
                },
                "stats": {
                  "type": "object",
                  "properties": {
                    "downloadCount": {
                      "type": "number"
                    },
                    "episodeCount": {
                      "type": "number"
                    },
                    "latestPublishedAt": {
                      "nullable": true
                    },
                    "firstEpisodePublishedAt": {
                      "nullable": true
                    },
                    "transcriptsCount": {
                      "type": "number"
                    },
                    "updateFrequency": {
                      "type": "string",
                      "enum": [
                        "daily",
                        "weekly",
                        "bi-weekly",
                        "monthly",
                        "stale",
                        "very-stale"
                      ]
                    }
                  },
                  "required": [
                    "downloadCount",
                    "episodeCount",
                    "latestPublishedAt",
                    "firstEpisodePublishedAt",
                    "transcriptsCount",
                    "updateFrequency"
                  ],
                  "additionalProperties": false
                },
                "titleLatestCleaned": {
                  "nullable": true,
                  "type": "string"
                },
                "transcriptionMode": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "mode": {
                          "type": "string",
                          "enum": [
                            "none"
                          ]
                        },
                        "transcribeSince": {
                          "not": {}
                        }
                      },
                      "required": [
                        "mode"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "mode": {
                          "type": "string",
                          "enum": [
                            "all"
                          ]
                        },
                        "transcribeSince": {
                          "not": {}
                        }
                      },
                      "required": [
                        "mode"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "mode": {
                          "type": "string",
                          "enum": [
                            "episodes-since"
                          ]
                        },
                        "transcribeSince": {}
                      },
                      "required": [
                        "mode",
                        "transcribeSince"
                      ],
                      "additionalProperties": false
                    }
                  ]
                },
                "websiteUrl": {
                  "nullable": true,
                  "type": "string"
                },
                "audienceEstimate": {
                  "type": "object",
                  "properties": {
                    "audienceDemographics": {
                      "nullable": true,
                      "type": "object",
                      "properties": {
                        "ageRange": {
                          "type": "string",
                          "enum": [
                            "Under 18",
                            "18-24",
                            "25-34",
                            "35-44",
                            "45-54",
                            "55+"
                          ],
                          "description": "The age range of the audience as a string."
                        },
                        "genderSkew": {
                          "type": "string",
                          "enum": [
                            "Male 0% Female 100%",
                            "Male 20% Female 80%",
                            "Male 40% Female 60%",
                            "Male 50% Female 50%",
                            "Male 60% Female 40%",
                            "Male 80% Female 20%",
                            "Male 100% Female 0%"
                          ],
                          "description": "How the audience is skewed in terms of gender."
                        },
                        "educationLevel": {
                          "type": "string",
                          "enum": [
                            "No High School",
                            "High School",
                            "Some College",
                            "Bachelors Degree",
                            "Masters Degree",
                            "Doctorate"
                          ],
                          "description": "The probable education levels of the audience."
                        },
                        "incomeLevel": {
                          "type": "string",
                          "enum": [
                            "Under $25K",
                            "$25K-$50K",
                            "$50K-$75K",
                            "$75K-$100K",
                            "$100K-$150K",
                            "$150K-$200K",
                            "$200K+"
                          ],
                          "description": "The probable income levels of the audience."
                        },
                        "exampleListenerProfile": {
                          "type": "string",
                          "description": "An example profile of the audience. This is a description of the audience that you can use to describe the audience to an advertiser."
                        }
                      },
                      "required": [
                        "ageRange",
                        "genderSkew",
                        "educationLevel",
                        "incomeLevel",
                        "exampleListenerProfile"
                      ],
                      "additionalProperties": false
                    },
                    "estimatedMonthlyListeners": {
                      "nullable": true,
                      "type": "number"
                    },
                    "estimatedMonthyListenersCalculatedAt": {
                      "nullable": true
                    }
                  },
                  "required": [
                    "audienceDemographics",
                    "estimatedMonthlyListeners",
                    "estimatedMonthyListenersCalculatedAt"
                  ],
                  "additionalProperties": false
                },
                "audioRetentionPolicy": {
                  "type": "string",
                  "enum": [
                    "RETAIN_INDEFINITELY",
                    "RETAIN_DAYS",
                    "RETAIN_UNTIL_TRANSCRIBED"
                  ]
                },
                "audioRetentionDays": {
                  "nullable": true,
                  "type": "number"
                }
              },
              "required": [
                "author",
                "authorityScore",
                "genres",
                "id",
                "imageUrl",
                "language",
                "lastEpisodePublishedAt",
                "slug",
                "title",
                "titleLatest",
                "appleId",
                "description",
                "emails",
                "explicitRss",
                "hostNames",
                "ignore",
                "isClaimed",
                "podcastAffiliation",
                "podcastDirectoryLinks",
                "podcastHasGuests",
                "podcastHasSponsors",
                "podcastLocations",
                "primaryContactEmail",
                "rssFeedUrl",
                "socialMediaLinks",
                "spotifyId",
                "stats",
                "titleLatestCleaned",
                "transcriptionMode",
                "websiteUrl"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "success",
            "podcast"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "success": {
              "type": "boolean",
              "enum": [
                false
              ]
            },
            "errorCode": {
              "type": "string",
              "enum": [
                "rss_not_found",
                "rss_parse_error",
                "rss_fetch_failed",
                "update_failed",
                "unknown_error"
              ]
            },
            "errorMessage": {
              "type": "string"
            },
            "errorDetails": {
              "type": "object",
              "properties": {
                "rssUrl": {
                  "type": "string"
                },
                "attemptId": {
                  "type": "number"
                }
              },
              "additionalProperties": false
            }
          },
          "required": [
            "success",
            "errorCode",
            "errorMessage"
          ],
          "additionalProperties": false
        }
      ]
    }
  },
  "required": [
    "status",
    "data"
  ],
  "additionalProperties": false
}
```

---

## See also

- All endpoints in one file: https://www.podengine.ai/api-docs/llms.txt
- Full reference with every schema inlined: https://www.podengine.ai/api-docs/llms-full.txt
- OpenAPI 3.1 spec: https://www.podengine.ai/api-docs/openapi.json
- Get an API key: https://www.podengine.ai/get-started
- Support: support@podengine.ai