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

Export OpenAPI in CI and validate every request/response example against its schema.
Snapshot public v1 operation IDs, methods, paths, auth, and response envelopes.
Assert @ApiExcludeEndpoint() routes are absent from exported OpenAPI.
Exercise Create Agent, Publish Agent, Create Call, list envelopes, and webhook registration in a non-production environment.
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.

Documentation

DASHBOARD BE API DOCS HANDOFF

dashboard-be API documentation handoff

Required backend changes

Tests to add in dashboard-be

Repository and environment actions

Removing docs overrides

​dashboard-be API documentation handoff

​Required backend changes

​Tests to add in dashboard-be

​Repository and environment actions

​Removing docs overrides

dashboard-be API documentation handoff

Required backend changes

Tests to add in dashboard-be

Repository and environment actions

Removing docs overrides