Ask the Docs developer reference

This reference covers the REST endpoint, the Abilities API ability, and the filters and actions behind Ask the Docs in Knowledge Base Pro. For setup and settings, see Ask the Docs: AI answers from your knowledge base.

Ask the Docs needs WordPress 7.0 or later. On older versions none of these hooks, routes or abilities are registered.

REST endpoint

POST /wp-json/wzkb/v1/ask with a JSON body:

{ "question": "How do I get a refund?" }

Questions must be 3 to 300 characters after HTML tags are stripped and whitespace is collapsed.

Response

Errors

When the daily cap is reached, the endpoint returns 200 with answered set to false and reason set to daily_cap.

When several visitors ask the same uncached question at once, only the first request calls the provider. The others wait for its answer and return it from the cache. If the provider is still working when the wait ends, they return 200 with answered set to false and reason set to provider_busy, rather than paying for a second provider call.

Answer validation

The provider replies with whether it answered, the answer text and the IDs of the articles it used. Source IDs that were not sent are discarded, and an answer with no valid sources is treated as unanswered. Source links are built from your articles, never from the model’s output, and the answer is returned as plain text. A malformed reply returns reason invalid_response and is not cached, so the next request gets a fresh attempt.

Bot check

Before any cache or provider work, the endpoint refuses requests with an empty user agent, or one that contains any of these, ignoring case: bot, crawl, spider, slurp, scrap, headless, phantom, puppeteer, playwright, selenium, curl, wget, python, httpclient, http-client, okhttp, axios, node-fetch, java/, libwww, guzzle, postman, insomnia.

A script can send a browser’s user agent, so the visitor limit and daily cap remain the limits on cost. Use wzkb_ai_is_bot to allow or block specific user agents:

add_filter(
    'wzkb_ai_is_bot',
    function ( $is_bot, $user_agent ) {
        // Allow an internal monitoring tool.
        return str_contains( $user_agent, 'AcmeMonitor/' ) ? false : $is_bot;
    },
    10,
    2
);

Ability

Knowledge Base Pro registers the knowledgebase/ask ability with the WordPress Abilities API, in the shared webberzone category. It takes { "question": "..." }, returns the same data as the REST endpoint, and runs through the same cache and limits. It is registered only on WordPress 7.0 or later, where Ask the Docs loads.

It is limited to logged-in users by default, because the Abilities API route cannot check that a request comes from your site the way the REST endpoint does. The bot check does not apply to it. Use wzkb_ai_ability_permission to change who can run it:

add_filter( 'wzkb_ai_ability_permission', '__return_true' );

Filters

Custom retriever

A retriever implements WebberZoneKnowledge_BaseProAIRetriever_Interface. Its retrieve( string $question, int $limit ): array method returns articles, most relevant first, each with id (int), title, url and content (plain text).

add_filter(
    'wzkb_ai_retriever',
    function ( $retriever ) {
        return new My_Embeddings_Retriever();
    }
);

Visitors behind a proxy

add_filter(
    'wzkb_ai_visitor_ip',
    function ( $ip ) {
        // Only trust this header if your proxy always sets it.
        return isset( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ? sanitize_text_field( wp_unslash( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ) : $ip;
    }
);

Actions

add_action(
    'wzkb_cache_cleared',
    function () {
        delete_transient( 'my_kb_cache' );
    }
);

Caching

• Answers: transients prefixed wzkb_ai_answer_, kept for a week. The key includes the canonical question (Ask_Handler::canonical_question()), the content version, Answer length, Articles sent as context, Maximum characters per article, the provider and model, and the locale.
• Article fingerprints: each answer stores a fingerprint of every article sent to the provider, taken before the request: its modified date plus the _wzkb_ai_rev post meta, which changes when the article is updated or its terms change. A changed fingerprint, or an article that is no longer published, makes the answer a miss. Answer_Cache::touch_post() retires the answers built from an article when it changes in a way the plugin cannot see.
• Content version: the wzkb_ai_content_version option. It changes when the settings are saved, when a knowledge base term is edited or deleted, and when the cache is cleared from the Tools page, and retires every answer.
• Unanswered version: the wzkb_ai_publish_version option. It changes when an article is published or updated and retires only cached unanswered results.
• Provider pauses: wzkb_ai_trip_* and wzkb_ai_failures_* transients. A network, rate-limit, quota or server error pauses a provider for 5 minutes, doubling up to an hour, and the next provider in the chain (the AI provider, then the fallback provider) is tried. A successful request clears the pause.
• Provider status: the wzkb_ai_provider_available transient, kept for a week when a provider is available and for 10 minutes when it isn’t. It is deleted when a provider request fails, when any plugin is activated or deactivated, when the AI provider setting changes, and when the cache is cleared. The AI settings tab checks again in the background when it is missing.

See also

• Ask the Docs: AI answers from your knowledge base
• Knowledge Base Abilities API
• Knowledge Base REST API