> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# DASHBOARD BE API DOCS HANDOFF

# dashboard-be API documentation handoff

The `api-docs` branch applies source-backed public contract corrections after OpenAPI export. The items below should move upstream into `dashboard-be` so the generated contract is correct without an override.

## Required backend changes

| Area                         | dashboard-be source                                                                       | Required change                                                                                                                                                                                                  | Docs override today                                                                           |
| ---------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Agent response schema        | `src/modules/agents/agents.entity.ts` and `agents-v1.controller.ts`                       | Publish the actual signed agent response DTO, including title, type, status, phone-number IDs, current version, and complete detail-version fields. Do not use the Sequelize entity with only `id` decorated.    | `scripts/improve_v1_openapi.py` expands the `Agents` schema.                                  |
| Agent request Swagger types  | Agent DTOs, including `agents.dto.ts` and `agents2.dto.ts`                                | Correct `version_title`, LLM fallback model/delay, transcriber, S2S voice provider, accent, icon, recording, responsiveness, and post-call analysis item decorators. Align examples with types and constraints.  | The normalization script corrects public schema types and invalid examples.                   |
| Create Call response         | `src/modules/calls/dto/create-call-response.dto.ts` and `calls-v1.controller.ts`          | Keep the runtime response and DTO identical: `id`, `to_phone_number`, `agent_id`, and optional `agent_version_number`. Add a controller test that serializes the public response.                                | The OpenAPI success example now matches the controller DTO.                                   |
| Call pagination parameters   | `src/modules/call-logs/dto/call-logs.dto.ts`                                              | Expose `page` and `limit` as integers with transformation, defaults, and limits instead of Swagger strings. Decide whether the list response should publish pagination metadata.                                 | Docs explain the current string schema and root-array response.                               |
| Knowledge Base response      | `src/modules/knowledge_base/knowledge-base.entity.ts`, service, and v1 controller         | Decorate the public resource DTO and document the actual `items` plus `meta` list envelope. Remove fields not returned by the entity.                                                                            | The OpenAPI schema and example now match service source.                                      |
| Webhook events               | `src/modules/user-webhooks/dto/create-user-webhook.dto.ts`, update DTO, delivery producer | Replace arbitrary strings and placeholder order events with one exported enum/catalog. Define the supported event names and payload schemas.                                                                     | Docs use current dotted call examples but flag the catalog as contract source.                |
| Webhook list envelope        | `src/modules/user-webhooks/user-webhooks-v1.controller.ts`                                | Keep the `webhooks` collection key in schema, runtime response, tests, and examples. Publish default and maximum limits.                                                                                         | The OpenAPI example now uses `webhooks` and default limit `10`.                               |
| Global errors and throttling | API gateway, guards, exception filters, and controllers                                   | Confirm where `422` and `429` are emitted, whether `Retry-After` is guaranteed, actual rate-limit scopes, request IDs, and server timeout guarantees. Add reusable OpenAPI responses only for verified behavior. | Errors and reliability pages are conservative and do not claim one universal limit or header. |
| Operation descriptions       | v1 controllers                                                                            | Add the missing `@ApiOperation({ description })` text upstream for all 49 public operations.                                                                                                                     | The normalization script fills 29 missing descriptions.                                       |

## Tests to add in dashboard-be

1. Export OpenAPI in CI and validate every request/response example against its schema.
2. Snapshot public v1 operation IDs, methods, paths, auth, and response envelopes.
3. Assert `@ApiExcludeEndpoint()` routes are absent from exported OpenAPI.
4. Exercise Create Agent, Publish Agent, Create Call, list envelopes, and webhook registration in a non-production environment.
5. Fail when a DTO example violates its type, enum, minimum, maximum, or required fields.

## Repository and environment actions

* Change the `api-docs` GitHub default branch from the two-file `master` stub to `main`, then archive or redirect `master`.
* Provide a safe staging workspace, test phone destination, API key secret, and spending guard before enabling nightly billable golden-path checks.
* Decide who owns the webhook event catalog and rate-limit contract so the docs have an authoritative reviewer.

## Removing docs overrides

After backend fixes merge, export a fresh OpenAPI file, run `scripts/improve_v1_openapi.py`, and inspect the diff. Remove an override only when the raw backend export already contains the same correct schema or example and `scripts/validate_v1_api_docs.py` still passes.