Gregius Data – REST API

Overview

The Gregius Data REST API exposes plugin capabilities through a versioned WordPress REST API surface at gg-data/v1. It surfaces CRUD and operational endpoints across settings, connections, schema, sync, vectors, search, RAG, models, prompts, logs, and interactions.

Prerequisites

• WordPress 6.9+ with Gregius Data plugin installed and activated
• Authenticated session or valid REST nonce for admin endpoints
• Connection and model configuration completed for RAG and search endpoints

---

API Fundamentals

All routes are registered under the base namespace /wp-json/gg-data/v1. Routes are grouped by operational domain across domain-specific controllers. Most endpoints accept and return JSON payloads with structured error responses for failures.

Three permission patterns are used across endpoint groups:

• Admin-gated — most operational controllers require privileged access
• Filter-based — RAG endpoints use runtime-filtered permission policy
• Ownership-aware — interactions endpoints respect record ownership

---

Endpoint Groups

The API is organized into 17 controller groups. Below is a summary organized by purpose.

Configuration

Group	Key Routes	Permission
Settings	GET/POST /settings, GET/POST /settings/{key}, POST /settings/bulk	Admin
Connections	GET/POST /connections, GET/PUT/DELETE /connections/{name}, POST /connections/{name}/test	Admin
Models	GET/POST /models, GET/PUT/DELETE /models/{id}, POST /models/test	Admin
Prompts	GET/POST /prompts, PUT/DELETE /prompts/{id}, POST /prompts/{id}/activate	Admin

Operations

Group	Key Routes	Permission
Schema	GET /schema/status, POST /schema/create, POST /schema/upgrade, POST /schema/verify	Admin
Sync	GET /sync/status, POST /sync/configuration, POST /sync/post-type/{type}, batch and orphan cleanup	Admin
Sync Validation	GET /sync/validation, POST /sync/validation/run	Admin
Search	GET /search/health, POST /search/typo-tolerance, GET /search/status	Admin
Vector Queue	GET /vector-queue, POST /vectors/batch-generate, POST /vectors/batch-delete	Admin
Vocabulary	POST /vocabulary/prepare, GET /vocabulary/status	Admin
Retry Queue	GET /sync/retry-queue, POST /sync/retry-queue/retry/{index}	Admin

Runtime

Group	Key Routes	Permission
RAG	POST /rag/chat, POST /rag/action, GET /rag/actions	Filter-based
RAG Journey	POST /rag/journey/issue, POST /rag/journey/consume, GET /rag/journey/history	Filter-based
Interactions	GET/POST /interactions, GET/PUT/DELETE /interactions/{id}	Ownership-aware

Observability

Group	Key Routes	Permission
Logs	GET /logs, GET /logs/stats, GET /logs/export, DELETE /logs/purge, GET/POST /logs/settings	Admin

---

Permission Model

The REST API enforces three distinct permission patterns:

Admin-gated is the default for configuration and operational endpoints. These require the manage_options capability or equivalent, ensuring only site administrators can modify settings, trigger syncs, or manage schema.

Filter-based applies to RAG and RAG Journey endpoints. The gg_data_rag_endpoint_permission filter allows runtime tightening of access policy. RAG chat and action endpoints use fail-closed semantics (default deny), while journey endpoints use fail-open semantics (default allow).

Ownership-aware applies to the Interactions controller. Logged-in users can access their own records (read, update, delete). Direct creation via POST /interactions is admin-only. Administrators can access all records regardless of ownership. Anonymous access is denied.

Route-scoped throttling is built in for POST /rag/chat and POST /rag/action with fixed-window limits configurable through hooks.

---

Request and Response Conventions

Requests to admin endpoints must include authentication. In the WordPress dashboard context, include a REST nonce via the X-WP-Nonce header. For external clients, use WordPress application passwords or OAuth.

Successful responses return structured JSON payloads.

Error responses return WP_Error structures with explicit HTTP status codes:

• 400 — invalid input or missing required parameters
• 401 — authentication required
• 403 — permission denied
• 404 — resource not found
• 429 — rate limit exceeded (RAG chat/action)

Route arguments are validated and sanitized according to each route’s declaration. Invalid requests are rejected before reaching the controller callback.

---