Skip to content

LCORE-2572: Updated OpenAPI specification (1st part) #1926

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tisnik merged 5 commits into from
Jun 14, 2026
Merged

LCORE-2572: Updated OpenAPI specification (1st part) #1926

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
eb2af6d
Updated description for /info endpoint
tisnik Jun 14, 2026
8263b63
Updated description for /models endpoint
tisnik Jun 14, 2026
ffe1482
Updated description for / endpoint
tisnik Jun 14, 2026
7b6b85a
Updated description for /tools endpoint
tisnik Jun 14, 2026
58042c0
Regenerated OpenAPI documenentation
tisnik Jun 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
"root"
],
"summary": "Root Endpoint Handler",
"description": "Handle GET requests to the root (\"/\") endpoint and returns the static HTML index page.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Returns:\n- HTMLResponse: The HTML content of the index page, including a heading,\n embedded image with the service icon, and links to the API documentation\n via Swagger UI and ReDoc.",
"description": "Handle GET requests to the root (\"/\") endpoint and returns the static HTML index page.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Raises:\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n\n### Returns:\n- HTMLResponse: The HTML content of the index page, including a heading,\n embedded image with the service icon, and links to the API documentation\n via Swagger UI and ReDoc.",
"operationId": "root_endpoint_handler__get",
"responses": {
"200": {
Expand Down Expand Up @@ -172,7 +172,7 @@
"info"
],
"summary": "Info Endpoint Handler",
"description": "Handle request to the /info endpoint.\n\nProcess GET requests to the /info endpoint, returning the\nservice name, version and Llama-stack version.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Raises:\n- HTTPException: with status 500 and a detail object\n containing `response` and `cause` when unable to connect to\n Llama Stack. It can also return status 401 or 403 for\n unauthorized access.\n\n### Returns:\n- InfoResponse: An object containing the service's name and version.",
"description": "Handle request to the /info endpoint.\n\nProcess GET requests to the /info endpoint, returning the\nservice name, version and Llama-stack version.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Raises:\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n- HTTPException: with status 503 and a detail object containing `response`\n and `cause` when unable to connect to Llama Stack.\n\n### Returns:\n- InfoResponse: An object containing the service's name and version.",
"operationId": "info_endpoint_handler_v1_info_get",
"responses": {
"200": {
Expand Down Expand Up @@ -323,7 +323,7 @@
"models"
],
"summary": "Models Endpoint Handler",
"description": "Handle requests to the /models endpoint.\n\nProcess GET requests to the /models endpoint, returning a list of available\nmodels from the Llama Stack service. It is possible to specify \"model_type\"\nquery parameter that is used as a filter. For example, if model type is set\nto \"llm\", only LLM models will be returned:\n\n curl http://localhost:8080/v1/models?model_type=llm\n\nThe \"model_type\" query parameter is optional. When not specified, all models\nwill be returned.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n- model_type: Optional filter to return only models matching this type.\n\n### Raises:\n- HTTPException: If unable to connect to the Llama Stack server or if\n model retrieval fails for any reason.\n\n### Returns:\n- ModelsResponse: An object containing the list of available models.",
"description": "Handle requests to the /models endpoint.\n\nProcess GET requests to the /models endpoint, returning a list of available\nmodels from the Llama Stack service. It is possible to specify \"model_type\"\nquery parameter that is used as a filter. For example, if model type is set\nto \"llm\", only LLM models will be returned:\n\n curl http://localhost:8080/v1/models?model_type=llm\n\nThe \"model_type\" query parameter is optional. When not specified, all models\nwill be returned.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n- model_type: Optional filter to return only models matching this type.\n\n### Raises:\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n- HTTPException: with status 422 if model_type parameter is\n improper.\n- HTTPException: with status 500 and a detail object containing `response`\n and `cause` when service configuration is wrong or incomplete.\n- HTTPException: with status 503 and a detail object containing `response`\n and `cause` when unable to connect to Llama Stack.\n\n### Returns:\n- ModelsResponse: An object containing the list of available models.",
"operationId": "models_endpoint_handler_v1_models_get",
"parameters": [
{
Expand Down Expand Up @@ -536,7 +536,7 @@
"tools"
],
"summary": "Tools Endpoint Handler",
"description": "Handle requests to the /tools endpoint.\n\nProcess GET requests to the /tools endpoint, returning a consolidated list of\navailable tools from all configured MCP servers.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n- mcp_headers: Headers that should be passed to MCP servers.\n### Raises:\n- HTTPException: If unable to connect to the Llama Stack server or if tool\n retrieval fails for any reason.\n\n### Returns:\n- ToolsResponse: An object containing the consolidated list of available\n tools with metadata including tool name, description, parameters, and\n server source.",
"description": "Handle requests to the /tools endpoint.\n\nProcess GET requests to the /tools endpoint, returning a consolidated list of\navailable tools from all configured MCP servers.\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n- mcp_headers: Headers that should be passed to MCP servers.\n\n### Raises:\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n- HTTPException: with status 422 if mcp_headers parameter is\n improper.\n- HTTPException: with status 500 and a detail object containing `response`\n and `cause` when service configuration is wrong or incomplete.\n- HTTPException: with status 503 and a detail object containing `response`\n and `cause` when unable to connect to Llama Stack.\n\n### Returns:\n- ToolsResponse: An object containing the consolidated list of available\n tools with metadata including tool name, description, parameters, and\n server source.",
"operationId": "tools_endpoint_handler_v1_tools_get",
"responses": {
"200": {
Expand Down
34 changes: 25 additions & 9 deletions docs/openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@ Lightspeed Core Service (LCS) service API specification.

<!-- vim-markdown-toc GFM -->

* [🌍 Base URL](#-base-url)
* [🛠️ APIs](#-apis)
* [List of REST API endpoints](#list-of-rest-api-endpoints)
* [GET `/`](#get-)
Expand Down Expand Up @@ -474,6 +473,10 @@ Handle GET requests to the root ("/") endpoint and returns the static HTML index
- request: The incoming HTTP request (used by middleware).
- auth: Authentication tuple from the auth dependency (used by middleware).

### Raises:
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.
Comment on lines +476 to +478

@coderabbitai coderabbitai Bot Jun 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add the missing blank lines before both Raises headings.

markdownlint still flags these headings because they follow the preceding list immediately. Insert one blank line before each ### Raises: block to keep the generated docs lint-clean.

🛠️ Suggested fix 
 - auth: Authentication tuple from the auth dependency (used by middleware).
 
 ### Raises:
@@
 - mcp_headers: Headers that should be passed to MCP servers.
 
 ### Raises:

Also applies to: 767-775

🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 476-476: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/openapi.md` around lines 476 - 478, The `### Raises:` headings in the
markdown file are not preceded by blank lines, causing markdownlint to flag
them. Insert one blank line before each `### Raises:` heading to comply with
markdown formatting standards. This applies at two locations in docs/openapi.md:
at the anchor location starting around line 476 where the first `### Raises:`
section appears, and at the sibling location around line 767 where another `###
Raises:` section appears. Add a blank line immediately before each of these
headings to separate them from the preceding list content.

Source: Linters/SAST tools


### Returns:
- HTMLResponse: The HTML content of the index page, including a heading,
embedded image with the service icon, and links to the API documentation
Expand Down Expand Up @@ -533,10 +536,10 @@ service name, version and Llama-stack version.
- auth: Authentication tuple from the auth dependency (used by middleware).

### Raises:
- HTTPException: with status 500 and a detail object
containing `response` and `cause` when unable to connect to
Llama Stack. It can also return status 401 or 403 for
unauthorized access.
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.
- HTTPException: with status 503 and a detail object containing `response`
and `cause` when unable to connect to Llama Stack.

### Returns:
- InfoResponse: An object containing the service's name and version.
Expand Down Expand Up @@ -668,8 +671,14 @@ will be returned.
- model_type: Optional filter to return only models matching this type.

### Raises:
- HTTPException: If unable to connect to the Llama Stack server or if
model retrieval fails for any reason.
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.
- HTTPException: with status 422 if model_type parameter is
improper.
- HTTPException: with status 500 and a detail object containing `response`
and `cause` when service configuration is wrong or incomplete.
- HTTPException: with status 503 and a detail object containing `response`
and `cause` when unable to connect to Llama Stack.

### Returns:
- ModelsResponse: An object containing the list of available models.
Expand Down Expand Up @@ -754,9 +763,16 @@ available tools from all configured MCP servers.
- request: The incoming HTTP request (used by middleware).
- auth: Authentication tuple from the auth dependency (used by middleware).
- mcp_headers: Headers that should be passed to MCP servers.

### Raises:
- HTTPException: If unable to connect to the Llama Stack server or if tool
retrieval fails for any reason.
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.
- HTTPException: with status 422 if mcp_headers parameter is
improper.
- HTTPException: with status 500 and a detail object containing `response`
and `cause` when service configuration is wrong or incomplete.
- HTTPException: with status 503 and a detail object containing `response`
and `cause` when unable to connect to Llama Stack.

### Returns:
- ToolsResponse: An object containing the consolidated list of available
Expand Down
8 changes: 4 additions & 4 deletions src/app/endpoints/info.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,10 +52,10 @@ async def info_endpoint_handler(
- auth: Authentication tuple from the auth dependency (used by middleware).

### Raises:
- HTTPException: with status 500 and a detail object
containing `response` and `cause` when unable to connect to
Llama Stack. It can also return status 401 or 403 for
unauthorized access.
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.
- HTTPException: with status 503 and a detail object containing `response`
and `cause` when unable to connect to Llama Stack.

### Returns:
- InfoResponse: An object containing the service's name and version.
Expand Down
10 changes: 8 additions & 2 deletions src/app/endpoints/models.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,14 @@ async def models_endpoint_handler(
- model_type: Optional filter to return only models matching this type.

### Raises:
- HTTPException: If unable to connect to the Llama Stack server or if
model retrieval fails for any reason.
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.
- HTTPException: with status 422 if model_type parameter is
improper.
- HTTPException: with status 500 and a detail object containing `response`
and `cause` when service configuration is wrong or incomplete.
- HTTPException: with status 503 and a detail object containing `response`
and `cause` when unable to connect to Llama Stack.

### Returns:
- ModelsResponse: An object containing the list of available models.
Expand Down
4 changes: 4 additions & 0 deletions src/app/endpoints/root.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -801,6 +801,10 @@ async def root_endpoint_handler(
- request: The incoming HTTP request (used by middleware).
- auth: Authentication tuple from the auth dependency (used by middleware).

### Raises:
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.

### Returns:
- HTMLResponse: The HTML content of the index page, including a heading,
embedded image with the service icon, and links to the API documentation
Expand Down
11 changes: 9 additions & 2 deletions src/app/endpoints/tools.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,9 +119,16 @@ async def tools_endpoint_handler( # pylint: disable=too-many-locals,too-many-st
- request: The incoming HTTP request (used by middleware).
- auth: Authentication tuple from the auth dependency (used by middleware).
- mcp_headers: Headers that should be passed to MCP servers.

### Raises:
- HTTPException: If unable to connect to the Llama Stack server or if tool
retrieval fails for any reason.
- HTTPException: with status 401 for unauthorized access.
- HTTPException: with status 403 if permission is denied.
- HTTPException: with status 422 if mcp_headers parameter is
improper.
- HTTPException: with status 500 and a detail object containing `response`
and `cause` when service configuration is wrong or incomplete.
- HTTPException: with status 503 and a detail object containing `response`
and `cause` when unable to connect to Llama Stack.

### Returns:
- ToolsResponse: An object containing the consolidated list of available
Expand Down
Loading