Docs: Update API documentation for endpoints to clarify parameters and functionality#638
Open
Docs: Update API documentation for endpoints to clarify parameters and functionality#638
Conversation
…eters and functionality
📝 WalkthroughWalkthroughDocumentation updates across multiple API docs: provider/config handling, completion types and guardrails, evaluation usage of stored configs, LLM input formats, STT dataset/feedback schemas, fine-tuning field formats, and minor endpoint field clarifications; no code or public API signatures changed. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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 (2)
backend/app/api/docs/api_keys/delete.md (1)
3-3: Consider clarifying "soft delete" for API consumers.The term "soft delete" is technical jargon that may not be immediately clear to all API users. Consider briefly explaining what this means in practice (e.g., whether the key can be restored, how long data is retained, etc.) to help users better understand the implications.
📝 Example clarification
-Revokes the API key via soft delete. Any requests using this key will fail after deletion. +Revokes the API key by marking it as deleted (the key data is retained for audit purposes but cannot be used). Any requests using this key will fail immediately after deletion.Or, if restoration is possible:
-Revokes the API key via soft delete. Any requests using this key will fail after deletion. +Revokes the API key by marking it as inactive. The key can be restored if needed. Any requests using this key will fail immediately after deletion.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@backend/app/api/docs/api_keys/delete.md` at line 3, Update the API docs text in backend/app/api/docs/api_keys/delete.md to replace the terse "soft delete" phrasing with a brief, consumer-facing clarification: state whether the key is reversible (can be restored), how long any audit/retention records are kept (if applicable), and confirm that any requests using the key will immediately fail after deletion; include a short example sentence such as "This is a soft delete: the key is deactivated immediately and requests will fail; it can be restored within X days (if restoration is supported) and audit records are retained for Y days," so consumers understand the practical implications.backend/app/api/docs/onboarding/onboarding.md (1)
18-19: Consider grouping field descriptions for better readability.The optional field descriptions (lines 18-19) are placed after the behavioral description (lines 16-17). For improved clarity, consider grouping all field descriptions together before explaining the behavior.
Example structure:
## 👤 User Handling **Fields:** - `email` (required): User's email address - `password` (optional): Password for the primary user (must be at least 8 characters) - `username` (optional): Full name of the primary user **Behavior:** - If `email` does not exist, a new user is created and linked to the project. - If the user already exists, they are simply attached to the project.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@backend/app/api/docs/onboarding/onboarding.md` around lines 18 - 19, Move the optional field bullets (`password`, `username`) so all field descriptions are grouped together before the behavior paragraph; create a short "Fields:" subsection listing `email` (required), `password` (optional, min 8 chars) and `username` (optional) and then create a separate "Behavior:" subsection that explains the create-or-attach logic for `email` (e.g., new user created and linked if email doesn't exist, otherwise attach existing user to project) to match the suggested structure.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/app/api/docs/llm/llm_call.md`:
- Around line 22-30: The docs are inconsistent: the structured "input" list
example and the sentence above it only mention support for `image`, `pdf`, and
`text` but the "Supported input types" line includes `audio`; update the
documentation to clarify audio support by either (A) adding `audio` to the
multimodal structured input examples and the preceding sentence if audio is
supported in lists, or (B) explicitly stating that `audio` is only valid for
single-object (non-multimodal) calls — make the change next to the "input"
structured example and the "Supported input types" line so the terms "input" and
"Supported input types" consistently reflect whether `audio` can appear in the
list.
In `@backend/app/api/docs/stt_evaluation/create_dataset.md`:
- Around line 15-23: The example JSON in the create_dataset request contains an
invalid trailing comma after the last item in the "samples" array; remove the
trailing comma after { "file_id": 12, "ground_truth": "hello how can I help you"
} so the "samples" array and overall JSON become valid (verify keys "name",
"description", "language_id", "samples", "file_id", and "ground_truth" remain
unchanged).
---
Nitpick comments:
In `@backend/app/api/docs/api_keys/delete.md`:
- Line 3: Update the API docs text in backend/app/api/docs/api_keys/delete.md to
replace the terse "soft delete" phrasing with a brief, consumer-facing
clarification: state whether the key is reversible (can be restored), how long
any audit/retention records are kept (if applicable), and confirm that any
requests using the key will immediately fail after deletion; include a short
example sentence such as "This is a soft delete: the key is deactivated
immediately and requests will fail; it can be restored within X days (if
restoration is supported) and audit records are retained for Y days," so
consumers understand the practical implications.
In `@backend/app/api/docs/onboarding/onboarding.md`:
- Around line 18-19: Move the optional field bullets (`password`, `username`) so
all field descriptions are grouped together before the behavior paragraph;
create a short "Fields:" subsection listing `email` (required), `password`
(optional, min 8 chars) and `username` (optional) and then create a separate
"Behavior:" subsection that explains the create-or-attach logic for `email`
(e.g., new user created and linked if email doesn't exist, otherwise attach
existing user to project) to match the suggested structure.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (12)
backend/app/api/docs/api_keys/delete.mdbackend/app/api/docs/collections/info.mdbackend/app/api/docs/config/create.mdbackend/app/api/docs/config/create_version.mdbackend/app/api/docs/evaluation/create_evaluation.mdbackend/app/api/docs/fine_tuning/create.mdbackend/app/api/docs/llm/llm_call.mdbackend/app/api/docs/onboarding/onboarding.mdbackend/app/api/docs/organization/update.mdbackend/app/api/docs/projects/create.mdbackend/app/api/docs/stt_evaluation/create_dataset.mdbackend/app/api/docs/stt_evaluation/update_feedback.md
Comment on lines
+15
to
+23
| ```json | ||
| { | ||
| "name": "Hindi call center dataset", | ||
| "description": "100 samples from call center recordings", | ||
| "language_id": 5, | ||
| "samples": [ | ||
| { "file_id": 12, "ground_truth": "hello how can I help you" }, | ||
| ] | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat backend/app/api/docs/stt_evaluation/create_dataset.mdRepository: ProjectTech4DevAI/kaapi-backend
Length of output: 938
🏁 Script executed:
#!/bin/bash
# Run the verification script from the review comment
python - <<'PY'
import json, pathlib, re, sys
p = pathlib.Path("backend/app/api/docs/stt_evaluation/create_dataset.md")
text = p.read_text(encoding="utf-8")
m = re.search(r"```json\s*(\{.*?\})\s*```", text, flags=re.S)
if not m:
print("No ```json block found")
sys.exit(1)
snippet = m.group(1)
try:
json.loads(snippet)
print("Valid JSON example")
except json.JSONDecodeError as e:
print(f"Invalid JSON example: {e}")
sys.exit(2)
PYRepository: ProjectTech4DevAI/kaapi-backend
Length of output: 140
Fix invalid JSON in the request example.
The trailing comma after the samples array item makes this JSON invalid and breaks copy/paste usage in API clients.
Suggested fix
{
"name": "Hindi call center dataset",
"description": "100 samples from call center recordings",
"language_id": 5,
"samples": [
- { "file_id": 12, "ground_truth": "hello how can I help you" },
+ { "file_id": 12, "ground_truth": "hello how can I help you" }
]
}📝 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
| ```json | |
| { | |
| "name": "Hindi call center dataset", | |
| "description": "100 samples from call center recordings", | |
| "language_id": 5, | |
| "samples": [ | |
| { "file_id": 12, "ground_truth": "hello how can I help you" }, | |
| ] | |
| } |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@backend/app/api/docs/stt_evaluation/create_dataset.md` around lines 15 - 23,
The example JSON in the create_dataset request contains an invalid trailing
comma after the last item in the "samples" array; remove the trailing comma
after { "file_id": 12, "ground_truth": "hello how can I help you" } so the
"samples" array and overall JSON become valid (verify keys "name",
"description", "language_id", "samples", "file_id", and "ground_truth" remain
unchanged).
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
backend/app/api/docs/llm/llm_call.md (1)
59-60: Add structure documentation for guardrails parameters.While
input_guardrailsandoutput_guardrailsare listed as optional parameters, the documentation doesn't explain what these lists should contain, their schema, or provide examples. Since this PR aims to clarify parameters and functionality, consider adding:
- Expected structure/schema for guardrail objects
- Available guardrail types or examples
- A reference to detailed guardrails documentation if it exists elsewhere
📝 Example documentation enhancement
- - `input_guardrails` (optional, list) - - `output_guardrails` (optional, list) + - `input_guardrails` (optional, list): List of guardrail configurations to apply to input validation + - Each guardrail object should specify the guardrail type and its parameters + - See guardrails schema documentation for available types and configuration options + - `output_guardrails` (optional, list): List of guardrail configurations to apply to output validation + - Each guardrail object should specify the guardrail type and its parameters + - See guardrails schema documentation for available types and configuration options🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@backend/app/api/docs/llm/llm_call.md` around lines 59 - 60, The docs list `input_guardrails` and `output_guardrails` but lack schema and examples; update the llm_call.md entry for these parameters to describe the expected structure of each guardrail object (e.g., required fields like `type`, `rule`, optional `severity`/`params`), enumerate supported `type` values or common examples (e.g., `no_personal_data`, `max_length`, `regex_match`), show a short YAML/JSON example for both `input_guardrails` and `output_guardrails`, and add a link or reference to any existing detailed guardrails documentation; ensure you reference the parameter names `input_guardrails` and `output_guardrails` so readers can find the usage in the LLM call docs.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@backend/app/api/docs/llm/llm_call.md`:
- Line 63: Update the example in the Kaapi documentation to replace the
non-existent "GPT-5" model with a real model that actually disallows temperature
(e.g., the "o1" series reasoning models referenced elsewhere); edit the sentence
in the paragraph that mentions parameter suppression so it reads that "o1 series
models do not support the temperature parameter," and ensure the example still
references metadata.warnings and the Kaapi abstraction so readers know
suppressed parameters are listed there.
---
Nitpick comments:
In `@backend/app/api/docs/llm/llm_call.md`:
- Around line 59-60: The docs list `input_guardrails` and `output_guardrails`
but lack schema and examples; update the llm_call.md entry for these parameters
to describe the expected structure of each guardrail object (e.g., required
fields like `type`, `rule`, optional `severity`/`params`), enumerate supported
`type` values or common examples (e.g., `no_personal_data`, `max_length`,
`regex_match`), show a short YAML/JSON example for both `input_guardrails` and
`output_guardrails`, and add a link or reference to any existing detailed
guardrails documentation; ensure you reference the parameter names
`input_guardrails` and `output_guardrails` so readers can find the usage in the
LLM call docs.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
backend/app/api/docs/llm/llm_call.mdbackend/app/api/docs/onboarding/onboarding.md
🚧 Files skipped from review as they are similar to previous changes (1)
- backend/app/api/docs/onboarding/onboarding.md
| - `output_guardrails` (optional, list) | ||
| - **Note** | ||
| - When using ad-hoc configuration, do not include `id` and `version` fields | ||
| - When using the Kaapi abstraction, parameters that are not supported by the selected provider or model are automatically suppressed. If any parameters are ignored, a list of warnings is included in the metadata.warnings. For example, the GPT-5 model does not support the temperature parameter, so Kaapi will neither throw an error nor pass this parameter to the model; instead, it will return a warning in the metadata.warnings response. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Search for GPT-5 references in the codebase
rg -n "GPT-5|gpt-5" --type=md --type=py --type=txtRepository: ProjectTech4DevAI/kaapi-backend
Length of output: 557
🏁 Script executed:
#!/bin/bash
# Get more context around line 63 in the file
cat -n backend/app/api/docs/llm/llm_call.md | sed -n '55,70p'Repository: ProjectTech4DevAI/kaapi-backend
Length of output: 1642
🏁 Script executed:
#!/bin/bash
# Check for other model references in the documentation to understand naming conventions
rg -n "GPT|Claude|o1|model" backend/app/api/docs/llm/llm_call.md | head -20Repository: ProjectTech4DevAI/kaapi-backend
Length of output: 695
Replace the non-existent "GPT-5" model with a real model example.
Line 63 references "GPT-5 model" as an example for parameter suppression, but GPT-5 doesn't exist. The documentation should use a real model with actual constraints—for example, "o1 series models do not support the temperature parameter" aligns with the reasoning model reference already mentioned on line 80.
Current snippet
- When using the Kaapi abstraction, parameters that are not supported by the selected provider or model are automatically suppressed. If any parameters are ignored, a list of warnings is included in the metadata.warnings. For example, the GPT-5 model does not support the temperature parameter, so Kaapi will neither throw an error nor pass this parameter to the model; instead, it will return a warning in the metadata.warnings response.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@backend/app/api/docs/llm/llm_call.md` at line 63, Update the example in the
Kaapi documentation to replace the non-existent "GPT-5" model with a real model
that actually disallows temperature (e.g., the "o1" series reasoning models
referenced elsewhere); edit the sentence in the paragraph that mentions
parameter suppression so it reads that "o1 series models do not support the
temperature parameter," and ensure the example still references
metadata.warnings and the Kaapi abstraction so readers know suppressed
parameters are listed there.
Prajna1999
approved these changes
Mar 3, 2026
| "vector_store_ids": ["vs_692d71f3f5708191b1c46525f3c1e196"], | ||
| "max_num_results": 20 | ||
| }]}}} | ||
| "completion": { |
Collaborator
There was a problem hiding this comment.
Add examples for stt, tts as well
| ## Important | ||
| - This endpoint accepts partial updates using dict[str, Any] for config_blob. | ||
| - Only the fields that need to be updated should be provided. | ||
| - Fields such as type and provider are inherited from the existing configuration and cannot be changed. |
Collaborator
There was a problem hiding this comment.
provider can be be changes ig
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
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.
Summary
Target issue is #PLEASE_TYPE_ISSUE_NUMBER
Explain the motivation for making this change. What existing problem does the pull request solve?
Checklist
Before submitting a pull request, please ensure that you mark these task.
fastapi run --reload app/main.pyordocker compose upin the repository root and test.Notes
Please add here if any other information is required for the reviewer.
Summary by CodeRabbit
New Features
Documentation