Embedding diagnostics

POST

/wp-json/wp2tutor/embedding/v1/diagnostics

const url = 'https://example.com/wp-json/wp2tutor/embedding/v1/diagnostics';
const options = {
  method: 'POST',
  headers: {'X-WP-Nonce': '<X-WP-Nonce>', 'Content-Type': 'application/json'},
  body: '{"query":"what is an embedding"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/wp-json/wp2tutor/embedding/v1/diagnostics \
  --header 'Content-Type: application/json' \
  --header 'X-WP-Nonce: <X-WP-Nonce>' \
  --data '{ "query": "what is an embedding" }'

Admin hybrid search against the index (not the production chat path). PHP diagnostics: JSON { query }, sanitize_text_field, DiagnosticsRunner::run. Always HTTP 200: { logs, matches }. Failure (empty query, missing key, no vec table, provider returned no vector) is not 4xx — logs hold the DiagnosticsAbortException text and matches is []. Hits: sqlite-vec kNN + FTS5, RRF, score 0–100 (HybridDiagnosticsScore, weights 0.7 vec / 0.3 FTS), typically up to 8 (FINAL_TOP_K). text is a content preview up to 200 chars with HTML stripped. Requires manage_options.

Authorizations

cookie
applicationPassword

Request Body

application/json

object

query

Query text. PHP sanitize_text_field; missing key → ''. Empty string → 200, logs with Enter query text. (i18n), matches [].

string

Example

{
  "query": "what is an embedding"
}

Responses

200

Logs (steps or a single abort message) and matches. Empty query → logs such as Enter query text., matches [].

application/json

object

logs

Run steps. Success: strings «Найдено совпадение {score}% в чанке №{id}: {text}» (PHP msgid is Russian). Abort: one item — DiagnosticsAbortException message (no query/key/vec table/query embedding).

Array<string>

matches

Matched chunks (typically ≤ 8). Abort → [].

Array<object>

object

id_chunk

Chunk id in the index/SQLite.

integer

distance

Sqlite-vec cosine distance (typically 0…1). FTS-only hits may get 1.0 from PHP.

number

score

Hybrid percent 0–100 (HybridDiagnosticsScore: 0.7×(1−distance) + 0.3×normalized bm25), rounded to 1 decimal. Not raw cosine similarity.

number

fts_rank

Raw FTS5 bm25, only if the chunk appeared in the FTS leg. Otherwise the key is omitted.

number

text

Content preview without HTML, up to 200 characters (whitespace collapsed). Missing chunk row → ''.

string

Example

{
  "logs": [
    "Найдено совпадение 91.2% в чанке №42: Embedding is a vector representation of text."
  ],
  "matches": [
    {
      "id_chunk": 42,
      "distance": 0.12,
      "score": 91.2,
      "fts_rank": -4.2,
      "text": "Embedding is a vector representation of text."
    }
  ]
}

401

Not authenticated. DualRest: rest_forbidden (status 401) when there is no cookie session. Cookie + X-WP-Nonce or Application Password.

application/json

object

code

WP_Error code. For POST /chat 401 — rest_forbidden. DualRest cookie — rest_forbidden / rest_not_logged_in / rest_cookie_invalid_nonce.

string

message

WP_Error message (for the chat secret — Missing or invalid secret.).

string

data

Usually { status: HTTP code }, as PHP stores in WP_Error data.

object

Example

{
  "code": "rest_forbidden",
  "message": "Missing or invalid secret.",
  "data": {
    "status": 401
  }
}

403

Missing manage_options or invalid REST nonce. WordPress REST: rest_forbidden / rest_cookie_invalid_nonce.

application/json

object

code

WP_Error code. For POST /chat 401 — rest_forbidden. DualRest cookie — rest_forbidden / rest_not_logged_in / rest_cookie_invalid_nonce.

string

message

WP_Error message (for the chat secret — Missing or invalid secret.).

string

data

Usually { status: HTTP code }, as PHP stores in WP_Error data.

object

Example

{
  "code": "rest_forbidden",
  "message": "Missing or invalid secret.",
  "data": {
    "status": 401
  }
}