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:
| Property | Value |
|---|---|
| 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) |
| Method | POST only |
| Protocol | MCP over JSON-RPC 2.0, protocol version 2025-06-18. One JSON object per request; batch arrays are rejected |
| Methods | initialize, ping, tools/list, tools/call |
| Authentication | A WordPress Application Password of a user with manage_options (an administrator), sent with HTTP Basic auth |
| Allowlist | Optional list of Application Password names in Settings › MCP Server; other passwords get 403 |
| Rate limit | 60 calls per minute per user |
| Response headers | MCP-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
| Situation | HTTP | Body |
|---|---|---|
| Not logged in (no or wrong Application Password) | 401 | WordPress REST error rest_not_logged_in |
| User is not an administrator, or the password is not on the allowlist | 403 | WordPress REST error rest_forbidden |
JSON-RPC notification (no id) | 202 | No body |
| Body is not valid JSON | 200 | JSON-RPC error -32700 |
| Not a single JSON-RPC 2.0 object | 200 | JSON-RPC error -32600 |
| Unknown method | 200 | JSON-RPC error -32601 |
| Unknown or disabled tool, or bad arguments | 200 | JSON-RPC error -32602 |
| Free edition | 200 | JSON-RPC error -32001 |
| Server switched off in the settings | 200 | JSON-RPC error -32002 |
| More than 60 calls in a minute | 429 | JSON-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_):
| Action | Purpose |
|---|---|
promptor_get_ai_suggestion | Ask a question and get the full answer in one response. |
promptor_get_ai_suggestion_stream | Ask a question and get the answer as a stream (see below). |
promptor_save_feedback | Save a thumbs-up or thumbs-down vote. A thumbs-down also flags the question as unanswered. |
promptor_submit_contact_form | Submit the lead or quote form. |
promptor_handoff_event | Record that a visitor picked a handoff channel or opened the live chat. Returns an error when handoff is off. |
promptor_add_to_cart | Add a recommended WooCommerce product (quantity 1) to the cart (Pro). |
promptor_apply_coupon | Apply 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_finalcarries the final structured answer.event: promptor_errorreports 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 thepromptor/chat_actionsfilter)data.handoff:suggest,reasonandsummary(frompromptor/chat_handoff)unanswered: whether the question was flagged as unanswered
Admin AJAX actions
All need a logged-in user with the manage_options capability.
| Area | Actions |
|---|---|
| Knowledge bases and indexing | promptor_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 questions | promptor_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 conversations | promptor_update_submission_status, promptor_get_query_details |
| API key and notifications | promptor_verify_api_key, promptor_send_test_email, promptor_send_test_slack, promptor_save_notification_settings |
| Setup wizard | promptor_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 |
| Notices | promptor_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
| What | Limit | Keyed by |
|---|---|---|
| Chat requests | 20 per minute and 200 per hour | Hash of IP, user agent and user ID |
| Lead form submissions | 20 per 10 minutes | IP |
| Feedback votes | 1 per answer per 5 minutes | Hash of IP, user agent and user ID |
| Handoff events | 5 per 10 minutes | Hash of IP, user agent and user ID |
| MCP calls (Pro) | 60 per minute | WordPress 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
| Status | Error codes |
|---|---|
| 400 | validation_error, invalid_input, empty_query, invalid_history |
| 403 | nonce_failed, unauthorized, all trial errors; also a handoff event while handoff is off |
| 429 | rate_limited, limit_reached (the free edition's 100 AI answers a month), daily_limit_exceeded |
| 500 | configuration_error, save_failed, server_error |
| 502 | api_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
| Destination | When |
|---|---|
https://api.openai.com/v1/chat/completions | Chat answers, language detection, translation, Generate with AI (filterable) |
https://api.openai.com/v1/embeddings | Indexing, each question and the MCP knowledge search; model text-embedding-3-small (filterable) |
https://api.openai.com/v1/models | Verify 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 URL | Pro notifications and handoff transcripts, if turned on |
| Your webhook URL | Pro webhooks, if turned on |
https://yjkfsxbxpreannhzoyad.supabase.co/functions/v1 | Free 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.
| Table | Contents | Key columns |
|---|---|---|
promptor_submissions | Leads | id, 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_queries | Every question and answer | id, 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_embeddings | Indexed content | id, 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 deliveries | id, 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
| Option | Contents |
|---|---|
promptor_api_settings | Settings › AI Behavior, including the OpenAI API key (plain text) |
promptor_ui_settings | Settings › UI Settings |
promptor_language | Settings › UI Settings › Language (empty for Automatic) |
promptor_contexts | Knowledge bases: name, source type, content roles, selected files, example questions, per-KB UI settings |
promptor_crawler_settings | Crawler and crawl schedule settings (Pro) |
promptor_crawl_last_run, promptor_crawl_schedule_state | Last scheduled crawl and its state (Pro) |
promptor_handoff_settings | Settings › Handoff & Channels |
promptor_handoff_log | The last 50 handoff events |
promptor_engagement_settings | Settings › Engagement |
promptor_woo_assistant_settings | Settings › WooCommerce Assistant (Pro) |
promptor_mcp_settings, promptor_mcp_activity_log | Settings › MCP Server and its activity log (Pro) |
promptor_digest_settings, promptor_digest_last_run | Weekly digest (Pro) |
promptor_notification_settings | Notifications (Pro) |
promptor_webhook_settings | Webhooks, including the secret key (Pro) |
promptor_cost_limits | Settings › AI Usage |
promptor_ai_usage | Token usage: 90 daily and 12 monthly buckets (UTC) |
promptor_available_models | Cached model list |
promptor_admin_dark_mode | Admin theme |
promptor_query_count, promptor_limit_reset_date | Free edition: AI answers used this month and the end of the current month, when the counter resets |
promptor_trial_data, promptor_trial_context | Free trial state and content |
The scheduled crawl keeps its position between batches in the transient promptor_crawl_cursor.
Browser storage (visitor side)
| sessionStorage key | Contents |
|---|---|
promptor_chat_v1_<context> | Last 15 messages and selected services for that knowledge base |
promptor_stream_fails | Count of consecutive streaming failures |
promptor_stream_off_until | Time 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
| Event | Schedule | Edition |
|---|---|---|
promptor_telemetry_send | Twice daily, only when telemetry is enabled | Free |
promptor_scheduled_crawl | Hourly, twice daily, daily or weekly, as set in the crawler settings | Pro |
promptor_scheduled_crawl_batch | Single events 30 seconds apart while a crawl runs in batches of 10 pages | Pro |
promptor_weekly_digest | Weekly, on the day and hour set for the digest | Pro |
promptor_webhook_send, promptor_webhook_retry | Single events for each webhook delivery and retry | Pro |
Deactivating Promptor clears the crawl, digest and telemetry events.
Related
Still need help?
Our support team answers every ticket. Tell us your WordPress version, Promptor version and what you see.
