Updated OpenAPI spec #884
Updated OpenAPI spec #884
Conversation
WalkthroughUpdates to OpenAPI specification documentation files introducing versioned endpoint naming conventions (V1/V2), replacing Agent API references with Responses API, expanding HTTP status mappings with granular error codes (401, 403, 404, 422, 429, 500, 503), and introducing new public schema entities for tooling and conversation endpoints. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Possibly related PRs
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
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: 2
🧹 Nitpick comments (1)
docs/openapi.md (1)
4098-4102: Simplify wording: "inaccessible" instead of "not accessible".Line 4101 in the ModelContextProtocolServer description uses wordier phrasing "are not accessible to lightspeed-core agents" where a more concise alternative exists.
Consider this minor stylistic improvement for clarity:
-configured in the llama-stack run.yaml are not accessible to lightspeed-core agents. +configured in the llama-stack run.yaml are inaccessible to lightspeed-core agents.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/openapi.md(18 hunks)docs/output.md(16 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-09-02T11:09:23.107Z
Learnt from: radofuchs
Repo: lightspeed-core/lightspeed-stack PR: 485
File: tests/e2e/features/authorized_noop.feature:11-11
Timestamp: 2025-09-02T11:09:23.107Z
Learning: The authorized endpoint in the lightspeed-stack project does not use the /v1 API prefix and should be accessed directly as "authorized" rather than "/v1/authorized".
Applied to files:
docs/openapi.mddocs/output.md
🪛 LanguageTool
docs/openapi.md
[grammar] ~1028-~1028: Use a hyphen to join words.
Context: ...ler_base that provides the Responses API specific retrieve_response and get_topic...
(QB_NEW_EN_HYPHEN)
[style] ~4101-~4101: Consider using “inaccessible” to avoid wordiness.
Context: ...figured in the llama-stack run.yaml are not accessible to lightspeed-core agents. Useful reso...
(NOT_ABLE_PREMIUM)
docs/output.md
[grammar] ~1028-~1028: Use a hyphen to join words.
Context: ...ler_base that provides the Responses API specific retrieve_response and get_topic...
(QB_NEW_EN_HYPHEN)
[style] ~4101-~4101: Consider using “inaccessible” to avoid wordiness.
Context: ...figured in the llama-stack run.yaml are not accessible to lightspeed-core agents. Useful reso...
(NOT_ABLE_PREMIUM)
🪛 markdownlint-cli2 (0.18.1)
docs/openapi.md
2467-2467: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
3187-3187: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
docs/output.md
2467-2467: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
3187-3187: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
⏰ 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). (6)
- GitHub Check: build-pr
- GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-on-pull-request
- GitHub Check: E2E: library mode / azure
- GitHub Check: E2E: server mode / azure
- GitHub Check: E2E: library mode / ci
- GitHub Check: E2E: server mode / ci
🔇 Additional comments (5)
docs/openapi.md (4)
3408-3417: Verify new schema entities are defined in the codebase and properly documented.The PR introduces new public schema models in the documentation (APIKeyTokenConfiguration at lines 3408–3417, ToolCallSummary and ToolResultSummary at lines 4527–4554). Ensure:
- These models are defined in the actual codebase
- The documentation accurately reflects the code definitions
- These entities are cross-referenced in all relevant endpoint descriptions and response models
1025-1025: Ensure "Responses API" terminology is used consistently throughout.The PR transitions from "Agent API" to "Responses API" references in several endpoint descriptions. Lines 1025, 1325, 2079, and 2254 show examples of this terminology shift. Verify all Agent API references have been replaced.
Scan for any remaining "Agent API" references:
#!/bin/bash # Description: Verify complete terminology migration from Agent API to Responses API # Search for any lingering Agent API references agent_refs=$(rg -c "Agent API" docs/openapi.md) echo "Remaining 'Agent API' references: $agent_refs" # Count Responses API references as comparison responses_refs=$(rg -c "Responses API" docs/openapi.md) echo "Total 'Responses API' references: $responses_refs" # Show context for any Agent API references found if [ "$agent_refs" -gt 0 ]; then rg -n -C 2 "Agent API" docs/openapi.md fiAlso applies to: 1325-1325, 2079-2079, 2254-2254
1023-1032: Verify endpoint versioning is consistent across all V1 and V2 endpoints.The PR introduces "V1" versioning labels in endpoint headings (e.g., "Query Endpoint Handler V1" at line 1023, "Streaming Query Endpoint Handler V1" at line 1323, "Conversations List Endpoint Handler V1" at line 1970). Ensure this naming convention is applied consistently across all versioned endpoints and matches the actual URL paths.
3233-3243: Endpoint path is correctly documented.The
/authorizedendpoint documentation is accurate—it should be accessed without the/v1prefix, consistent with the actual implementation in the codebase (as evidenced by the authorized_noop.feature test file).docs/output.md (1)
1-100: Clarify purpose of duplicate documentation files.Both
docs/openapi.mdanddocs/output.mdappear to contain nearly identical OpenAPI specification documentation. If these are true duplicates, consolidate them to a single source of truth to reduce maintenance burden and consistency risks.
| > **Query Endpoint Handler V1** | ||
| Handle request to the /query endpoint using Agent API. | ||
| Handle request to the /query endpoint using Responses API. | ||
|
|
||
| This is a wrapper around query_endpoint_handler_base that provides | ||
| the Agent API specific retrieve_response and get_topic_summary functions. | ||
| the Responses API specific retrieve_response and get_topic_summary functions. |
There was a problem hiding this comment.
Fix grammar issue: hyphenate compound adjectives.
Line 1028 contains a grammar issue flagged by LanguageTool. The phrase "Responses API specific retrieve_response and get_topic_summary functions" should use hyphens to join compound adjectives/nouns for clarity.
Apply this fix:
-the Responses API specific retrieve_response and get_topic_summary functions.
+the Responses API–specific retrieve_response and get_topic_summary functions.📝 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.
| > **Query Endpoint Handler V1** | |
| Handle request to the /query endpoint using Agent API. | |
| Handle request to the /query endpoint using Responses API. | |
| This is a wrapper around query_endpoint_handler_base that provides | |
| the Agent API specific retrieve_response and get_topic_summary functions. | |
| the Responses API specific retrieve_response and get_topic_summary functions. | |
| > **Query Endpoint Handler V1** | |
| Handle request to the /query endpoint using Responses API. | |
| This is a wrapper around query_endpoint_handler_base that provides | |
| the Responses API–specific retrieve_response and get_topic_summary functions. |
🧰 Tools
🪛 LanguageTool
[grammar] ~1028-~1028: Use a hyphen to join words.
Context: ...ler_base that provides the Responses API specific retrieve_response and get_topic...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In docs/openapi.md around lines 1023 to 1028, the phrase "Responses API specific
retrieve_response and get_topic_summary functions" should be hyphenated to form
compound adjectives; change it to "Responses-API-specific retrieve_response and
get_topic_summary functions" (or "Responses API–specific ..." if using an
en-dash per style) so the compound modifier is clear and grammatically correct.
| | Status Code | Description | Component | | ||
| |-------------|-------------|-----------| | ||
| | 200 | Successful response | [ConversationUpdateResponse](#conversationupdateresponse) | | ||
| | 400 | Invalid request format | [BadRequestResponse](#badrequestresponse) |
There was a problem hiding this comment.
Fix markdown table pipe formatting.
Static analysis identified two markdown table formatting violations where trailing pipes are missing. Lines 2467 and 3187 each have a table header or row missing the trailing pipe character, violating the leading_and_trailing pipe style requirement.
Ensure all markdown tables follow the leading_and_trailing pipe style:
Line 2467:
-| Name | Type | Required | Description |
+| Name | Type | Required | Description |
|------|------|----------|-------------|
Line 3187:
-| Status Code | Description | Component |
+| Status Code | Description | Component |
|-------------|-------------|-----------|Note: Verify these lines explicitly as the pipe formatting may not render correctly in this diff view.
Also applies to: 3187-3187
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
2467-2467: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
🤖 Prompt for AI Agents
In docs/openapi.md around lines 2467 and 3187, two markdown table rows/headers
are missing the trailing pipe; update each affected line to include the closing
pipe character so the table follows the leading_and_trailing pipe style (i.e.,
ensure every table row and header ends with a "|" character), then re-run a
markdown linter to confirm no further table pipe violations remain.
1 participant
Description
Updated OpenAPI spec
Type of change
Tools used to create PR
Identify any AI code assistants used in this PR (for transparency and review context)
Related Tickets & Documents
Checklist before requesting a review
Testing
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.