Java REST API Reference

The Java business backend handles operational data — users, sessions, plugin registry, connectors, permissions. The chat itself runs in the Python core; Java holds the data the chat needs to be associated with.

The live spec is auto-generated by springdoc-openapi:

• JSON: http://localhost:8080/v3/api-docs
• YAML: http://localhost:8080/v3/api-docs.yaml
• Swagger UI: http://localhost:8080/swagger-ui.html

The committed copy lives in docs/api/java-v1.yaml and is exported on every release.

Resource map

Group	Base path	Description
Auth	/api/v1/auth	Login / refresh / dev token
Users	/api/v1/users	User aggregate CRUD
Sessions	/api/v1/sessions	Conversation sessions
Plugins	/api/v1/plugins	Plugin registry + activation
Connectors	/api/v1/connectors	OAuth-backed IM connectors
Permissions	/api/v1/users/{id}/permissions	Per-user ACL

Auth

The dev profile returns a stable dummy token; the prod profile validates real JWTs via Spring Security OAuth2 Resource Server. See ADR-013 for the boundary between Python and Java.

POST /api/v1/auth/login
Content-Type: application/json

{ "username": "alice", "password": "secret" }

Response:

{
  "accessToken": "...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

Attach Authorization: Bearer ACCESS_TOKEN to every subsequent request.

Convention notes

• camelCase field naming (Java Jackson default). Frontend clients normalise to whatever they need.
• UUIDs for all entity ids.
• ISO 8601 strings for timestamps.
• Status enums are strict (e.g. Plugin.status is one of DRAFT | PUBLISHED | DISABLED).

Pagination

List endpoints support ?page=0&size=20. Responses use Spring Data's Page<T> envelope:

{
  "content": [...],
  "page": 0,
  "size": 20,
  "totalElements": 137
}

Error envelope

Errors normalise to:

{
  "timestamp": "2026-06-07T10:00:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "email already in use",
  "path": "/api/v1/users"
}

The full spec, including request/response examples and validation rules, is the Swagger UI listed at the top of this page.