LCORE-724: OpenAPI schema #592
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
WalkthroughAdds v2 conversation endpoints (/v2/conversations and /v2/conversations/{conversation_id}) to OpenAPI JSON and docs, including GET list, GET by ID, and DELETE. Introduces a new schema ConversationsListResponseV2 and updates documentation/output to reference it alongside standard response codes. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Client
participant API as API (v2)
participant Store as Data Store
rect rgb(235, 245, 255)
note over Client,API: List conversations (GET /v2/conversations)
Client->>API: GET /v2/conversations
API->>Store: Fetch user conversations
Store-->>API: conversations[]
API-->>Client: 200 ConversationsListResponseV2
end
rect rgb(245, 235, 255)
note over Client,API: Retrieve conversation (GET /v2/conversations/{id})
Client->>API: GET /v2/conversations/{id}
API->>Store: Load conversation by id
alt Found
Store-->>API: conversation
API-->>Client: 200 conversation
else Not found
Store-->>API: null
API-->>Client: 404
end
end
rect rgb(235, 255, 240)
note over Client,API: Delete conversation (DELETE /v2/conversations/{id})
Client->>API: DELETE /v2/conversations/{id}
API->>Store: Delete by id
alt Deleted
Store-->>API: ok
API-->>Client: 200/204
else Not found / unauthorized / invalid
Store-->>API: error
API-->>Client: 401/404/422
end
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/openapi.json(2 hunks)docs/openapi.md(2 hunks)docs/output.md(2 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
docs/output.md
365-365: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
389-389: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
413-413: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: build-pr
- GitHub Check: e2e_tests
Comment on lines
+735
to
+752
| "responses": { | ||
| "200": { | ||
| "description": "Successful Response", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/ConversationsListResponseV2" | ||
| } | ||
| } | ||
| }, | ||
| "conversations": [ | ||
| { | ||
| "conversation_id": "123e4567-e89b-12d3-a456-426614174000" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
Bring back the non-200 responses and fix the example payload for the v2 list endpoint.
The v2 route still enforces auth and can surface backend outages, so dropping 400/401/503 regresses the contract. Also, the example currently shows an array of objects, but the new schema promises strings. Please align both pieces.
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversationsListResponseV2"
}
}
- },
- "conversations": [
- {
- "conversation_id": "123e4567-e89b-12d3-a456-426614174000"
- }
- ]
- }
+ },
+ "conversations": [
+ "123e4567-e89b-12d3-a456-426614174000",
+ "456e7890-e12b-34d5-a678-901234567890"
+ ]
+ },
+ "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": {
+ "response": "Unable to connect to Llama Stack",
+ "cause": "Connection error."
+ }
+ }
}
}
},📝 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
| "responses": { | |
| "200": { | |
| "description": "Successful Response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/ConversationsListResponseV2" | |
| } | |
| } | |
| }, | |
| "conversations": [ | |
| { | |
| "conversation_id": "123e4567-e89b-12d3-a456-426614174000" | |
| } | |
| ] | |
| } | |
| } | |
| } | |
| "responses": { | |
| "200": { | |
| "description": "Successful Response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/ConversationsListResponseV2" | |
| } | |
| } | |
| }, | |
| "conversations": [ | |
| "123e4567-e89b-12d3-a456-426614174000", | |
| "456e7890-e12b-34d5-a678-901234567890" | |
| ] | |
| }, | |
| "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": { | |
| "response": "Unable to connect to Llama Stack", | |
| "cause": "Connection error." | |
| } | |
| } | |
| } | |
| }, |
🤖 Prompt for AI Agents
In docs/openapi.json around lines 735 to 752, the 200-only responses and example
are incorrect for the v2 list endpoint: restore the non-200 responses (at
minimum 400 Bad Request, 401 Unauthorized, and 503 Service Unavailable) with
appropriate descriptions and content that reference the common error schema used
elsewhere (e.g., application/json -> $ref to the error schema), and modify the
200 example payload so the "conversations" example is an array of strings (e.g.,
["123e4567-e89b-12d3-a456-426614174000"]) to match ConversationsListResponseV2
rather than an array of objects. Ensure response entries follow the same
structure and $ref usage as other endpoints in the spec.
Comment on lines
+774
to
+840
| "200": { | ||
| "description": "Successful Response", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/ConversationResponse" | ||
| } | ||
| } | ||
| }, | ||
| "conversation_id": "123e4567-e89b-12d3-a456-426614174000", | ||
| "chat_history": [ | ||
| { | ||
| "messages": [ | ||
| { | ||
| "content": "Hi", | ||
| "type": "user" | ||
| }, | ||
| { | ||
| "content": "Hello!", | ||
| "type": "assistant" | ||
| } | ||
| ], | ||
| "started_at": "2024-01-01T00:00:00Z", | ||
| "completed_at": "2024-01-01T00:00:05Z", | ||
| "provider": "provider ID", | ||
| "model": "model ID" | ||
| } | ||
| ] | ||
| }, | ||
| "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", | ||
| "cause": "The specified conversation ID does not exist." | ||
| }, | ||
| "description": "Not Found" | ||
| }, | ||
| "422": { | ||
| "description": "Validation Error", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/HTTPValidationError" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
Keep the 503 response on the v2 get-by-id operation.
The v1 definition still documents 503 when the upstream Llama Stack is unreachable; v2 should do the same so clients can handle outages correctly.
"404": {
"detail": {
"response": "Conversation not found",
"cause": "The specified conversation ID does not exist."
},
"description": "Not Found"
- },
- "422": {
+ },
+ "503": {
+ "detail": {
+ "response": "Unable to connect to Llama Stack",
+ "cause": "Connection error."
+ },
+ "description": "Service Unavailable"
+ },
+ "422": {
"description": "Validation Error",
"content": {
"application/json": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}📝 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
| "200": { | |
| "description": "Successful Response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/ConversationResponse" | |
| } | |
| } | |
| }, | |
| "conversation_id": "123e4567-e89b-12d3-a456-426614174000", | |
| "chat_history": [ | |
| { | |
| "messages": [ | |
| { | |
| "content": "Hi", | |
| "type": "user" | |
| }, | |
| { | |
| "content": "Hello!", | |
| "type": "assistant" | |
| } | |
| ], | |
| "started_at": "2024-01-01T00:00:00Z", | |
| "completed_at": "2024-01-01T00:00:05Z", | |
| "provider": "provider ID", | |
| "model": "model ID" | |
| } | |
| ] | |
| }, | |
| "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", | |
| "cause": "The specified conversation ID does not exist." | |
| }, | |
| "description": "Not Found" | |
| }, | |
| "422": { | |
| "description": "Validation Error", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/HTTPValidationError" | |
| } | |
| } | |
| } | |
| } | |
| } | |
| "404": { | |
| "detail": { | |
| "response": "Conversation not found", | |
| "cause": "The specified conversation ID does not exist." | |
| }, | |
| "description": "Not Found" | |
| }, | |
| "503": { | |
| "detail": { | |
| "response": "Unable to connect to Llama Stack", | |
| "cause": "Connection error." | |
| }, | |
| "description": "Service Unavailable" | |
| }, | |
| "422": { | |
| "description": "Validation Error", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/HTTPValidationError" | |
| } | |
| } | |
| } | |
| } |
Comment on lines
+861
to
+910
| "200": { | ||
| "description": "Successful Response", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/ConversationDeleteResponse" | ||
| } | ||
| } | ||
| }, | ||
| "conversation_id": "123e4567-e89b-12d3-a456-426614174000", | ||
| "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", | ||
| "cause": "The specified conversation ID does not exist." | ||
| }, | ||
| "description": "Not Found" | ||
| }, | ||
| "422": { | ||
| "description": "Validation Error", | ||
| "content": { | ||
| "application/json": { | ||
| "schema": { | ||
| "$ref": "#/components/schemas/HTTPValidationError" | ||
| } | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
Add the 503 branch back to the v2 delete response set.
Deletion can still fail when the backend is unavailable; retaining the 503 entry keeps the v2 spec aligned with v1 behavior.
"404": {
"detail": {
"response": "Conversation not found",
"cause": "The specified conversation ID does not exist."
},
"description": "Not Found"
- },
- "422": {
+ },
+ "503": {
+ "detail": {
+ "response": "Unable to connect to Llama Stack",
+ "cause": "Connection error."
+ },
+ "description": "Service Unavailable"
+ },
+ "422": {
"description": "Validation Error",
"content": {
"application/json": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}📝 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
| "200": { | |
| "description": "Successful Response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/ConversationDeleteResponse" | |
| } | |
| } | |
| }, | |
| "conversation_id": "123e4567-e89b-12d3-a456-426614174000", | |
| "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", | |
| "cause": "The specified conversation ID does not exist." | |
| }, | |
| "description": "Not Found" | |
| }, | |
| "422": { | |
| "description": "Validation Error", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/HTTPValidationError" | |
| } | |
| } | |
| } | |
| } | |
| "200": { | |
| "description": "Successful Response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/ConversationDeleteResponse" | |
| } | |
| } | |
| }, | |
| "conversation_id": "123e4567-e89b-12d3-a456-426614174000", | |
| "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", | |
| "cause": "The specified conversation ID does not exist." | |
| }, | |
| "description": "Not Found" | |
| }, | |
| "503": { | |
| "detail": { | |
| "response": "Unable to connect to Llama Stack", | |
| "cause": "Connection error." | |
| }, | |
| "description": "Service Unavailable" | |
| }, | |
| "422": { | |
| "description": "Validation Error", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/HTTPValidationError" | |
| } | |
| } | |
| } | |
| } |
🤖 Prompt for AI Agents
In docs/openapi.json around lines 861 to 910, the 503 Service Unavailable
response branch was removed from the v2 DELETE response set; re-add a "503"
response object under the same responses block with a descriptive "Service
Unavailable" description and a content section for "application/json" that
references the appropriate error schema (e.g.,
"#/components/schemas/ServiceUnavailableResponse" or the project’s standard
error schema if that specific one doesn't exist) so the v2 spec matches v1
behavior when the backend is unavailable.
Comment on lines
+361
to
+366
| ### ✅ Responses | ||
|
|
||
| | Status Code | Description | Component | | ||
| |-------------|-------------|-----------| | ||
| | 200 | Successful Response | [ConversationsListResponseV2](#conversationslistresponsev2) | | ||
| ## GET `/v2/conversations/{conversation_id}` |
There was a problem hiding this comment.
Restore the full error response table for the v2 conversations list.
The v1 endpoint immediately above still emits 400/401/503, and the v2 handler calls the same stack, so the new table advertising only 200 is incorrect. Please restore the missing error rows so consumers know to expect auth failures and backend outages.
| Status Code | Description | Component |
|-------------|-------------|-----------|
| 200 | Successful Response | [ConversationsListResponseV2](#conversationslistresponsev2) |
+| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
+| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
+| 503 | Service Unavailable | |📝 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
| ### ✅ Responses | |
| | Status Code | Description | Component | | |
| |-------------|-------------|-----------| | |
| | 200 | Successful Response | [ConversationsListResponseV2](#conversationslistresponsev2) | | |
| ## GET `/v2/conversations/{conversation_id}` | |
| ### ✅ Responses | |
| | Status Code | Description | Component | | |
| |-------------|-------------|-----------| | |
| | 200 | Successful Response | [ConversationsListResponseV2](#conversationslistresponsev2) | | |
| | 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) | | |
| | 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) | | |
| | 503 | Service Unavailable | | |
🤖 Prompt for AI Agents
In docs/openapi.md around lines 361 to 366, the Responses table for the GET
/v2/conversations/{conversation_id} only lists 200; restore the missing error
response rows (400, 401, 503) by copying the same error entries used for the v1
conversations list table directly above so consumers see Bad Request,
Unauthorized, and Service Unavailable responses and their components; ensure the
table rows match the v1 wording and component links exactly so the v2 docs
reflect the same error surface as the v1 handler.
Comment on lines
+383
to
+389
| | 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 | | | ||
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | |
There was a problem hiding this comment.
Keep the service-unavailable response for the v2 get-by-id endpoint.
The v1 entry documents 503 when the Llama Stack is down, and the v2 route has the same dependency. Please add the missing row back so clients don’t misinterpret outage responses.
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
| 404 | Not Found | |
+| 503 | Service Unavailable | |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |📝 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
| | 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 | | | |
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | | |
| | 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) | |
🤖 Prompt for AI Agents
In docs/openapi.md around lines 383 to 389, the v2 get-by-id response table is
missing the 503 Service Unavailable row; add a row with Status Code 503,
Description indicating the Llama Stack or dependent service is down (e.g.,
"Service Unavailable: Llama Stack down"), and Component referencing the
appropriate error schema (e.g., [ServiceUnavailableResponse] or existing 503
component) so clients see outage responses the same as v1.
Comment on lines
+407
to
+413
| | 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 | | | ||
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | |
There was a problem hiding this comment.
Include the 503 failure state for the v2 delete endpoint.
Deletion still talks to the same backend as v1, so it can surface 503. Documenting only happy-path responses is misleading—please reintroduce the unavailable row.
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
| 404 | Not Found | |
+| 503 | Service Unavailable | |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |📝 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
| | 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 | | | |
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | | |
| | 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) | |
🤖 Prompt for AI Agents
In docs/openapi.md around lines 407 to 413, the v2 DELETE endpoint responses are
missing the 503 state; add a table row for HTTP 503 with a short description
like "Service Unavailable" and reference the existing component used for
unavailability (e.g. [UnavailableResponse](#unavailableresponse) or the
equivalent component already defined in the spec) so the doc includes the
backend-unavailable failure case.
Comment on lines
+361
to
+366
| ### ✅ Responses | ||
|
|
||
| | Status Code | Description | Component | | ||
| |-------------|-------------|-----------| | ||
| | 200 | Successful Response | [ConversationsListResponseV2](#conversationslistresponsev2) | | ||
| ## GET `/v2/conversations/{conversation_id}` |
There was a problem hiding this comment.
Mirror the v1 error responses in the v2 conversations list table.
Same backend means the v2 route will still yield 400/401/503. Without documenting them the OpenAPI summary is inaccurate.
| Status Code | Description | Component |
|-------------|-------------|-----------|
| 200 | Successful Response | [ConversationsListResponseV2](#conversationslistresponsev2) |
+| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
+| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
+| 503 | Service Unavailable | |📝 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
| ### ✅ Responses | |
| | Status Code | Description | Component | | |
| |-------------|-------------|-----------| | |
| | 200 | Successful Response | [ConversationsListResponseV2](#conversationslistresponsev2) | | |
| ## GET `/v2/conversations/{conversation_id}` | |
| ### ✅ Responses | |
| | Status Code | Description | Component | | |
| |-------------|-------------|-----------| | |
| | 200 | Successful Response | [ConversationsListResponseV2](#conversationslistresponsev2) | | |
| | 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) | | |
| | 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) | | |
| | 503 | Service Unavailable | | | |
| ## GET `/v2/conversations/{conversation_id}` |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
365-365: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In docs/output.md around lines 361 to 366, the v2 Conversations list response
table only documents 200 and omits error responses; update the table to mirror
the v1 error responses by adding rows for 400, 401, and 503 with appropriate
descriptions and the same component references used in v1 (e.g., the existing
error response component anchors), ensuring the table entries match formatting
and links used elsewhere so the OpenAPI summary accurately reflects the backend
behavior.
Comment on lines
+383
to
+389
| | 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 | | | ||
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | |
There was a problem hiding this comment.
Document the 503 path for the v2 get-by-id endpoint.
Same reasoning as v1: backend outages still bubble up, so the table should keep the 503 entry.
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
| 404 | Not Found | |
+| 503 | Service Unavailable | |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |📝 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
| | 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 | | | |
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | | |
| | 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) | |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
389-389: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In docs/output.md around lines 383 to 389, the response table for the v2
get-by-id endpoint is missing the 503 entry; add a row for 503 (Service
Unavailable) to match v1. Insert a new line in the table (between the 404 and
422 rows) with the status code 503, a short description like "Service
Unavailable: backend outage", and link the Component to the appropriate response
type (e.g. [ServiceUnavailableResponse](#serviceunavailableresponse) or the
existing error response used for 503), so the table reflects backend outage
behavior.
Comment on lines
+407
to
+413
| | 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 | | | ||
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | |
There was a problem hiding this comment.
Add the missing 503 response to the v2 delete endpoint table.
Deletion can still fail when the upstream service is down; please reflect that in the docs.
| 401 | Unauthorized: Invalid or missing Bearer token | [UnauthorizedResponse](#unauthorizedresponse) |
| 404 | Not Found | |
+| 503 | Service Unavailable | |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |📝 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
| | 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 | | | |
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | | |
| | 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) | |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
413-413: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In docs/output.md around lines 407 to 413, the v2 delete endpoint response table
is missing the 503 entry; add a new table row for status code 503 with a concise
description like "Upstream service unavailable" (or "Service Unavailable") and a
component link (e.g. [ServiceUnavailableResponse](#serviceunavailableresponse))
so the docs reflect failures when upstream services are down; insert the 503 row
in the table (preferably after 404) following the same pipe-separated format as
the other rows.
This was referenced Sep 29, 2025
Merged
18 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
LCORE-724: OpenAPI schema
Type of change
Related Tickets & Documents
Summary by CodeRabbit
New Features
Documentation