Backend Api Services

---
name: backend-api-services
description: "Modify and debug RAGFlow backend API routes, service layers, auth,
  DB models, channels, and system endpoints."
disable-model-invocation: true
metadata:
  disco-role: operating
license: Apache 2.0
---

# Backend API Services

Use this sub-skill when changing or debugging RAGFlow backend HTTP behavior: Quart app registration, `/api/v1` RESTful APIs, legacy `/v1/<page>` APIs, authentication, Peewee services/models, chat channels embedded in the API server, and health/system routes.

## Start Here

1. Identify the route family before editing:
   - Newer public RESTful endpoints live in `api/apps/restful_apis/` and register under `/api/v1`.
   - Legacy app modules use `api/apps/*_app.py` and register under `/v1/<page_name>`.
   - Backward compatibility aliases live in `api/apps/backward_compat.py` and register under both `/api/v1` and `/v1` as declared there.
2. Keep route handlers thin. Put API-facing orchestration in `api/apps/services/` when a RESTful endpoint needs multi-step behavior, and put reusable DB operations in `api/db/services/` against Peewee models from `api/db/db_models.py`.
3. Use the established response and validation helpers from `api/utils/api_utils.py`: `get_json_result`, `construct_json_result`, `get_request_json`, `validate_request`, `not_allowed_parameters`, `server_error_response`.
4. Check auth deliberately. `@login_required` supports signed JWT-style session tokens, API tokens, beta tokens, and server-side session fallback depending on `auth_types`.
5. For route audits, optionally run the bundled static helper: `python scripts/list_routes.py --root <checkout-or-api-snippets>`.

## References

- `references/backend-architecture.md` explains app setup, auth, service boundaries, DB patterns, and channels.
- `references/route-patterns.md` explains route registration, URL prefixes, endpoint conventions, and tests to update.
- `references/troubleshooting.md` maps common backend failures to likely causes and fixes.

## Guardrails

- RAGFlow uses Quart and Peewee; do not introduce Flask-only assumptions or SQLAlchemy patterns.
- Preserve async request handling. Await Quart request body/form helpers and wrap sync call sites with existing service patterns instead of blocking in handlers.
- Do not make runtime docs or helpers depend on a local checkout path. Treat source files and tests as evidence, not runtime dependencies.
- Keep compatibility aliases explicit when changing a public path; update both modern and legacy tests when behavior must coexist.