Search a podcaster’s catalog from the admin, as the AI Search production panel does
Search a podcaster’s whole back catalog by meaning from your own admin tool, or keep a record of the podcaster’s own lookups, using the route behind the AI Search production panel.
The production panel is a side panel beside every Benecaster admin screen (see Open your own panel beside every Benecaster screen with a shortcut), declared with id ai-search-backend, scope any_show and the shortcut alt+shift+s (Option+Shift+S on a Mac). Its slot is BenecasterShellPanel_ai-search-backend. It is closed on every admin load until the podcaster opens it.
GET /wp-json/benecaster-ai-search/v1/panel/search?q={query}&show_ids={id},{id} is the panel’s search. Admin only: manage_options, through benecaster_rest_permission_admin(), with the X-WP-Nonce header.
show_idsis a comma-separated list. Each show is checked again: one with AI Search switched off is dropped silently, and with none left (or AI Search on for no show at all) the answer is403 benecaster_ai_search_not_active.qis 2 to 200 characters after trimming, or400 benecaster_ai_search_query_invalid.- Not a visitor’s search. No per-visitor rate limit, and it is never counted toward the daily limit on paid searches, nor stopped by it, though each search that reaches the provider is still billed to the podcaster. No access check per result and no
result_visibility: every published episode of the searched shows can be returned, members-only ones included, and a transcript match always counts. - With an embedding provider the query is sent once however many shows are searched; with Anthropic each show’s episode list is ranked by its own call.
- The answer is
200 { results: [ { id, show_id, show_title, title, episode_number, season_number, date, excerpt, excerpt_source } ], unavailable, reason }, best first across all the shows, at most 20.episode_numberandseason_numberare the episode’s own numbers,nullwhen not set;dateis the publish date in the site’s date format.excerptis one line (about 140 characters) of the content that matched: the sentence sharing most of the search’s words, from the piece of text that scored best.excerpt_sourcesays where it came from:episode(title, description, show notes),transcript, or''with no text. A transcript line is quoted only for a user benecaster_user_can_see_transcript() allows (true for anyone who can edit the episode); otherwise, or once the transcript is Hidden, the line comes from the episode’s own text. With Anthropic the line is always from the episode’s own text. Building the excerpt calls no provider.unavailableis true withreasonnot_configured(no provider or key saved) orfailed(a provider call failed; the results are whatever was ranked before it). The provider’s own message goes to the PHP error log only.reasonis''otherwise.- Fields may be added to a result in later versions; none will be removed.
guests, with the Guest Manager add-on:[ { id, name, title, organization, matched, profile_url, record_url, appearance_count, appearances: [ { id, show_id, show_title, title, date } ] } ], at most 10.- Read from Guest Manager’s whole roster (benecaster_guest_manager_get_guests() and benecaster_guest_manager_get_guest_episodes()), so a guest on no published episode of the searched shows yet is listed too, with
appearance_count0.[]when Guest Manager is off on every searched show. matchedsays why:name,organizationortitle(the search is part of that field, or the whole field is inside the search at word boundaries; letter case, accents and punctuation ignored; at least 3 characters either way), in that order, each A to Z by name; thenbio(by its words, whole words of four letters or more, and with OpenAI, Google Gemini or Cohere by meaning, at most three per search, each at least as close as the fifth-best episode result); thenepisodes, guests of the five best episode results, in the order of those episodes. Text matching calls no provider, soguestscan be filled whileunavailableis true.appearancesare the guest’s newest five episodes among the searched shows, newest first, andappearance_countcounts them all.record_urlis Guest Manager’s own address for the guest’s record (''when it gives none);profile_urlis their public page.[]when nothing matches. Each show’s list is cached for up to an hour and cleared whenever a guest, an episode’s guests, an episode’s published state or an add-on’s per-show switch changes.
- Read from Guest Manager’s whole roster (benecaster_guest_manager_get_guests() and benecaster_guest_manager_get_guest_episodes()), so a guest on no published episode of the searched shows yet is listed too, with
The hooks:
benecaster_ai_search_before_panel_search( string $query, int[] $show_ids ), with only the shows that passed the check. Fires before the provider is asked; not for a refused request.benecaster_ai_search_panel_results( array $results, string $query, int[] $show_ids ): arrayfilters the list above. Admin only, so it may add anything the podcaster may see.benecaster_ai_search_panel_guest_results( array $guests, string $query, int[] $show_ids ): arrayfilters theguestslist above; a non-array becomes[]. It runs afterbenecaster_ai_search_panel_results, and theepisodesguests come from that filter’s output.benecaster_ai_search_after_panel_search( string $query, int[] $show_ids, array $results ), with the filtered episode results (not the guests).
Code
<?php
// Keep a short history of the podcaster's own lookups, for the team's prep notes.
add_action( 'benecaster_ai_search_after_panel_search', function ( string $query, array $show_ids, array $results ): void {
$log = (array) get_option( 'my_prep_lookups', [] );
$log[] = [ 'q' => $query, 'shows' => $show_ids, 'found' => array_column( $results, 'id' ), 'at' => gmdate( 'Y-m-d H:i:s' ) ];
update_option( 'my_prep_lookups', array_slice( $log, -50 ), false );
}, 10, 3 );
Hooks Used
Need this built rather than just documented? See our services →