Engine Application

Controllers

All controllers are reactive WebFlux @RestController`s in `engine/controller/, annotated with a Springdoc @Tag so they group in the generated OpenAPI document. Authorization is applied per method with @PreAuthorize — the security filter chain itself permits every exchange, see Security Implementation.

The request and response semantics of the externally consumed endpoints are documented for integrators in the public integration documentation; this page is the map from endpoint groups to the classes that serve them, plus the endpoints that are internal only.

Consumer-Facing Controllers

Controller Paths Notes

AgentController

/api/v2/project, /api/v2/project/{idOrRef}, /api/agent, /api/agent/{key}, /api/agents/{keys}, /api/agent/{ref}/_star, /api/agent/{ref}/_unstar

Project and agent discovery. Delegates the visibility and permission rules to AgentService.

SessionController

/api/session/**

Session and turn history, and the LLM log of a session.

UserController

/api/user, /api/user/fcmToken

Current user, user erasure and push token registration.

MemoryController

/api/memory/**

Memory snapshot, restore and deletion.

DevelopmentProfileController

/api/development-profile

The caller’s own coaching profile for a project — see Codebook and Development Profile. The user id comes from the authenticated principal, never from the request. An absent profile is a normal state and returns 200 with an empty body.

EvaluationController

/api/evaluation/**, /api/v2/evaluation/status

Evaluation status, insights and aggregations. The status endpoints are explicitly permitAll() so a client can read the outcome of an anonymous session.

NavigationController

/api/navigation/status/{ref}, POST /api/navigation/{ref}/refresh

Whether a navigation hint is active for the user. refresh?projectRef=… sets an entry, for every user with evaluation results in the project, to where those results put it — for an entry added or a condition changed after users' evaluations — and answers {"changedUsers": n}. It needs the editor or owner role in the project, decided as for the project payload (AgentService.hasProjectRole: the user’s ACL records on the project or its account, plus the identity provider’s roles when the project uses external roles), and notifies no one.

FeedbackController

/api/feedback/specification, /api/feedback/submission/{definitionId}, /api/feedback/postpone/{definitionId}, /api/feedback/skip/{definitionId}

Feedback specifications, the answers to them, and skipping or postponing a form without answers. The caller is the authenticated user or, failing that, the user of the deviceRef device — see Feedback Scheduling.

VisualController

/api/visual/**

Agent, project and live-avatar images, composed and cached in resource storage and re-encoded to the requested format.

RecordingController

/api/recording/session/{sessionId}.*

Streams session recordings from resource storage, remuxing to MP4 on the fly through ffmpeg.

ReportController

/api/report, /api/report/bug, /api/report/issue

Client technical reports, bug reports and conversation issues.

PipelineController

/api/pipeline/{key}

The HTTP conversation channel: a streamed text/plain request body in, a newline-delimited stream of serialized output elements out, session continuity through the sessionId cookie. Can be disabled with promethist.pipeline.controller=false.

MainController

/api/version, /api/time, /api/client

Instance metadata and the platform-dependent redirect to the client application.

OAuthController

/api/oauth/**

Authorization code flow with PKCE for third-party service connections.

McpConnectionController

/api/mcpconnection/**

MCP connector management. Loading tools requires the admin role.

CallController

/api/call/initiate

Outbound telephony. Only present when a CallService bean exists.

SlackController

/api/slack/{key}

Slack Events API webhook: runs a conversation turn per message and posts the streamed response back through the Slack Web API. Also runs a scheduled cleanup of stale state.

Internal Controllers

These are not part of the public integration surface.

Controller Paths Purpose

HealthCheckController

/api/health/textSpeechSynthesizer/, /api/health/speechRecognizer/, /api/health/realtimeModel/, /api/health/llm/

Probes the pluggable providers — all of them or one by name — and reports per-component results. Requires the admin role. Used for operational diagnostics of provider outages, and distinct from the Actuator health endpoints used by Kubernetes.

MessageController

/api/message/user/{userId}, /api/message/agent/{agentRef}, /api/message/project/{projectRef}

Sends a push message to a user, to all users of an agent or to all users of a project. Requires the admin role.

LLMDebuggerSessionController

/api/debug/sessions/{sessionId}, /api/debug/replay, /api/debug/replay/judge

Session debugger: the turn and component timeline of a session, and replaying a recorded invocation against a model. Requires an authenticated user, additionally authorized against the session’s project ACL.

LLMDebuggerToolCallController

/api/debug/projects/{projectRef}, /api/debug/tool-calls/options, /api/debug/tool-calls/stats, /api/debug/tool-calls/turns, /api/debug/tool-calls/classify, /api/debug/tool-call-criteria

Opening a project, its tool call statistics, the turns behind them, on-demand relevance classification and the classification criteria with their draft and publish workflow. Requires an authenticated project or account owner — see Tool Call Analysis.

LLMDebuggerAuthController

/api/debug/auth/config

Bootstrap configuration (issuer, client ID, scopes) for the debugger front end.

TemplateController

/, /index.html

Renders the SPA host page, injecting version, commit and public URL.

Cross-Cutting

Class Behaviour

GlobalExceptionHandler

@ControllerAdvice mapping NotFoundException to a JSON 404 and ResponseStatusException to the rendered HTML error view used by the SPA.

LLMDebuggerExceptionHandler

A @RestControllerAdvice scoped to the debugger controllers so their errors stay JSON instead of rendering the HTML view.

SwaggerConfiguration

Adds the bearer security scheme and the @PreAuthorize-derived authorization notes to the OpenAPI document served at /api/schema.json.

CORS is enabled for /api/ for all origins, methods and headers; static resources and the /client/ SPA fallback are served by the router function declared in EngineConfiguration.