Developers

AJAX endpoints, REST routes and data storage

Technical reference for Promptor 2.1.0: AJAX actions, the Pro MCP REST route, streaming format, rate limits, tables, options and cron events.

This page describes how Promptor 2.1.0 talks to WordPress and where it keeps its data. Use it for firewall and cache rules, security reviews, debugging and data migrations.

The AJAX actions are Promptor's internal interface, not a public API. Request parameters are not documented and may change between versions. To react to new leads, use the promptor_lead_created action (see Hooks and filters) or Pro webhooks. For read access from AI tools, use the Pro MCP server.

REST API: the MCP endpoint

The chat itself does not use the REST API. Promptor 2.1.0 registers one REST route, for the MCP server:

PropertyValue
URL/wp-json/promptor/v1/mcp (the part after promptor/v1/ is the Endpoint path in Settings › MCP Server, default mcp, and can be changed with the promptor/mcp_route filter)
MethodPOST only
ProtocolMCP over JSON-RPC 2.0, protocol version 2025-06-18. One JSON object per request; batch arrays are rejected
Methodsinitialize, ping, tools/list, tools/call
AuthenticationA WordPress Application Password of a user with manage_options (an administrator), sent with HTTP Basic auth
AllowlistOptional list of Application Password names in Settings › MCP Server; other passwords get 403
Rate limit60 calls per minute per user
Response headersMCP-Protocol-Version: 2025-06-18, Cache-Control: no-store

The server is read-only. Its six tools are promptor_list_knowledge_bases, promptor_search_knowledge, promptor_list_leads, promptor_get_stats, promptor_list_unanswered and promptor_list_conversations. Each can be switched off in the settings. When the WordPress Abilities API is available (wp_register_ability()), the same tools are also registered as abilities named promptor/list-knowledge-bases, promptor/search-knowledge, promptor/list-leads, promptor/get-stats, promptor/list-unanswered and promptor/list-conversations in the category promptor. Setup for Claude, ChatGPT and Cursor is in Connect Claude, ChatGPT or Cursor with the MCP server.

The MCP server is part of Promptor Pro and is off until you enable it. The free edition registers the same route but answers every call with a "Pro feature" error. Compare plans.

Responses and errors

SituationHTTPBody
Not logged in (no or wrong Application Password)401WordPress REST error rest_not_logged_in
User is not an administrator, or the password is not on the allowlist403WordPress REST error rest_forbidden
JSON-RPC notification (no id)202No body
Body is not valid JSON200JSON-RPC error -32700
Not a single JSON-RPC 2.0 object200JSON-RPC error -32600
Unknown method200JSON-RPC error -32601
Unknown or disabled tool, or bad arguments200JSON-RPC error -32602
Free edition200JSON-RPC error -32001
Server switched off in the settings200JSON-RPC error -32002
More than 60 calls in a minute429JSON-RPC error -32029, header Retry-After: 60

When a tool runs but fails (for example no OpenAI key is saved for promptor_search_knowledge), the result has isError: true and the message as text, as the MCP specification asks. Successful tool results carry the data both as JSON text and as structuredContent.

Promptor keeps the last 50 MCP calls (tool, duration, success) in the option promptor_mcp_activity_log, shown in Settings › MCP Server.

Public AJAX actions

All other requests go through /wp-admin/admin-ajax.php. These actions are registered for both logged-in users and visitors (wp_ajax_ and wp_ajax_nopriv_):

ActionPurpose
promptor_get_ai_suggestionAsk a question and get the full answer in one response.
promptor_get_ai_suggestion_streamAsk a question and get the answer as a stream (see below).
promptor_save_feedbackSave a thumbs-up or thumbs-down vote. A thumbs-down also flags the question as unanswered.
promptor_submit_contact_formSubmit the lead or quote form.
promptor_handoff_eventRecord that a visitor picked a handoff channel or opened the live chat. Returns an error when handoff is off.
promptor_add_to_cartAdd a recommended WooCommerce product (quantity 1) to the cart (Pro).
promptor_apply_couponApply the coupon offered by the assistant to the cart (Pro, WooCommerce).

Each request carries a nonce. The nonces are printed into the page in the inline objects promptor_data_<context>, promptor_public and, on Pro shops, promptor_woo_assistant, so a page cached for longer than the nonce lifetime makes these requests fail. See Caching plugins.

Streaming format

promptor_get_ai_suggestion_stream responds with Content-Type: text/event-stream (Server-Sent Events):

data: {"delta":"Hello"}

data: {"delta":", how can I help?"}

event: promptor_final
data: {...}

data: [DONE]
  • data: {"delta":…} carries the next piece of text. Since 2.1.0 the first words arrive as soon as the model writes them.
  • event: promptor_final carries the final structured answer.
  • event: promptor_error reports an error.
  • data: [DONE] ends the stream.

To get past buffering proxies, the response sends about 2 KB of padding and the header X-Accel-Buffering: no, and disables zlib and gzip compression. The browser falls back to promptor_get_ai_suggestion when:

  • the server answers stream_unsupported (free trial or WordPress AI Client)
  • no first byte arrives within 6,000 ms, or the response is not text/event-stream
  • streaming failed twice in a row; it then stays off for 6 hours in that browser tab

Structured answer

The AI is asked for JSON with the keys explanation, recommended_services, recommended_products, recommended_articles, recommended_faqs and off_topic. When off_topic is true, Promptor empties every recommendation and keeps only the handoff chip. The full answer and the cards are stored in promptor_queries.ai_response_raw.

The response sent to the widget also contains:

  • data.actions: the action chips (from the promptor/chat_actions filter)
  • data.handoff: suggest, reason and summary (from promptor/chat_handoff)
  • unanswered: whether the question was flagged as unanswered

Admin AJAX actions

All need a logged-in user with the manage_options capability.

AreaActions
Knowledge bases and indexingpromptor_add_context, promptor_delete_context, promptor_get_indexing_stats, promptor_save_content_selection, promptor_bulk_update_roles, promptor_update_single_role, promptor_generate_example_questions, promptor_load_more_content, promptor_start_sync, promptor_start_crawl, promptor_process_item, promptor_clear_index
Q&A entries and unanswered questionspromptor_qa_save, promptor_qa_delete, promptor_add_unanswered_to_kb
Scheduled crawling and digest (Pro)promptor_run_crawl_now, promptor_send_test_digest
Leads and conversationspromptor_update_submission_status, promptor_get_query_details
API key and notificationspromptor_verify_api_key, promptor_send_test_email, promptor_send_test_slack, promptor_save_notification_settings
Setup wizardpromptor_wizard_load_content, promptor_wizard_save_api, promptor_wizard_save_content, promptor_wizard_complete
Free trial and telemetry (free edition)promptor_trial_activate, promptor_trial_status, promptor_trial_index_content, promptor_wizard_telemetry_optin
Noticespromptor_dismiss_review_prompt, promptor_dismiss_onboarding (free edition)

admin-post.php actions: promptor_save_ui_settings (both editions; also saves the Language setting), promptor_save_telemetry, promptor_reset_telemetry_id, promptor_clear_telemetry_queue (free edition) and promptor_clear_cache (Pro).

Rate limits

WhatLimitKeyed by
Chat requests20 per minute and 200 per hourHash of IP, user agent and user ID
Lead form submissions20 per 10 minutesIP
Feedback votes1 per answer per 5 minutesHash of IP, user agent and user ID
Handoff events5 per 10 minutesHash of IP, user agent and user ID
MCP calls (Pro)60 per minuteWordPress user

Visitor counters are stored in transients named promptor_rl_*. IP addresses are only hashed for these keys, never stored in tables.

HTTP status codes

StatusError codes
400validation_error, invalid_input, empty_query, invalid_history
403nonce_failed, unauthorized, all trial errors; also a handoff event while handoff is off
429rate_limited, limit_reached (the free edition's 100 AI answers a month), daily_limit_exceeded
500configuration_error, save_failed, server_error
502api_error, api_request_failed, embedding_request_failed

The usage-limit pause in Settings › AI Usage returns the error code daily_limit_exceeded for both daily and monthly token limits.

Outgoing requests

DestinationWhen
https://api.openai.com/v1/chat/completionsChat answers, language detection, translation, Generate with AI (filterable)
https://api.openai.com/v1/embeddingsIndexing, each question and the MCP knowledge search; model text-embedding-3-small (filterable)
https://api.openai.com/v1/modelsVerify Key and the weekly model list refresh (filterable)
WordPress AI Client (wp_ai_client_prompt())Chat answers when that provider is selected
Your Slack webhook URLPro notifications and handoff transcripts, if turned on
Your webhook URLPro webhooks, if turned on
https://yjkfsxbxpreannhzoyad.supabase.co/functions/v1Free trial and opt-in telemetry only (free edition)

Timeouts: 45 s for a normal answer, 60 s for a stream.

Database tables

All tables use your WordPress table prefix.

TableContentsKey columns
promptor_submissionsLeadsid, name, email, phone, recommendations, notes, query_id, submitted_at, status (pending, contacted, converted, rejected), is_demo, linked_order_id, order_value, source, meta (JSON, holds lead scoring in Pro)
promptor_queriesEvery question and answerid, user_query, ai_response_raw, suggested_service_titles, products_added_to_cart, is_demo, is_archived, linked_order_id, order_value, query_timestamp, status_code, feedback (1, -1 or NULL), response_time_ms, similarity_score, tokens_used, query_cost, context_name, unanswered (new in 2.1.0: 1 for no-context answers and thumbs-down votes)
promptor_embeddingsIndexed contentid, post_id, post_type, content_chunk, vector_data (JSON), item_vector (JSON), token_count, context_name, is_demo, created_at
promptor_webhook_logs (Pro)Webhook deliveriesid, event, lead_id, url, payload, response_code, response_body, attempt, status (pending, paused, success, failed), created_at, delivered_at, error_message

Content is split into chunks of up to 1,000 characters. Pages crawled by the Pro crawler are stored with post_type url; files with attachment; Q&A entries with promptor_qa.

Schema changes run automatically on admin_init when the stored promptor_db_version differs from the plugin version.

Q&A entries

Q&A entries are stored as private posts of the post type promptor_qa. They have no admin screen or public URL of their own; you manage them in the knowledge base's Q&A tab. Each entry is indexed as one Q: … A: … chunk and counted with the role faq. See Add Q&A entries.

Options

OptionContents
promptor_api_settingsSettings › AI Behavior, including the OpenAI API key (plain text)
promptor_ui_settingsSettings › UI Settings
promptor_languageSettings › UI Settings › Language (empty for Automatic)
promptor_contextsKnowledge bases: name, source type, content roles, selected files, example questions, per-KB UI settings
promptor_crawler_settingsCrawler and crawl schedule settings (Pro)
promptor_crawl_last_run, promptor_crawl_schedule_stateLast scheduled crawl and its state (Pro)
promptor_handoff_settingsSettings › Handoff & Channels
promptor_handoff_logThe last 50 handoff events
promptor_engagement_settingsSettings › Engagement
promptor_woo_assistant_settingsSettings › WooCommerce Assistant (Pro)
promptor_mcp_settings, promptor_mcp_activity_logSettings › MCP Server and its activity log (Pro)
promptor_digest_settings, promptor_digest_last_runWeekly digest (Pro)
promptor_notification_settingsNotifications (Pro)
promptor_webhook_settingsWebhooks, including the secret key (Pro)
promptor_cost_limitsSettings › AI Usage
promptor_ai_usageToken usage: 90 daily and 12 monthly buckets (UTC)
promptor_available_modelsCached model list
promptor_admin_dark_modeAdmin theme
promptor_query_count, promptor_limit_reset_dateFree edition: AI answers used this month and the end of the current month, when the counter resets
promptor_trial_data, promptor_trial_contextFree trial state and content

The scheduled crawl keeps its position between batches in the transient promptor_crawl_cursor.

Browser storage (visitor side)

sessionStorage keyContents
promptor_chat_v1_<context>Last 15 messages and selected services for that knowledge base
promptor_stream_failsCount of consecutive streaming failures
promptor_stream_off_untilTime until streaming is retried
promptor_engaged_<context>Set once an engagement trigger (delay, scroll or exit intent) has opened the popup, so it fires once per session (Pro)

WooCommerce order attribution

Add to Cart from the chat stores promptor_query_id on the cart item. At checkout it becomes the order item meta _promptor_query_id. On the thank-you page, the matching promptor_queries row gets linked_order_id and order_value.

Cron

EventScheduleEdition
promptor_telemetry_sendTwice daily, only when telemetry is enabledFree
promptor_scheduled_crawlHourly, twice daily, daily or weekly, as set in the crawler settingsPro
promptor_scheduled_crawl_batchSingle events 30 seconds apart while a crawl runs in batches of 10 pagesPro
promptor_weekly_digestWeekly, on the day and hour set for the digestPro
promptor_webhook_send, promptor_webhook_retrySingle events for each webhook delivery and retryPro

Deactivating Promptor clears the crawl, digest and telemetry events.

Still need help?

Our support team answers every ticket. Tell us your WordPress version, Promptor version and what you see.

Read the FAQSee what changed in each version

Open a support ticket

All help topics