Gregius Data – Interactions

Overview

Gregius Data automatically captures every search and RAG conversation turn as an interaction record — a complete, inspectable history of AI-driven activity on your WordPress site. Site administrators can access and extend these records for analysis, troubleshooting, and downstream workflow integration.

Prerequisites

• WordPress 6.9+ with Gregius Data plugin installed and activated
• At least one AI model registered and active on the site
• At least one data connection configured and active

---

Understanding Interaction Records

Interaction records capture what happened during a search or RAG conversation turn. Each record is stored as a gg_interaction post with typed meta fields and a canonical JSON payload that preserves full context.

Search interactions

A search interaction records the query, connection used, whether the search returned zero results, and the source context (frontend, rest, wpcli, or mcp). Exactly one record is created per completed search event.

RAG conversation interactions

RAG interactions group turns by conversation UUID. The first turn creates a new conversation record; subsequent turns with the same UUID append to the existing record. Each turn preserves the query, response, model chain, latency, and source documents.

Key fields

Field	Description
Type	search or rag
Source	Where the interaction originated — frontend, rest, wpcli, or mcp
Connection	The data connection used for the request
Conversation ID	UUID identifying the RAG conversation (RAG only)
Zero results	Whether a search returned no results (search only)
JSON payload	Full interaction context including query, model metadata, sources, and latency

---

Accessing Interactions Through the REST API

Interaction records are available through the gg-data/v1/interactions REST endpoint family. All requests require authentication.

List and read interactions

Administrators can list and read all interaction records on the site. Non-admin users are scoped to their own records only.

Route	Method	Description
/interactions	GET	List interactions
/interactions/{id}	GET	Read a single interaction

Create, update, and delete interactions

Creating interaction records directly through the REST API is restricted to administrators. Non-admins create interactions through the RAG and search lifecycle (chat endpoints or search integrations).

Route	Method	Description
/interactions	POST	Create interaction (admin only)
/interactions/{id}	PUT / PATCH	Update interaction
/interactions/{id}	DELETE	Delete interaction (soft-delete by default; use force=true for hard delete)

Multisite behavior

In multisite, administrators see records from their own site by default. Super administrators can supply an explicit site_id parameter to access interaction records on another site within the network. Non-super-admin requests that include site_id are denied.

---

Customizing Interactions Through Hooks

The interaction subsystem exposes hooks — extension points that let integrators enrich metadata, shape log context, and react to newly recorded interactions.

Hook	Type	Purpose
gg_data_interaction_meta_fields	Filter	Register additional meta fields for interaction records
gg_data_interaction_log_context	Filter	Add or modify context data written to the operational log
gg_data_interaction_recorded	Action	React to newly recorded interactions (analytics, notifications, external sync)

---