Documentation: iterating over collection and documents module

[nishika26]

Summary

Target issue is #801

Notes

• Documentation
  • Clarified collections documentation - including job tracking and status retrieval.
  • Updated document deletion behavior documentation to distinguish between soft and permanent deletion.
  • Documented document transformation capabilities, including supported formats and transformers.
  • Refined API response structure documentation for collections, credentials, and document endpoints.
  • Improved webhook credential configuration examples.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates API documentation across the collections, credentials, and documents interfaces to clarify endpoint behaviors, standardize terminology (shifting from "document store" to "vector store"), and improve wording around response formats, async job handling, and resource deletion semantics.

Changes

API Documentation Clarification & Standardization

Layer / File(s)	Summary
Collections Interface Terminology backend/app/api/docs/collections/README.md, create.md	Terminology updated from "document store for RAG" to "Vector store for File search"; removed tight coupling description to OpenAI File Search in README.
Collections Job & Async Behavior backend/app/api/docs/collections/create.md, delete.md, job_info.md	Async creation and deletion endpoints clarified to describe immediate return of job ID and status; clients retrieve results via callback URL or collection job info endpoint. Failure handling now explicitly states automatic cleanup of previously created resources.
Collections Response Fields backend/app/api/docs/collections/info.md, list.md	include_url documented to return signed URLs for retrieved document(s) (plural); list endpoint clarifies conditional response fields: llm_service_id/llm_service_name for Assistant-created collections, knowledge_base_id/knowledge_base_provider for Vector Store–only collections.
Credentials & Document Endpoints backend/app/api/docs/credentials/create.md, documents/delete.md, permanent_delete.md, upload.md	Webhook credential example updated to nested credential.webhook_ structure; document deletion docs reworded to clarify active collections/knowledge bases deletion implications; upload docs refined to emphasize optional background transformation and supported transformations formatting.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~8 minutes

Possibly related PRs

• ProjectTech4DevAI/kaapi-backend#622: Introduces conditional collection public fields and to_collection_public serialization, directly corresponding to this PR's documentation updates on conditional response fields (llm_service_id vs knowledge_base_id).
• ProjectTech4DevAI/kaapi-backend#509: Implements include_url and signed URL generation for collection info endpoint, matching this PR's documentation update clarifying that include_url returns signed URLs for retrieved documents.
• ProjectTech4DevAI/kaapi-backend#638: Also modifies backend/app/api/docs/collections/info.md to update include_url/include_docs behavior wording.

Suggested reviewers

• vprashrex
• AkhileshNegi
• Prajna1999

---

🐰 A Rabbit's Ode to Clarity

Through docs we hop, refining every line,
"Vector stores" and "jobs" now align,
Async flows and cleanup paths so bright,
The API's story shines more clear and right! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the main change: documentation updates across the collections and documents modules with clarifications on API behavior and response formats.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch enahncement/documentation_collection

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

backend/app/api/docs/collections/create.md (1)

19-21: ⚡ Quick win

Clarify async wording to avoid conflict with the deprecation note.

Line 19 says “Vector store/assistant” is created asynchronously, but Line 10 marks Assistant attachment as deprecated. Consider phrasing this as “collection job is processed asynchronously” (and mention assistant creation only as legacy/optional behavior) to avoid mixed signals.

🤖 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 `@backend/app/api/docs/collections/create.md` around lines 19 - 21, Change the
phrasing that currently reads "Vector store/assistant will be created
asynchronously" to say the "collection job is processed asynchronously" and
clarify that assistant creation is legacy/optional/deprecated behavior;
specifically update the sentence referencing "Vector store/assistant" to focus
on asynchronous collection job processing and add a short clause noting that
attaching/creating an assistant is deprecated and only performed for legacy
compatibility when present (refer to the existing "Assistant attachment"
deprecation note).

🤖 Prompt for all review comments with 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.

Inline comments:
In `@backend/app/api/docs/collections/delete.md`:
- Line 3: Replace the unhyphenated phrase "two step process" with the hyphenated
compound adjective "two-step process" in the markdown text (the line containing
"This is a two step process:") to improve readability; ensure the sentence reads
"This is a two-step process:".

In `@backend/app/api/docs/credentials/create.md`:
- Around line 54-56: Update the example JSON to use the canonical provider key
"webhook_secret" instead of "webhook_" and fix the JSON syntax error by adding
the missing quote and colon so the pair reads "webhook_secret":
"webhook_secret"; ensure all examples (including the multi-provider example and
the credential object) consistently use "webhook_secret".
- Around line 55-57: Fix the invalid JSON and incorrect provider key in the
webhook examples by closing the missing quote on the webhook_secret key in both
blocks, removing the trailing comma after the webhook_secret block in the second
example, and replacing the incorrect provider key "webhook_" with the canonical
"webhook_secret"; update the JSON objects surrounding "webhook_secret" (the
example blocks around the quoted webhook_secret entries) so they are valid JSON
with properly quoted keys and no stray commas.

---

Nitpick comments:
In `@backend/app/api/docs/collections/create.md`:
- Around line 19-21: Change the phrasing that currently reads "Vector
store/assistant will be created asynchronously" to say the "collection job is
processed asynchronously" and clarify that assistant creation is
legacy/optional/deprecated behavior; specifically update the sentence
referencing "Vector store/assistant" to focus on asynchronous collection job
processing and add a short clause noting that attaching/creating an assistant is
deprecated and only performed for legacy compatibility when present (refer to
the existing "Assistant attachment" deprecation note).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 235f6bd3-f76f-4089-acfe-c499e7432c97

📥 Commits

Reviewing files that changed from the base of the PR and between 5f8c4c3 and 63398b0.

📒 Files selected for processing (11)

• backend/app/api/docs/collections/README.md
• backend/app/api/docs/collections/create.md
• backend/app/api/docs/collections/delete.md
• backend/app/api/docs/collections/info.md
• backend/app/api/docs/collections/job_info.md
• backend/app/api/docs/collections/list.md
• backend/app/api/docs/credentials/create.md
• backend/app/api/docs/documents/README.md
• backend/app/api/docs/documents/delete.md
• backend/app/api/docs/documents/permanent_delete.md
• backend/app/api/docs/documents/upload.md

💤 Files with no reviewable changes (2)

• backend/app/api/docs/documents/README.md
• backend/app/api/docs/collections/README.md