MxChat REST API

MxChat REST API

MxChat ships a bearer-token-authenticated REST API for reading transcripts, deleting chat data, and pushing content into the knowledge base. The endpoints are general-purpose primitives — they power MxChat’s own daily FAQ agent, but they are equally useful for analytics exports, external automations (n8n, Zapier, Make), data migrations, and custom RAG pipelines.

Base URL: https://yoursite.com/wp-json/mxchat/v1/

All authenticated requests use a bearer token in the Authorization header. When no token has been generated, every authenticated route returns 401, so the API surface is zero until you explicitly enable it.

Generating a Token

1. In your WordPress admin, open MxChat → API Access.
2. Click Generate Token. A 48-character token is created and displayed once — copy it somewhere safe immediately.
3. Paste the token into the tool that will call the API.

To rotate the token, click Rotate Token on the same page (the old token is invalidated). To disable the API entirely, click Revoke Token — all authenticated endpoints will start returning 401 until a new token is generated.

The token is stored hashed and verified in constant time. Keep it out of public repositories and client-side code; it grants read access to chat transcripts.

Authentication

Send the token in the Authorization header on every request except /health:

Authorization: Bearer YOUR_TOKEN_HERE

A missing or wrong token returns:

HTTP/1.1 401 Unauthorized
{"code":"mxchat_rest_unauthorized","message":"Invalid bearer token.","data":{"status":401}}

Endpoints

GET /health

Unauthenticated connectivity check. Returns plugin version, whether a token is set, the configured embedding model, and whether RAG utilities loaded. Call this first when wiring up the API to confirm everything is reachable.

curl https://yoursite.com/wp-json/mxchat/v1/health
{
  "ok": true,
  "plugin_version": "3.2.5",
  "token_set": true,
  "embedding_model": "text-embedding-3-small",
  "utils_loaded": true,
  "namespace": "mxchat/v1"
}

GET /transcripts

Read chat transcripts. Supports filtering, pagination, and sort order. The response is a JSON object with items (an array of message rows) and pagination metadata.

Example — yesterday’s user messages where the bot got no RAG context:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://yoursite.com/wp-json/mxchat/v1/transcripts?role=user&has_rag_context=no&since=2026-05-12T00:00:00Z&limit=200&order=asc"

DELETE /transcripts

Delete chat data for one or more session_ids. There is no “delete all” shorthand — you must list session IDs explicitly. Maximum 1000 IDs per call. By default the delete cascades to translation and URL-click tracking rows for the same sessions.

curl -X DELETE -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"session_ids":["mxchat_chat_abc123","mxchat_chat_def456"],"cascade":true}' \
  "https://yoursite.com/wp-json/mxchat/v1/transcripts"

{
  "session_ids_requested": 2,
  "transcripts_deleted": 14,
  "translations_deleted": 0,
  "url_clicks_deleted": 1,
  "cascade": true
}

POST /knowledge

Push content into the knowledge base. The endpoint generates embeddings on the server side, so it can take 10–60 seconds depending on the size of the content and the embedding provider. Use source_url as the dedupe key — submitting the same URL replaces the existing entry rather than creating a duplicate.

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  --max-time 180 \
  -d '{
    "content": "Q: How do I enable streaming?\nA: MxChat → Settings → Streaming, pick a streaming-capable model.",
    "source_url": "https://yoursite.com/faq/#faq-enable-streaming",
    "content_type": "faq"
  }' \
  "https://yoursite.com/wp-json/mxchat/v1/knowledge"

If your site is behind Cloudflare, embedding requests can exceed the 100-second proxy timeout. To bypass Cloudflare for this call, resolve the host to your origin IP directly:

curl --resolve yoursite.com:443:<origin-ip> ...

Privacy and Security Notes

• Zero by default. Until you generate a token, every authenticated route returns 401. The endpoints add no exposed surface area on a fresh install.
• Constant-time comparison. The bearer-token check uses hash_equals() so it does not leak information through timing.
• Cascade deletes are real deletes. The DELETE endpoint removes rows from mxchat_transcripts and (when cascade=true) mxchat_transcript_translations and mxchat_url_clicks. There is no soft delete or undo.
• Transcripts contain user-submitted content. Treat the token like a secret. Don’t ship it in client-side code or commit it to a public repo.

Error Responses

• 401 mxchat_rest_disabled — no token has been generated on the site. Visit MxChat → API Access and click Generate Token.
• 401 mxchat_rest_unauthorized — wrong token or missing Authorization header.
• 400 rest_invalid_param — one of the request parameters failed validation. The response body names the parameter.
• 500 — the embedding provider rejected the request (knowledge endpoint) or a database write failed. Check the WordPress error log.