Skip to content

LCORE-432: update doc for endpoints #560

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
merged 1 commit into from
Sep 18, 2025
Merged

LCORE-432: update doc for endpoints #560

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
113 changes: 108 additions & 5 deletions docs/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,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 and version.\n\nReturns:\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\nReturns:\n InfoResponse: An object containing the service's name and version.",
"operationId": "info_endpoint_handler_v1_info_get",
"responses": {
"200": {
Expand Down Expand Up @@ -117,7 +117,7 @@
}
]
},
"503": {
"500": {
"description": "Connection to Llama Stack is broken"
}
}
Expand Down Expand Up @@ -174,8 +174,8 @@
}
}
},
"503": {
"description": "Service Unavailable",
"500": {
"description": "Internal Server Error",
"detail": {
"response": "Unable to connect to Llama Stack",
"cause": "Connection error."
Expand Down Expand Up @@ -214,13 +214,56 @@
},
"responses": {
"200": {
"description": "Successful Response",
"description": "Streaming response with Server-Sent Events",
"content": {
"application/json": {
"schema": {}
},
"text/event-stream": {
"schema": {
"type": "string",
"example": "data: {\"event\": \"start\", \"data\": {\"conversation_id\": \"123e4567-e89b-12d3-a456-426614174000\"}}\n\ndata: {\"event\": \"token\", \"data\": {\"id\": 0, \"role\": \"inference\", \"token\": \"Hello\"}}\n\ndata: {\"event\": \"end\", \"data\": {\"referenced_documents\": [], \"truncated\": null, \"input_tokens\": 0, \"output_tokens\": 0}, \"available_quotas\": {}}\n\n"
}
}
}
},
"400": {
"description": "Missing or invalid credentials provided by client",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
},
"401": {
"description": "Unauthorized: Invalid or missing Bearer token for k8s auth",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
},
"403": {
"description": "User is not authorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ForbiddenResponse"
}
}
}
},
"500": {
"description": "Internal Server Error",
"detail": {
"response": "Unable to connect to Llama Stack",
"cause": "Connection error."
}
},
Comment on lines +260 to +266
Copy link
Contributor

@coderabbitai coderabbitai bot Sep 18, 2025

Choose a reason for hiding this comment

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

⚠️ Potential issue

Invalid OpenAPI: “detail” at top level in 500 response; move under content.

Same issue as /v1/query. Use ErrorResponse.

-                    "500": {
-                        "description": "Internal Server Error",
-                        "detail": {
-                            "response": "Unable to connect to Llama Stack",
-                            "cause": "Connection error."
-                        }
-                    },
+                    "500": {
+                        "description": "Internal Server Error",
+                        "content": {
+                            "application/json": {
+                                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+                            }
+                        }
+                    },
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
"500": {
"description": "Internal Server Error",
"detail": {
"response": "Unable to connect to Llama Stack",
"cause": "Connection error."
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": { "$ref": "#/components/schemas/ErrorResponse" }
}
}
},
🤖 Prompt for AI Agents 
In docs/openapi.json around lines 260 to 266, the 500 response currently
contains a top-level "detail" object which is invalid OpenAPI; move that error
payload under the response's "content" (e.g., application/json) and reference or
use the existing ErrorResponse schema instead of an inline "detail" object so
the response body is properly described (replace the inline detail with a
content block that references ErrorResponse).

"422": {
"description": "Validation Error",
"content": {
Expand Down Expand Up @@ -473,6 +516,26 @@
}
]
},
"400": {
"description": "Missing or invalid credentials provided by client",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
},
"401": {
"description": "Unauthorized: Invalid or missing Bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
},
"503": {
"description": "Service Unavailable",
"detail": {
Expand Down Expand Up @@ -530,6 +593,26 @@
}
]
},
"400": {
"description": "Missing or invalid credentials provided by client",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
},
"401": {
"description": "Unauthorized: Invalid or missing Bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
},
"404": {
"detail": {
"response": "Conversation not found",
Expand Down Expand Up @@ -588,6 +671,26 @@
"success": true,
"message": "Conversation deleted successfully"
},
"400": {
"description": "Missing or invalid credentials provided by client",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
},
"401": {
"description": "Unauthorized: Invalid or missing Bearer token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
},
"404": {
"detail": {
"response": "Conversation not found",
Expand Down
27 changes: 14 additions & 13 deletions docs/openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Handle request to the / endpoint.
Handle request to the /info endpoint.

Process GET requests to the /info endpoint, returning the
service name and version.
service name, version and Llama-stack version.

Returns:
InfoResponse: An object containing the service's name and version.
Expand Down Expand Up @@ -74,7 +74,7 @@ Returns:
| Status Code | Description | Component |
|-------------|-------------|-----------|
| 200 | Successful Response | [ModelsResponse](#modelsresponse) |
| 503 | Connection to Llama Stack is broken | |
| 500 | Connection to Llama Stack is broken | |
## POST `/v1/query`

> **Query Endpoint Handler**
Expand Down Expand Up @@ -108,7 +108,7 @@ Returns:
| 200 | Successful Response | [QueryResponse](#queryresponse) |
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
| 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) |
| 503 | Service Unavailable | |
| 500 | Internal Server Error | |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
## POST `/v1/streaming_query`

Expand Down Expand Up @@ -143,7 +143,11 @@ Raises:

| Status Code | Description | Component |
|-------------|-------------|-----------|
| 200 | Successful Response | ... |
| 200 | Streaming response with Server-Sent Events | ...string |
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
| 401 | Unauthorized: Invalid or missing Bearer token for k8s auth | [UnauthorizedResponse](#unauthorizedresponse) |
| 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) |
| 500 | Internal Server Error | |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
## GET `/v1/config`

Expand Down Expand Up @@ -269,6 +273,8 @@ Handle request to retrieve all conversations for the authenticated user.
| Status Code | Description | Component |
|-------------|-------------|-----------|
| 200 | Successful Response | [ConversationsListResponse](#conversationslistresponse) |
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
| 503 | Service Unavailable | |
## GET `/v1/conversations/{conversation_id}`

Expand Down Expand Up @@ -304,6 +310,8 @@ Returns:
| Status Code | Description | Component |
|-------------|-------------|-----------|
| 200 | Successful Response | [ConversationResponse](#conversationresponse) |
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
| 404 | Not Found | |
| 503 | Service Unavailable | |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
Expand Down Expand Up @@ -335,6 +343,8 @@ Returns:
| Status Code | Description | Component |
|-------------|-------------|-----------|
| 200 | Successful Response | [ConversationDeleteResponse](#conversationdeleteresponse) |
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
| 404 | Not Found | |
| 503 | Service Unavailable | |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
Expand Down Expand Up @@ -769,15 +779,6 @@ Example:
user_question="what are you doing?",
user_feedback="This response is not helpful",
llm_response="I don't know",
sentiment=1
)

# Feedback with categories
feedback_request = FeedbackRequest(
conversation_id="12345678-abcd-0000-0123-456789abcdef",
user_question="How do I deploy a web app?",
llm_response="You need to use Docker and Kubernetes for everything.",
user_feedback="This response is too general and doesn't provide specific steps.",
sentiment=-1,
categories=[FeedbackCategory.INCORRECT, FeedbackCategory.INCOMPLETE]
)
Expand Down
18 changes: 14 additions & 4 deletions docs/output.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Handle request to the / endpoint.
Handle request to the /info endpoint.

Process GET requests to the /info endpoint, returning the
service name and version.
service name, version and Llama-stack version.

Returns:
InfoResponse: An object containing the service's name and version.
Expand Down Expand Up @@ -74,7 +74,7 @@ Returns:
| Status Code | Description | Component |
|-------------|-------------|-----------|
| 200 | Successful Response | [ModelsResponse](#modelsresponse) |
| 503 | Connection to Llama Stack is broken | |
| 500 | Connection to Llama Stack is broken | |
## POST `/v1/query`

> **Query Endpoint Handler**
Expand Down Expand Up @@ -108,7 +108,7 @@ Returns:
| 200 | Successful Response | [QueryResponse](#queryresponse) |
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
| 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) |
| 503 | Service Unavailable | |
| 500 | Internal Server Error | |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
## POST `/v1/streaming_query`

Expand Down Expand Up @@ -143,7 +143,11 @@ Raises:

| Status Code | Description | Component |
|-------------|-------------|-----------|
| 200 | Successful Response | ... |
| 200 | Streaming response with Server-Sent Events | ...string |
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
| 401 | Unauthorized: Invalid or missing Bearer token for k8s auth | [UnauthorizedResponse](#unauthorizedresponse) |
| 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) |
| 500 | Internal Server Error | |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
## GET `/v1/config`

Expand Down Expand Up @@ -269,6 +273,8 @@ Handle request to retrieve all conversations for the authenticated user.
| Status Code | Description | Component |
|-------------|-------------|-----------|
| 200 | Successful Response | [ConversationsListResponse](#conversationslistresponse) |
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
| 503 | Service Unavailable | |
## GET `/v1/conversations/{conversation_id}`

Expand Down Expand Up @@ -304,6 +310,8 @@ Returns:
| Status Code | Description | Component |
|-------------|-------------|-----------|
| 200 | Successful Response | [ConversationResponse](#conversationresponse) |
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
| 404 | Not Found | |
| 503 | Service Unavailable | |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
Expand Down Expand Up @@ -335,6 +343,8 @@ Returns:
| Status Code | Description | Component |
|-------------|-------------|-----------|
| 200 | Successful Response | [ConversationDeleteResponse](#conversationdeleteresponse) |
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
| 404 | Not Found | |
| 503 | Service Unavailable | |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
Expand Down
25 changes: 25 additions & 0 deletions src/app/endpoints/conversations.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
ConversationDeleteResponse,
ConversationsListResponse,
ConversationDetails,
UnauthorizedResponse,
)
from utils.endpoints import (
check_configuration_loaded,
Expand All @@ -45,6 +46,14 @@
}
],
},
400: {
"description": "Missing or invalid credentials provided by client",
"model": UnauthorizedResponse,
},
401: {
"description": "Unauthorized: Invalid or missing Bearer token",
"model": UnauthorizedResponse,
},
404: {
"detail": {
"response": "Conversation not found",
Expand All @@ -65,6 +74,14 @@
"success": True,
"message": "Conversation deleted successfully",
},
400: {
"description": "Missing or invalid credentials provided by client",
"model": UnauthorizedResponse,
},
401: {
"description": "Unauthorized: Invalid or missing Bearer token",
"model": UnauthorizedResponse,
},
404: {
"detail": {
"response": "Conversation not found",
Expand Down Expand Up @@ -100,6 +117,14 @@
},
]
},
400: {
"description": "Missing or invalid credentials provided by client",
"model": UnauthorizedResponse,
},
401: {
"description": "Unauthorized: Invalid or missing Bearer token",
"model": UnauthorizedResponse,
},
503: {
"detail": {
"response": "Unable to connect to Llama Stack",
Expand Down
2 changes: 1 addition & 1 deletion src/app/endpoints/info.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ async def info_endpoint_handler(
Handle request to the /info endpoint.

Process GET requests to the /info endpoint, returning the
service name and version.
service name, version and Llama-stack version.

Returns:
InfoResponse: An object containing the service's name and version.
Expand Down
2 changes: 1 addition & 1 deletion src/app/endpoints/models.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@
},
]
},
503: {"description": "Connection to Llama Stack is broken"},
500: {"description": "Connection to Llama Stack is broken"},
}


Expand Down
2 changes: 1 addition & 1 deletion src/app/endpoints/query.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@
"description": "User is not authorized",
"model": ForbiddenResponse,
},
503: {
500: {
"detail": {
"response": "Unable to connect to Llama Stack",
"cause": "Connection error.",
Expand Down
Loading
Loading