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.

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. The Abilities API requires WordPress 6.9 or later.

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 day. The key includes the normalized question, the knowledge base content version, Answer length, Articles sent as context, Maximum characters per article, the provider and the locale.
• Content version: the wzkb_rest_cache_version option. It changes when a knowledge base article is saved, changes status or is deleted, when a section or product is created, edited or deleted, and when the cache is cleared from the Tools page. A new version changes every answer key, so stale answers are never served.
• 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