REST API

The ConvEngine REST APIs provide interaction hooks for conversations, administrative controls for the database-driven semantic engine configuration, and advanced tooling for developers mapping state boundaries.

Conversation APIs

Base: /api/v1/conversation

Conversation endpoints

Method	Path	Purpose
POST	/message	Process one conversation turn and return payload
POST	/feedback	Store thumbs up/down + optional correction metadata
GET	/audit/{conversationId}	Raw audit rows (`ce_audit`) for the conversation
GET	/audit/{conversationId}/trace	Step and stage timeline view derived from audit rows

Turn Execution (/message)

Processes a single turn of conversation, accepting a user message and returning the deterministic intent/state payload alongside an AI generated response.

Request Payload

POST /message request

JSON

{
  "conversationId": "9bf7540a-b129-4685-a120-730e8a0cb94b",
  "message": "show all disconnect requests",
  "reset": false,
  "inputParams": {
    "tenant": "acme"
  }
}

Response (Success)

POST /message success response

JSON

{
  "success": true,
  "conversationId": "9bf7540a-b129-4685-a120-730e8a0cb94b",
  "intent": "SEMANTIC_QUERY",
  "state": "COMPLETED",
  "payload": {
    "type": "TEXT",
    "value": "Found 7 matching disconnect requests."
  },
  "context": "{...}"
}

Response (Error)

POST /message error payload

JSON

{
  "success": false,
  "conversationId": "9bf7540a-b129-4685-a120-730e8a0cb94b",
  "intent": "ERROR",
  "state": "ERROR",
  "payload": {
    "type": "ERROR",
    "value": "{\"errorCode\":\"400_BAD_REQ\",\"message\":\"...\",\"recoverable\":false}"
  }
}

Cache APIs

Base: /api/v1/cache

Cache endpoints

Method	Path	Purpose
POST	/refresh	Evict and reload static caches; also refresh query-failure embeddings
GET	/analyze	Inspect cache health/state (`warmup` query param supported)

DB + Semantic admin APIs

Base: /api/v1/db

Schema and semantic administration

Method	Path	Purpose
GET	/inspect-schema	Inspect live DB schema (`schema`, `prefix`, `matchMode` query params)
POST	/semantic/embeddings/rebuild	Rebuild embeddings from semantic model
POST	/semantic/embeddings/query-failures/rebuild	Rebuild `ce_semantic_query_failures.question_embedding` vectors

Semantic mode

Semantic admin endpoints require semantic runtime to be enabled in application.yml (convengine.mcp.db.semantic.enabled=true) as well as vector support on your DB.

Embeddings Pipeline (/semantic/embeddings/*)

Controls the backend refresh state for Postgres pgvector knowledge graphs.

Rebuild Models

Rebuild Base Model Embeddings

JSON

{
  "forceRebuildAll": false,
  "onlyMissing": true
}

Rebuild Failures

Rebuild Query Failures Embeddings

JSON

// POST /api/v1/db/semantic/embeddings/query-failures/rebuild
{
  "onlyMissing": true
}

// Response
{
  "indexedCount": 42,
  "skippedCount": 100,
  "failedCount": 0
}

Experimental APIs

Base: /api/v1/conversation/experimental

Feature-flagged endpoints

Method	Path	Purpose
POST	/generate-sql	Generate CE seed SQL from scenario input
POST	/generate-sql/zip	Generate ZIP package containing SQL/assets

Enable with:

application.yml

convengine:
  experimental:
    enabled: true

Postman

Postman setup

Field	Value
Method	POST
URL	http://localhost:8080/api/v1/conversation/experimental/generate-sql/zip
Headers	Content-Type: application/json
Body Mode	raw (JSON)
Output	Save Response -> Save to a file (creates ZIP)

Postman body (JSON)

JSON

{
  "scenario": "Build semantic logic for disconnect workflow",
  "domain": "utilities",
  "constraints": "Focus on semantic filtering by date",
  "includeMcp": true
}

curl

curl request

BASH

curl -X POST "http://localhost:8080/api/v1/conversation/experimental/generate-sql/zip" \\
  -H "Content-Type: application/json" \\
  -d '{
    "scenario": "Build semantic logic for disconnect workflow",
    "domain": "utilities",
    "constraints": "Focus on semantic filtering by date",
    "includeMcp": true
  }' --output semantic_payload.zip

/experimental/generate-sql success response

JSON

Generation scope

generate-sql is designed for non-transactional configuration tables (ce_config, ce_intent, ce_rule, ce_prompt_template, ce_response, ce_output_schema, ce_semantic_*). It does not generate runtime conversation/audit data.

Experimental output

Generated SQL should always be reviewed before execution.