# Project Podcast Relevancy

> Pod Engine API endpoint reference, optimized for LLM consumption.
> Auto-generated from the source-of-truth endpoint registry.
>
> Category: Agent
> Source: https://www.podengine.ai/api-docs/ask-agent-project-podcast-relevancy.md
> Interactive HTML docs: https://www.podengine.ai/api-docs/ask-agent-project-podcast-relevancy
> 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`

---

#### POST /api/v1/agent/project/relevancy
**Project Podcast Relevancy**

Analyze the relevancy of a podcast to a project using AI

```bash
curl -X POST "http://localhost:4000/api/v1/agent/project/relevancy" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "projectId": "example-project-id",
  "podcastId": "example-podcast-id",
  "forceRegenerate": false
}'
```

**Request body schema:**
```json
{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string"
    },
    "podcastId": {
      "type": "string"
    },
    "searchOptions": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "cursor": {
              "nullable": true,
              "description": "Pagination cursor for fetching the next page of results. This cursor is stateless and does not expire. However, because it uses search_after pagination, results may be inconsistent if the underlying data changes between requests (e.g., you may see duplicate or missing results if documents are added/removed).",
              "type": "string"
            },
            "pageSize": {
              "description": "Number of results to return per page",
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            },
            "project": {
              "description": "Details about any Project this search is associated with. If included will filter out podcasts related to the project.",
              "type": "object",
              "properties": {
                "projectId": {
                  "type": "string",
                  "description": "The Pod Engine Project ID"
                },
                "excludeIgnoredPodcasts": {
                  "description": "If true, will not include any podcasts marked as ignored on this project in the results.",
                  "type": "boolean"
                },
                "excludePodcastsOnList": {
                  "description": "If true, will not include any podcasts on the project list in the results.",
                  "type": "boolean"
                },
                "includePodcastRelevancy": {
                  "description": "If the podcast relevancy should be included with the search results. Note that including this will limit your search results to 20 total and also slow down the search results response",
                  "type": "boolean"
                },
                "excludeRelvancyValues": {
                  "description": "If provided, will exclude podcasts with these relevancy values. Valid values are 1-5. Note this is a server side filter and will only work if includePodcastRelevancy is set.",
                  "type": "array",
                  "items": {
                    "type": "number",
                    "minimum": 1,
                    "maximum": 5
                  }
                },
                "forceRecalculateRelevancy": {
                  "description": "If true, will force a recalculation of the podcast relevancy values for this search. Note this will slow down the search results response and should only be used if you believe the relevancy values are out of date.",
                  "type": "boolean"
                }
              },
              "required": [
                "projectId"
              ],
              "additionalProperties": false
            },
            "projectId": {
              "description": "[DEPRECATED] Project ID to associate the search with",
              "type": "string"
            },
            "searchTerms": {
              "description": "Terms to search for in podcast title and description",
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "searchTerm": {
                    "type": "string",
                    "minLength": 2
                  },
                  "searchType": {
                    "type": "string",
                    "enum": [
                      "text",
                      "embeddings"
                    ]
                  },
                  "searchTargets": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "podcast-title",
                        "podcast-description"
                      ]
                    }
                  },
                  "searchTermOptions": {
                    "default": {
                      "matchMode": "optional",
                      "phraseMatch": false,
                      "fuzzy": false
                    },
                    "type": "object",
                    "properties": {
                      "matchMode": {
                        "default": "optional",
                        "type": "string",
                        "enum": [
                          "must",
                          "not",
                          "optional"
                        ]
                      },
                      "phraseMatch": {
                        "description": "Whether to match the search term as a phrase",
                        "type": "boolean"
                      },
                      "slop": {
                        "description": "How many words apart tokens can appear in a document to be considered a match",
                        "type": "number"
                      },
                      "fuzzy": {
                        "description": "Whether to use fuzzy matching",
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "matchMode"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "searchTerm",
                  "searchType",
                  "searchTargets",
                  "searchTermOptions"
                ],
                "additionalProperties": false
              }
            },
            "excludeItunesGenres": {
              "description": "iTunes genres to exclude from results",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "excludePodcastIds": {
              "description": "Specific podcast IDs to exclude from results",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "excludeEpisodeIds": {
              "description": "Specific episode IDs to exclude from results",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "explicit": {
              "description": "Filter by explicit content rating",
              "type": "string",
              "enum": [
                "clean",
                "explicit"
              ]
            },
            "foundedSince": {
              "description": "Filter podcasts founded after this date"
            },
            "hasPrimaryContact": {
              "description": "Filter podcasts that have primary contact information",
              "type": "boolean"
            },
            "hasSocials": {
              "description": "Filter podcasts with specific social media presence from 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",
              "type": "array",
              "items": {
                "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"
                ]
              }
            },
            "includeItunesGenres": {
              "description": "iTunes genres to include in results",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "includePodcastIds": {
              "description": "Specific podcast IDs to include in results",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "languages": {
              "description": "Filter podcasts by language",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "lastEpisodeDateSince": {
              "description": "Filter podcasts with episodes published after this date"
            },
            "maxTotalEpisodes": {
              "description": "Maximum number of total episodes",
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "minCastboxPlays": {
              "description": "Minimum number of Castbox plays",
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "minCastboxSubscribers": {
              "description": "Minimum number of Castbox subscribers",
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "minItunesRating": {
              "description": "Minimum iTunes rating score",
              "type": "number",
              "minimum": 0,
              "maximum": 5
            },
            "minItunesRatingCount": {
              "description": "Minimum number of iTunes ratings",
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "minSpotifyRating": {
              "description": "Minimum Spotify rating score",
              "type": "number",
              "minimum": 0,
              "maximum": 5
            },
            "minSpotifyRatingCount": {
              "description": "Minimum number of Spotify ratings",
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "minTotalEpisodes": {
              "description": "Minimum number of total episodes",
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "podcastCountries": {
              "description": "Filter podcasts by country of origin using ISO 3166-1 alpha-2 codes, for example us",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "podcastHasGuests": {
              "description": "Filter podcasts that feature guests",
              "type": "boolean"
            },
            "podcastAuthorityScore": {
              "description": "Filter podcasts by their Authority Score",
              "type": "object",
              "properties": {
                "authorityScore": {
                  "type": "object",
                  "properties": {
                    "min": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    },
                    "max": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    }
                  },
                  "required": [
                    "min",
                    "max"
                  ],
                  "additionalProperties": false
                },
                "qualityScore": {
                  "type": "object",
                  "properties": {
                    "min": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    },
                    "max": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    }
                  },
                  "required": [
                    "min",
                    "max"
                  ],
                  "additionalProperties": false
                },
                "engagementScore": {
                  "type": "object",
                  "properties": {
                    "min": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    },
                    "max": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    }
                  },
                  "required": [
                    "min",
                    "max"
                  ],
                  "additionalProperties": false
                },
                "socialScore": {
                  "type": "object",
                  "properties": {
                    "min": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    },
                    "max": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    }
                  },
                  "required": [
                    "min",
                    "max"
                  ],
                  "additionalProperties": false
                },
                "youtubeScore": {
                  "type": "object",
                  "properties": {
                    "min": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    },
                    "max": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    }
                  },
                  "required": [
                    "min",
                    "max"
                  ],
                  "additionalProperties": false
                }
              },
              "additionalProperties": false
            },
            "sortOrder": {
              "description": "Specify how results should be sorted",
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "field": {
                    "type": "string",
                    "enum": [
                      "relevance",
                      "recentActivity",
                      "title",
                      "appleReviews",
                      "spotifyReviews"
                    ]
                  },
                  "direction": {
                    "type": "string",
                    "enum": [
                      "asc",
                      "desc"
                    ]
                  },
                  "nullOrder": {
                    "type": "string",
                    "enum": [
                      "first",
                      "last"
                    ]
                  }
                },
                "required": [
                  "field"
                ],
                "additionalProperties": false
              }
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "cursor": {
              "nullable": true,
              "description": "Pagination cursor for fetching the next page of results. This cursor is stateless and does not expire. However, because it uses search_after pagination, results may be inconsistent if the underlying data changes between requests (e.g., you may see duplicate or missing results if documents are added/removed).",
              "type": "string"
            },
            "pageSize": {
              "description": "Number of results to return per page",
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            },
            "project": {
              "description": "Details about any Project this search is associated with. If included will filter out podcasts related to the project.",
              "type": "object",
              "properties": {
                "projectId": {
                  "type": "string",
                  "description": "The Pod Engine Project ID"
                },
                "excludeIgnoredPodcasts": {
                  "description": "If true, will not include any podcasts marked as ignored on this project in the results.",
                  "type": "boolean"
                },
                "excludePodcastsOnList": {
                  "description": "If true, will not include any podcasts on the project list in the results.",
                  "type": "boolean"
                },
                "includePodcastRelevancy": {
                  "description": "If the podcast relevancy should be included with the search results. Note that including this will limit your search results to 20 total and also slow down the search results response",
                  "type": "boolean"
                },
                "excludeRelvancyValues": {
                  "description": "If provided, will exclude podcasts with these relevancy values. Valid values are 1-5. Note this is a server side filter and will only work if includePodcastRelevancy is set.",
                  "type": "array",
                  "items": {
                    "type": "number",
                    "minimum": 1,
                    "maximum": 5
                  }
                },
                "forceRecalculateRelevancy": {
                  "description": "If true, will force a recalculation of the podcast relevancy values for this search. Note this will slow down the search results response and should only be used if you believe the relevancy values are out of date.",
                  "type": "boolean"
                }
              },
              "required": [
                "projectId"
              ],
              "additionalProperties": false
            },
            "projectId": {
              "description": "[DEPRECATED] Project ID to associate the search with",
              "type": "string"
            },
            "searchTerms": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "searchTerm": {
                    "type": "string",
                    "minLength": 2
                  },
                  "searchType": {
                    "type": "string",
                    "enum": [
                      "text",
                      "embeddings"
                    ]
                  },
                  "searchTargets": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "podcast-title",
                        "podcast-description",
                        "episode-title",
                        "episode-description",
                        "transcript"
                      ]
                    }
                  },
                  "searchTermOptions": {
                    "default": {
                      "matchMode": "optional",
                      "phraseMatch": false,
                      "fuzzy": false
                    },
                    "type": "object",
                    "properties": {
                      "matchMode": {
                        "default": "optional",
                        "type": "string",
                        "enum": [
                          "must",
                          "not",
                          "optional"
                        ]
                      },
                      "phraseMatch": {
                        "description": "Whether to match the search term as a phrase",
                        "type": "boolean"
                      },
                      "slop": {
                        "description": "How many words apart tokens can appear in a document to be considered a match",
                        "type": "number"
                      },
                      "fuzzy": {
                        "description": "Whether to use fuzzy matching",
                        "type": "boolean"
                      }
                    },
                    "required": [
                      "matchMode"
                    ],
                    "additionalProperties": false
                  }
                },
                "required": [
                  "searchTerm",
                  "searchType",
                  "searchTargets",
                  "searchTermOptions"
                ],
                "additionalProperties": false
              }
            },
            "excludeItunesGenres": {
              "description": "iTunes genres to exclude from results",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "excludePodcastIds": {
              "description": "Specific podcast IDs to exclude from results",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "excludeEpisodeIds": {
              "description": "Specific episode IDs to exclude from results",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "explicit": {
              "description": "Filter by explicit content rating",
              "type": "string",
              "enum": [
                "clean",
                "explicit"
              ]
            },
            "foundedSince": {
              "description": "Filter podcasts founded after this date"
            },
            "hasPrimaryContact": {
              "description": "Filter podcasts that have primary contact information",
              "type": "boolean"
            },
            "hasSocials": {
              "description": "Filter podcasts with specific social media presence from 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",
              "type": "array",
              "items": {
                "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"
                ]
              }
            },
            "includeItunesGenres": {
              "description": "iTunes genres to include in results",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "includePodcastIds": {
              "description": "Specific podcast IDs to include in results",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "languages": {
              "description": "Filter podcasts by language",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "lastEpisodeDateSince": {
              "description": "Filter podcasts with episodes published after this date"
            },
            "maxTotalEpisodes": {
              "description": "Maximum number of total episodes",
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "minCastboxPlays": {
              "description": "Minimum number of Castbox plays",
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "minCastboxSubscribers": {
              "description": "Minimum number of Castbox subscribers",
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "minItunesRating": {
              "description": "Minimum iTunes rating score",
              "type": "number",
              "minimum": 0,
              "maximum": 5
            },
            "minItunesRatingCount": {
              "description": "Minimum number of iTunes ratings",
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "minSpotifyRating": {
              "description": "Minimum Spotify rating score",
              "type": "number",
              "minimum": 0,
              "maximum": 5
            },
            "minSpotifyRatingCount": {
              "description": "Minimum number of Spotify ratings",
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "minTotalEpisodes": {
              "description": "Minimum number of total episodes",
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "podcastCountries": {
              "description": "Filter podcasts by country of origin using ISO 3166-1 alpha-2 codes, for example us",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "podcastHasGuests": {
              "description": "Filter podcasts that feature guests",
              "type": "boolean"
            },
            "podcastAuthorityScore": {
              "description": "Filter podcasts by their Authority Score",
              "type": "object",
              "properties": {
                "authorityScore": {
                  "type": "object",
                  "properties": {
                    "min": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    },
                    "max": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    }
                  },
                  "required": [
                    "min",
                    "max"
                  ],
                  "additionalProperties": false
                },
                "qualityScore": {
                  "type": "object",
                  "properties": {
                    "min": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    },
                    "max": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    }
                  },
                  "required": [
                    "min",
                    "max"
                  ],
                  "additionalProperties": false
                },
                "engagementScore": {
                  "type": "object",
                  "properties": {
                    "min": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    },
                    "max": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    }
                  },
                  "required": [
                    "min",
                    "max"
                  ],
                  "additionalProperties": false
                },
                "socialScore": {
                  "type": "object",
                  "properties": {
                    "min": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    },
                    "max": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    }
                  },
                  "required": [
                    "min",
                    "max"
                  ],
                  "additionalProperties": false
                },
                "youtubeScore": {
                  "type": "object",
                  "properties": {
                    "min": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    },
                    "max": {
                      "nullable": true,
                      "type": "number",
                      "minimum": 0,
                      "maximum": 100
                    }
                  },
                  "required": [
                    "min",
                    "max"
                  ],
                  "additionalProperties": false
                }
              },
              "additionalProperties": false
            },
            "sortOrder": {
              "description": "Specify how results should be sorted",
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "field": {
                    "type": "string",
                    "enum": [
                      "relevance",
                      "recentActivity",
                      "title",
                      "appleReviews",
                      "spotifyReviews"
                    ]
                  },
                  "direction": {
                    "type": "string",
                    "enum": [
                      "asc",
                      "desc"
                    ]
                  },
                  "nullOrder": {
                    "type": "string",
                    "enum": [
                      "first",
                      "last"
                    ]
                  }
                },
                "required": [
                  "field"
                ],
                "additionalProperties": false
              }
            },
            "includeTranscriptSnippet": {
              "type": "boolean"
            },
            "transcriptSnippetLength": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "transcriptHighlightLength": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            },
            "includeEpisodeIds": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "publishedSince": {},
            "hasTranscript": {
              "type": "boolean"
            },
            "episodeUpdatedSince": {},
            "episodeCreatedSince": {}
          },
          "additionalProperties": false
        }
      ]
    },
    "forceRegenerate": {
      "type": "boolean"
    }
  },
  "required": [
    "projectId",
    "podcastId"
  ],
  "additionalProperties": false
}
```

**Response schema:**
```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "OK"
      ]
    },
    "data": {
      "type": "object",
      "properties": {
        "result": {
          "type": "object",
          "properties": {
            "answer": {
              "type": "object",
              "properties": {
                "rating": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 5
                },
                "justification": {
                  "type": "string"
                },
                "strengths": {},
                "concerns": {}
              },
              "required": [
                "rating",
                "justification",
                "strengths",
                "concerns"
              ],
              "additionalProperties": false
            }
          },
          "required": [
            "answer"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "result"
      ],
      "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