codewiki
API

Public API Endpoints

Overview

This page documents the public API endpoints exposed by DeepDoc, grouped by resource family. These endpoints provide health checks, chatbot query capabilities, report retrieval, and user management operations. They are intended for use by both internal services and external clients integrating with DeepDoc.

The main runtime and chatbot engine logic is implemented in the Runtime Services & Chatbot Engine module.

All endpoints documented here are grounded in the actual handler code found in deepdoc/chatbot/service.py, deepdoc/chatbot/scaffold.py, and tests/fixtures/frameworks/django_app/urls.py.

API Request Lifecycle

For a detailed breakdown of the runtime and chatbot engine, see Runtime Services & Chatbot Engine.

Authentication

Health check and public query endpoints do not require authentication by default, as seen in deepdoc/chatbot/service.py:514 and deepdoc/chatbot/scaffold.py:30. The Django-based endpoints in tests/fixtures/frameworks/django_app/urls.py do not show explicit authentication decorators or middleware in the provided evidence.

If you deploy these endpoints in production, you must add authentication and authorization middleware as appropriate for your environment. See your framework's security documentation.

Endpoints

Health Check Endpoints

GET /health

Handlers:

  • health() (deepdoc/chatbot/service.py:529)
  • _health() (deepdoc/chatbot/scaffold.py:57)
  • health() (tests/fixtures/frameworks/django_app/urls.py:9)

Returns a simple status indicator for service health.

Parameters
LocationNameTypeRequiredDescription
————No parameters
Response
FieldTypeDescription
statusstring"ok" if healthy, "error" if startup failed
detailstringError detail (only present if startup failed)
Example
curl https://api.deepdoc.com/health
{ "status": "ok" }

If startup failed (scaffold fallback):

{ "status": "error", "detail": "ImportError: ..." }
Errors
StatusCondition
503Service startup failed (scaffold fallback)
200Always returns 200 if healthy

POST /health

Handler: health() (tests/fixtures/frameworks/django_app/urls.py:9)

No implementation details are present in the evidence. The POST method is registered but its behavior is unknown.

Parameters

No parameters documented.

Response

No response schema documented.

Errors
StatusCondition
—Not specified in evidence

Chatbot Query Endpoints

POST /query

Handlers:

  • query() (deepdoc/chatbot/service.py:533)
  • _query() (deepdoc/chatbot/scaffold.py:61)

Submits a natural language question to the DeepDoc chatbot and receives a grounded, context-rich answer with citations.

Parameters
LocationNameTypeRequiredDescription
bodyquestionstringyesThe user's question
bodyhistoryarray of objectsnoConversation history (list of {role, content})

Body Schema (from QueryRequest in deepdoc/chatbot/service.py:18):

{
  "question": "How does the query endpoint work?",
  "history": [
    {"role": "user", "content": "What endpoints are available?"},
    {"role": "assistant", "content": "See /health and /query."}
  ]
}
Response
FieldTypeDescription
answerstringThe chatbot's answer, grounded in code context
code_citationsarrayList of cited code chunks (dicts)
artifact_citationsarrayList of cited artifact chunks (dicts)
doc_linksarrayList of related documentation links
used_chunksintegerNumber of context chunks used in the answer
Example
curl -X POST https://api.deepdoc.com/query \
  -H "Content-Type: application/json" \
  -d '{"question": "How does the query endpoint work?"}'
{
  "answer": "The /query endpoint processes your question by expanding queries, embedding them, searching across code, artifacts, and docs, reranking results, and composing a detailed answer with citations.",
  "code_citations": [
    {"file": "deepdoc/chatbot/service.py", "lines": "53-150", "snippet": "..."}
  ],
  "artifact_citations": [],
  "doc_links": [
    {"title": "Runtime Services & Chatbot Engine", "url": "/runtime-services-chatbot", "doc_path": "runtime-services-chatbot.mdx"}
  ],
  "used_chunks": 5
}
Errors
StatusCondition
500Chatbot query failed (e.g., exception in handler)
503Service startup failed (scaffold fallback)

Report Retrieval Endpoint

GET /reports/{slug}

Handler: ReportView.get() (tests/fixtures/frameworks/django_app/urls.py:14)

Retrieves a report by slug. No implementation details are present in the evidence.

Parameters
LocationNameTypeRequiredDescription
pathslugstringyesReport identifier
Response

No response schema documented.

Example
curl https://api.deepdoc.com/reports/monthly-summary
Errors
StatusCondition
404Report not found (assumed)

User Management Endpoints

All user endpoints are handled by UserViewSet (tests/fixtures/frameworks/django_app/urls.py:18), which subclasses ModelViewSet.

GET /api/users

Handler: UserViewSet.list() (tests/fixtures/frameworks/django_app/urls.py:19)

Lists all users.

Parameters

No parameters documented.

Response

No response schema documented.

Example
curl https://api.deepdoc.com/api/users
Errors
StatusCondition
401Unauthorized (if auth enforced)

POST /api/users

Handler: UserViewSet.create() (tests/fixtures/frameworks/django_app/urls.py:25)

Creates a new user.

Parameters
LocationNameTypeRequiredDescription
body—objectyesUser creation payload (fields not specified)
Response

No response schema documented.

Example
curl -X POST https://api.deepdoc.com/api/users \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "email": "alice@example.com"}'
Errors
StatusCondition
400Invalid input (assumed)
401Unauthorized (if auth enforced)

GET /api/users/{id}

Handler: UserViewSet.retrieve() (tests/fixtures/frameworks/django_app/urls.py:22)

Retrieves a user by ID.

Parameters
LocationNameTypeRequiredDescription
pathidstringyesUser ID
Response

No response schema documented.

Example
curl https://api.deepdoc.com/api/users/123
Errors
StatusCondition
404User not found (assumed)
401Unauthorized (if auth enforced)

DELETE /api/users/{id}

Handler: UserViewSet.destroy() (tests/fixtures/frameworks/django_app/urls.py:28)

Deletes a user by ID.

Parameters
LocationNameTypeRequiredDescription
pathidstringyesUser ID
Response

No response schema documented.

Example
curl -X DELETE https://api.deepdoc.com/api/users/123
Errors
StatusCondition
404User not found (assumed)
401Unauthorized (if auth enforced)

GET /api/users/{id}/stats

Handler: UserViewSet.stats() (tests/fixtures/frameworks/django_app/urls.py:42)

Retrieves statistics for a user by ID.

Parameters
LocationNameTypeRequiredDescription
pathidstringyesUser ID
Response

No response schema documented.

Example
curl https://api.deepdoc.com/api/users/123/stats
Errors
StatusCondition
404User not found (assumed)
401Unauthorized (if auth enforced)

Execution Flow

Chatbot Query (POST /query)

  1. Request Parsing: The request body is parsed into a QueryRequest (deepdoc/chatbot/service.py:18).
  2. Service Instantiation: ChatbotQueryService is initialized with the repo root and config (deepdoc/chatbot/service.py:25).
  3. Query Expansion: _expand_query() (deepdoc/chatbot/service.py:164) may generate alternative queries via LLM if retrieval_cfg["query_expansion"] is enabled.
  4. Embedding: All queries are embedded in batch using embedding_client.embed() (from build_embedding_client() in deepdoc/chatbot/providers.py:136).
  5. Similarity Search: _multi_query_search() (deepdoc/chatbot/service.py:186) runs across code, artifact, doc, and relationship corpora.
  6. Chain Retrieval: _chain_retrieve() (deepdoc/chatbot/service.py:217) pulls in code from related files based on import graphs.
  7. Reranking: _rerank() (deepdoc/chatbot/service.py:260) optionally reranks chunks using LLM if retrieval_cfg["rerank"] is enabled.
  8. Prompt Construction: _build_prompt() (deepdoc/chatbot/service.py:402) assembles the final prompt for the LLM.
  9. Answer Generation: The LLM generates an answer, which is returned with citations and doc links.
  10. Error Handling: Any exception in the handler returns a 500 with {"error": "chatbot_query_failed", "detail": ...}.

Conditional Branches & Feature Flags:

  • query_expansion (config flag): If enabled, alternative queries are generated.
  • rerank (config flag): If enabled, LLM reranking is performed.
  • If no context is found, _no_context_result() returns a fallback answer.

Health Endpoints

  • GET /health in FastAPI always returns {"status": "ok"} unless the app failed to start, in which case the scaffold fallback returns {"status": "error", "detail": ...}.
  • No conditional logic or feature flags are present in the health handler.

User/Report Endpoints

  • No implementation or branching logic is present in the evidence for user or report endpoints.

State Changes & Side Effects

  • Chatbot Query: Reads from vector indexes and corpus files using load_corpus() and load_vector_index() (deepdoc/chatbot/persistence.py). No writes, cache, or background jobs are triggered by the query endpoint in the provided evidence.
  • User/Report Endpoints: No database or side effect logic is visible in the evidence.

Constants, Enums & Status Values

  • Health Status: "ok" (healthy), "error" (startup failed).
  • Chatbot Query Response: No enums, but the response always includes answer, code_citations, artifact_citations, doc_links, and used_chunks.

See Also

Runtime Services & Chatbot Engine

Details the main runtime services, chatbot engine, and service orchestration.

DeepDoc Chat API Integration

Integration details for the DeepDoc Chat API.

DeepDoc Embedding API Integration

Integration details for the DeepDoc Embedding API.

Referenced files:

  • deepdoc/chatbot/service.py
  • deepdoc/chatbot/scaffold.py
  • tests/fixtures/frameworks/django_app/urls.py

For implementation details and service orchestration, see Runtime Services & Chatbot Engine.

endpoint_listing

TODO: This section (endpoint_listing) needs to be filled in with details from the source files listed above.

request_response_examples

TODO: This section (request_response_examples) needs to be filled in with details from the source files listed above.

error_codes

TODO: This section (error_codes) needs to be filled in with details from the source files listed above.

Runtime Services & Chatbot Engine

Previous Page

Database Models & Schema

Next Page

On this page

Public API EndpointsOverviewAPI Request LifecycleAuthenticationEndpointsHealth Check EndpointsGET /healthParametersResponseExampleErrorsPOST /healthParametersResponseErrorsChatbot Query EndpointsPOST /queryParametersResponseExampleErrorsReport Retrieval EndpointGET /reports/{slug}ParametersResponseExampleErrorsUser Management EndpointsGET /api/usersParametersResponseExampleErrorsPOST /api/usersParametersResponseExampleErrorsGET /api/users/{id}ParametersResponseExampleErrorsDELETE /api/users/{id}ParametersResponseExampleErrorsGET /api/users/{id}/statsParametersResponseExampleErrorsExecution FlowChatbot Query (POST /query)Health EndpointsUser/Report EndpointsState Changes & Side EffectsConstants, Enums & Status ValuesSee Alsoendpoint_listingrequest_response_exampleserror_codes

Ask the codebase

Open a dedicated answer page with grounded citations.

Ask from any docs page and keep reading without losing context.