REST API

Base

/api/v1/conversation

Endpoints

Conversation endpoints

Method	Path	Purpose
POST	/message	Process one turn and return payload
GET	/audit/{conversationId}	Raw audit rows for conversation
GET	/audit/{conversationId}/trace	Normalized step+stage timeline
GET	/cache/refresh	Evicts static configs memory tree (`ce_static_configs`) and triggers a Spring DB pre-loader to dynamically swap framework configuration

POST /message

Request body

JSON

{
  "conversationId": "uuid-optional",
  "message": "Track request REQ-778102",
  "reset": false,
  "inputParams": {
    "tenant": "acme"
  }
}

Success response

JSON

{
  "success": true,
  "conversationId": "9bf7540a-b129-4685-a120-730e8a0cb94b",
  "intent": "REQUEST_TRACKER",
  "state": "IDLE",
  "payload": {
    "type": "TEXT",
    "value": "Request REQ-778102 is IN_REVIEW."
  },
  "context": "{...}"
}

Experimental endpoint (feature-flagged)

Base: /api/v1/conversation/experimental

• POST /generate-sql

Enable with:

application.yml (feature flag)

YAML

convengine:
  experimental:
    enabled: true

Postman

Postman setup

Field	Value
Method	POST
URL	http://localhost:8080/api/v1/conversation/experimental/generate-sql
Headers	Content-Type: application/json
Body Mode	raw (JSON)

Postman body (JSON)

JSON

{
  "scenario": "Build disconnect electricity workflow",
  "domain": "utilities",
  "constraints": "Collect account number before action",
  "includeMcp": true
}

curl

curl request

BASH

curl -X POST "http://localhost:8080/api/v1/conversation/experimental/generate-sql" \
-H "Content-Type: application/json" \
-d '{
  "scenario": "Build disconnect electricity workflow",
  "domain": "utilities",
  "constraints": "Collect account number before action",
  "includeMcp": true
}'

/experimental/generate-sql success response

JSON

{
  "success": true,
  "sql": "INSERT INTO ce_config ...;\nINSERT INTO ce_intent ...;",
  "warnings": [],
  "note": "Experimental output: review before applying in production."
}

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_container_config, optional MCP tables). It does not generate runtime conversation/audit data.

Experimental output

Generated SQL should be reviewed before use. The endpoint applies safety checks but does not replace human review.