REST API Reference
All interactions with uxopian-ai go through its REST API. This page provides a complete overview of the endpoints and how to access the interactive documentation.
For practical usage examples with cURL and JavaScript, see Using the REST API.
Interactive Documentation (Swagger UI)
The service exposes a full OpenAPI 3.1.0 specification. We highly recommend using the built-in Swagger UI for exploring the API, inspecting schemas, and testing requests in real-time.
Accessing Swagger UI
Depending on your environment, the Swagger UI is available at:
- Local / Docker:
http://localhost:8080/swagger-ui.html(Default port is 8080)
Note: If a custom CONTEXT_PATH is configured in application.yml, append it to the base URL (e.g., http://localhost:8080/ai/swagger-ui.html).
The Swagger UI is publicly accessible (no authentication required). Endpoints are organized by tags prefixed with Admin - for admin operations, making it easy to explore the full API surface.
Authentication
The API expects authentication via headers injected by your Gateway or BFF. See Security Model for the full explanation.
| Header | Required | Description |
|---|---|---|
X-User-TenantId | Yes | Tenant isolation key. |
X-User-Id | Yes | Unique User ID. |
X-User-Roles | No | Comma-separated roles (e.g., admin). |
X-User-Token | No | Original user token for downstream context. |
API Endpoints
Conversations
Manage the lifecycle of chat sessions.
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/conversations | Create a new conversation. |
GET | /api/v1/conversations | List user conversations (paginated). |
GET | /api/v1/conversations/{id} | Retrieve full details of a conversation. |
DELETE | /api/v1/conversations/{id} | Delete a conversation. |
Requests (Chat)
Send messages and interact with the LLM.
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/requests | Send a message and get a synchronous response. |
POST | /api/v1/requests/stream | Send a message and receive the response as an SSE stream. |
POST | /api/v1/requests/retry | Regenerate the last answer. |
Query Parameters:
conversation(Required) — The conversation ID.provider(Optional) — Override the LLM provider for this request.model(Optional) — Override the LLM model for this request.
Administration — Prompts
Endpoints restricted to users with the admin role.
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/admin/prompts | Create a new prompt. |
PUT | /api/v1/admin/prompts | Update an existing prompt. |
GET | /api/v1/admin/prompts/{id} | Get a specific prompt by ID. |
DELETE | /api/v1/admin/prompts/{id} | Delete a prompt. |
Administration — Goals
| Method | Endpoint | Description |
|---|---|---|
POST | /api/v1/admin/goals | Create a new goal. |
PUT | /api/v1/admin/goals | Update an existing goal. |
GET | /api/v1/admin/goals | Get all goals. |
DELETE | /api/v1/admin/goals/{id} | Delete a goal. |
Administration — LLM Providers
Manage LLM provider configurations at runtime. See LLM Provider Management for the full UI guide.
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/admin/llm/providers | List all registered provider types (bean names). |
GET | /api/v1/admin/llm/provider-conf | List all provider configurations for the tenant. |
GET | /api/v1/admin/llm/provider-conf/{id} | Get a specific provider configuration by ID. |
POST | /api/v1/admin/llm/provider-conf | Create a new provider configuration. |
PUT | /api/v1/admin/llm/provider-conf/{id} | Update an existing provider configuration. |
DELETE | /api/v1/admin/llm/provider-conf/{id} | Delete a provider configuration. |
Administration — Statistics
All statistics endpoints accept an optional interval query parameter to control time-series granularity. Supported values: HOUR, DAY, WEEK, MONTH, YEAR. Default: DAY.
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/admin/stats/global | Aggregate counters (total requests, tokens, time saved). |
GET | /api/v1/admin/stats/timeseries?interval=DAY | Time-series activity data (requests, tokens over time). |
GET | /api/v1/admin/stats/llm-distribution | Model usage distribution breakdown. |
GET | /api/v1/admin/stats/top-prompts-time-saved | Top prompts ranked by estimated time saved. |
GET | /api/v1/admin/stats/feature-adoption | Advanced feature adoption rates (multi-modal, function calling). |