> ## Documentation Index > Fetch the complete documentation index at: https://aisa.one/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > - Base URLs: models `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`); data APIs `https://api.aisa.one/apis/v1`. The `servers` of each operation in https://aisa.one/openapi.yaml is authoritative. > - Auth: `Authorization: Bearer $AISA_API_KEY`. Never print, log, or commit the key. > - MCP (preferred for agents): `https://mcp.aisa.one/mcp`, signed in with OAuth, so there is no key to paste. > - Agent Skill: `npx skills add AIsa-team/agent-skills --skill aisa`. Fallback with the AIsa CLI: `aisa skills install aisa`. > - Spending: docs, https://aisa.one/models, https://aisa.one/api, `/v1/models`, and MCP `search`, `list_categories`, `get_details`, `batch_quote`, and the `account` operation are free. Quote the exact calls before running them (MCP `batch_quote`, CLI `aisa quote --json`). If the quote reports `auto_execute_eligible: true`, run it unless the user set a tighter limit or asked only for a quote. Otherwise, tell the user in one message the planned calls, the quoted price, and a total USD budget for the task, then wait for approval. Direct HTTP calls follow the stricter rule at https://aisa.one/docs/get-started/cli.md#direct-http-fallback. Do not make paid calls to test availability. Full rule: https://aisa.one/llms.txt # Fetch best podcasts list > Usage-based billing; Default request estimate: $0.0403 USD (not a fixed price). Declared unit rate: $0.000001 USD per provider_credit. Account-specific pricing and final settlement may differ. ## Request contract * **Method and path:** POST /apis/v1/listennotes/fetch-a-list-of-best-podcasts-by-genre * **Availability:** enabled * **Request URL template:** `https://api.aisa.one/apis/v1/listennotes/fetch-a-list-of-best-podcasts-by-genre` * **Runtime facts:** 3f699076c1baf63c05edde2629715e34586e70ee0982cdee89366394f35facf8 [Complete OpenAPI definition](https://aisa.one/docs/reference-contracts/listennotes.json) Effective request and pricing declaration (including authentication and referenced schemas): ```json theme={null} { "operationId": "listennotes.fetch-a-list-of-best-podcasts-by-genre", "method": "POST", "path": "/apis/v1/listennotes/fetch-a-list-of-best-podcasts-by-genre", "servers": [ { "url": "https://api.aisa.one" } ], "parameters": [], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "type": "integer", "description": "Page number of those podcasts in this genre." }, "sort": { "enum": [ "listen_score", "oldest_added_first", "oldest_published_first", "recent_added_first", "recent_published_first" ], "type": "string", "default": "recent_added_first", "description": "How do you want to sort these podcasts? If you\"d like to sort by popularity, please use **listen_score**. " }, "region": { "type": "string", "default": "us", "description": "Filter best podcasts by country/region. Please note that podcasts that are \"best\" in a country/region may not be produced in that country/region. For example, a podcast from the US may be very popular in Canada. You can get the supported country codes (e.g., us, jp, gb...) from `GET /regions`. If not specified, you\"ll get \"best podcasts\" in United States. " }, "genre_id": { "type": "string", "description": "You can get the id from `GET /genres`. If not specified, it\"ll be the overall best podcasts, which can be considered as a special genre. " }, "language": { "type": "string", "description": "Filter best podcasts by language. You can get a list of supported languages (e.g., English, Chinese, Japanese...) from `GET /languages`. If not specified, you\"ll get \"best podcasts\" in any language. " }, "safe_mode": { "type": "integer", "default": 0, "description": "Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no. " }, "publisher_region": { "type": "string", "description": "Filter best podcasts by the publisher\"s country/region. This is to narrow down the results to include \"best podcasts\" produced in a specific country/region. You can get the supported country codes (e.g., us, jp, gb...) from `GET /regions`. If not specified, you\"ll get \"best podcasts\" produced in any country/region. If you want to get a country/region\"s \"best podcasts\" that are also produced in that country/region, then you need to specify both **region** and **publisher_region**, e.g., `region=jp` and `publisher_region=jp`. " } } } } } }, "x-aisa-status": "enabled", "x-aisa-pricing": { "cost_contract": "response_units", "customer_multiplier": 1.0, "customer_pricing": "provider_cost_multiplier", "default_request_estimate_usd": 0.0403, "estimate_source": "profile_seed", "evidence_source": "response_body", "maximum_units": 10000000, "unit": "provider_credit", "unit_rate_usd": 1e-06 }, "components": { "securitySchemes": { "bearerAuth": { "scheme": "bearer", "type": "http" } } } } ``` ## Cost and request rules Usage-based billing; Default request estimate: \$0.0403 USD (not a fixed price). Declared unit rate: \$0.000001 USD per provider\_credit. Account-specific pricing and final settlement may differ. Published reference values are not an account-specific quote or a settled charge. For endpoints supporting X-AISA-Cost-Mode: quote, obtain a free quote for your exact request before execution; reconcile the settled cost with response metadata and Usage Logs. USD amounts use 1,000,000 integer micro-USD per dollar. * **Default request reference estimate (USD):** 0.0403 * **Declared unit rate (USD):** 1e-06 * **Billing unit:** provider\_credit * **Cost contract:** response\_units * **Published reference multiplier:** 1.0 * **Declared maximum count/units:** 10000000 * **Settlement evidence source:** response\_body ## OpenAPI ````yaml reference-contracts/listennotes.json POST /apis/v1/listennotes/fetch-a-list-of-best-podcasts-by-genre openapi: 3.1.0 info: description: '' title: Listen Notes version: '1' x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote x-aisa-configured-paths: - /apis/v1/listennotes/batch-fetch-basic-meta-data-for-episodes - /apis/v1/listennotes/batch-fetch-basic-meta-data-for-podcasts - /apis/v1/listennotes/fetch-a-curated-list-of-podcasts-by-id - /apis/v1/listennotes/fetch-a-list-of-best-podcasts-by-genre - /apis/v1/listennotes/fetch-a-list-of-podcast-genres - /apis/v1/listennotes/fetch-a-random-podcast-episode - /apis/v1/listennotes/fetch-audience-demographics-for-a-podcast - /apis/v1/listennotes/fetch-curated-lists-of-podcasts - /apis/v1/listennotes/fetch-detailed-meta-data-for-an-episode-by-id - /apis/v1/listennotes/fetch-podcast-episodes-by-id - /apis/v1/listennotes/fetch-podcast-languages - /apis/v1/listennotes/fetch-podcasts-by-a-publisher-s-domain-name - /apis/v1/listennotes/fetch-recommendations-for-a-podcast - /apis/v1/listennotes/fetch-recommendations-for-an-episode - /apis/v1/listennotes/fetch-related-search-terms - /apis/v1/listennotes/fetch-supported-regions - /apis/v1/listennotes/fetch-trending-search-terms - /apis/v1/listennotes/find-episodes-by-title - /apis/v1/listennotes/full-text-search - /apis/v1/listennotes/typeahead-search x-aisa-document: facts_hash: 3f699076c1baf63c05edde2629715e34586e70ee0982cdee89366394f35facf8 generator_version: '3' protocol_version: '1' schema_version: '1' composer_version: '28' response_pending: [] document_hash: sha256:bd77c0884b58e4fbb6600c9c74a804ea4c4a004f668af8485e1b70fec19e76d1 x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-provider: listennotes x-aisa-catalogs: listennotes: title: Listen Notes description: '' x-aisa-document: facts_hash: 3f699076c1baf63c05edde2629715e34586e70ee0982cdee89366394f35facf8 generator_version: '3' protocol_version: '1' schema_version: '1' x-aisa-plans: builder: 1 display_plan: payg payg: 1 similarweb_payg: 1 team: 1 version: e70a0959cd1b93b84ae16dffd7a538273ddb9c1d46277b82823c37ff1b6bc0fb x-aisa-capabilities: idempotency: Idempotency-Key max_price: X-AISA-Max-Price-USD quote: header: X-AISA-Cost-Mode value: quote servers: - url: https://api.aisa.one security: - bearerAuth: [] paths: /apis/v1/listennotes/fetch-a-list-of-best-podcasts-by-genre: post: tags: - Listen Notes summary: Fetch best podcasts list description: >- Usage-based billing; Default request estimate: $0.0403 USD (not a fixed price). Declared unit rate: $0.000001 USD per provider_credit. Account-specific pricing and final settlement may differ. operationId: listennotes.fetch-a-list-of-best-podcasts-by-genre requestBody: required: false content: application/json: schema: type: object properties: page: type: integer description: Page number of those podcasts in this genre. sort: enum: - listen_score - oldest_added_first - oldest_published_first - recent_added_first - recent_published_first type: string default: recent_added_first description: >- How do you want to sort these podcasts? If you"d like to sort by popularity, please use **listen_score**. region: type: string default: us description: >- Filter best podcasts by country/region. Please note that podcasts that are "best" in a country/region may not be produced in that country/region. For example, a podcast from the US may be very popular in Canada. You can get the supported country codes (e.g., us, jp, gb...) from `GET /regions`. If not specified, you"ll get "best podcasts" in United States. genre_id: type: string description: >- You can get the id from `GET /genres`. If not specified, it"ll be the overall best podcasts, which can be considered as a special genre. language: type: string description: >- Filter best podcasts by language. You can get a list of supported languages (e.g., English, Chinese, Japanese...) from `GET /languages`. If not specified, you"ll get "best podcasts" in any language. safe_mode: type: integer default: 0 description: >- Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no. publisher_region: type: string description: >- Filter best podcasts by the publisher"s country/region. This is to narrow down the results to include "best podcasts" produced in a specific country/region. You can get the supported country codes (e.g., us, jp, gb...) from `GET /regions`. If not specified, you"ll get "best podcasts" produced in any country/region. If you want to get a country/region"s "best podcasts" that are also produced in that country/region, then you need to specify both **region** and **publisher_region**, e.g., `region=jp` and `publisher_region=jp`. responses: '200': description: Tool result data content: application/json: schema: $ref: >- #/components/schemas/Response576A0Ea506F3_connect_LISTENNOTES_FETCH_A_LIST_OF_BEST_PODCASTS_BY_GENRE__output__public_data default: content: application/json: schema: {} description: >- Error response; upstream passthrough responses may use provider formats components: schemas: Response576A0Ea506F3_connect_LISTENNOTES_FETCH_A_LIST_OF_BEST_PODCASTS_BY_GENRE__output__public_data: $ref: >- #/components/schemas/Response576A0Ea506F3_connect_LISTENNOTES_FETCH_A_LIST_OF_BEST_PODCASTS_BY_GENRE__output__41794a55f545946b Response576A0Ea506F3_connect_LISTENNOTES_FETCH_A_LIST_OF_BEST_PODCASTS_BY_GENRE__output__41794a55f545946b: type: object required: - data properties: data: $ref: >- #/components/schemas/Response576A0Ea506F3_connect_LISTENNOTES_FETCH_A_LIST_OF_BEST_PODCASTS_BY_GENRE__output__cad6072e01a87fc4 Response576A0Ea506F3_connect_LISTENNOTES_FETCH_A_LIST_OF_BEST_PODCASTS_BY_GENRE__output__cad6072e01a87fc4: type: object required: - has_previous - name - listennotes_url - previous_page_number - page_number - has_next - next_page_number - parent_id - id - total - podcasts properties: id: type: integer examples: - 95 name: type: string examples: - Business News total: type: integer examples: - 325 has_next: type: boolean examples: - true podcasts: type: array items: $ref: >- #/components/schemas/Response576A0Ea506F3_connect_LISTENNOTES_FETCH_A_LIST_OF_BEST_PODCASTS_BY_GENRE__output__8759638295d1e25d parent_id: type: integer examples: - 93 page_number: type: integer examples: - 2 has_previous: type: boolean examples: - true listennotes_url: type: string examples: - https://www.listennotes.com/best-business-news-podcasts-95/ next_page_number: type: integer examples: - 3 previous_page_number: type: integer examples: - 1 Response576A0Ea506F3_connect_LISTENNOTES_FETCH_A_LIST_OF_BEST_PODCASTS_BY_GENRE__output__8759638295d1e25d: type: object properties: id: type: string examples: - 4d3fe717742d4963a85562e9f84d8c79 rss: type: string examples: - https://sw7x7.libsyn.com/rss type: $ref: >- #/components/schemas/Response576A0Ea506F3_connect_LISTENNOTES_FETCH_A_LIST_OF_BEST_PODCASTS_BY_GENRE__output__9a819c5ce16785dc examples: - episodic email: type: string examples: - hello@example.com extra: $ref: >- #/components/schemas/Response576A0Ea506F3_connect_LISTENNOTES_FETCH_A_LIST_OF_BEST_PODCASTS_BY_GENRE__output__d930abe0d81bf0f6 image: type: string examples: - >- https://cdn-images-3.listennotes.com/podcasts/exponent-ben-thompson-james-allworth-OaJSjb4xQv3.1400x1400.jpg title: type: string examples: - Star Wars 7x7 | Star Wars News, Interviews, and More! country: type: string examples: - United States website: type: string examples: - http://sw7x7.com/ language: type: string examples: - English genre_ids: type: array items: type: integer examples: - - 138 - 86 - 160 - 68 - 82 - 100 - 101 itunes_id: type: integer examples: - 896354638 publisher: type: string examples: - Planet Broadcasting thumbnail: type: string examples: - >- https://cdn-images-3.listennotes.com/podcasts/exponent-ben-thompson-james-allworth-OaJSjb4xQv3.300x300.jpg is_claimed: type: boolean examples: - true description: type: string examples: - >-

The Star Wars 7x7 Podcast is Rebel-rousing fun for everyday Jedi, between 7 and 14 minutes a day, 7 days a week. Join host Allen Voivod for Star Wars news, history, interviews, trivia, and deep dives into the Star Wars story as told in movies, books, comics, games, cartoons, and more. Subscribe now for your daily dose of Star Wars joy. It's destiny unleashed!

looking_for: $ref: >- #/components/schemas/Response576A0Ea506F3_connect_LISTENNOTES_FETCH_A_LIST_OF_BEST_PODCASTS_BY_GENRE__output__5072254562346fda has_sponsors: type: boolean examples: - false listen_score: type: integer examples: - 81 total_episodes: type: integer examples: - 324 listennotes_url: type: string examples: - https://www.listennotes.com/c/4d3fe717742d4963a85562e9f84d8c79/ audio_length_sec: type: integer examples: - 1291 explicit_content: type: boolean examples: - false latest_episode_id: type: string examples: - d057092e57cc4ced80e0efaa196593d9 latest_pub_date_ms: type: integer examples: - 1557499770000 earliest_pub_date_ms: type: integer examples: - 1470667902000 has_guest_interviews: type: boolean examples: - false update_frequency_hours: type: integer examples: - 168 listen_score_global_rank: type: string examples: - 0.5% Response576A0Ea506F3_connect_LISTENNOTES_FETCH_A_LIST_OF_BEST_PODCASTS_BY_GENRE__output__9a819c5ce16785dc: enum: - episodic - serial type: string Response576A0Ea506F3_connect_LISTENNOTES_FETCH_A_LIST_OF_BEST_PODCASTS_BY_GENRE__output__d930abe0d81bf0f6: type: object properties: url1: type: string url2: type: string url3: type: string spotify_url: type: string examples: - https://open.spotify.com/show/2rQJUP9Y3HxemiW3JHt9WV youtube_url: type: string examples: - https://www.youtube.com/sw7x7 linkedin_url: type: string wechat_handle: type: string patreon_handle: type: string examples: - sw7x7 twitter_handle: type: string examples: - SW7x7podcast facebook_handle: type: string examples: - sw7x7 amazon_music_url: type: string examples: - >- https://music.amazon.com/podcasts/6fc6d683-9ef3-4850-9c35-8e8b1a42a147/the-lock-sportscast instagram_handle: type: string examples: - sw7x7 Response576A0Ea506F3_connect_LISTENNOTES_FETCH_A_LIST_OF_BEST_PODCASTS_BY_GENRE__output__5072254562346fda: type: object properties: guests: type: boolean examples: - true cohosts: type: boolean examples: - true sponsors: type: boolean examples: - true cross_promotion: type: boolean examples: - true securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.