Docs — Generate from Diff

POST /api/docs/generate

Generate documentation drafts by comparing a base and head ref in your repository. The route is protected and requires a valid session (see validateUserSession()).

Request

{ "repo": "owner/name", // required "base": "main", // required (base ref) "head": "feature-branch", // required (head ref) "ticketId": "TCK-123", // optional (for frontmatter) "prNumber": 57, // optional (for titles/links) "audience": "both", // optional: developer | user | both "openPr": true, // optional: open a PR with generated docs "labels": ["documentation"], // optional: PR labels "triggerWorkflow": true, // optional: trigger CI workflow after PR "workflowIdOrFile": "docs.yml", // optional: GitHub Actions file or ID "workflowRef": "docs/1725680000000" // optional: ref to run workflow on (defaults to PR branch) }

Response

When openPr is false:

{ "summary": "Updated 5 files...", "docs": [ { "path": "content/docs/developer/2025-09-06-api-and-ui-updates.mdx", "content": "..." }, { "path": "content/docs/user/2025-09-06-api-and-ui-updates.mdx", "content": "..." }, { "path": "content/docs/changelog/2025-09-06-api-and-ui-updates.mdx", "content": "..." } ] }

When openPr is true:

{ "summary": "Updated 5 files...", "pr": { "url": "https://github.com/owner/name/pull/58", "number": 58, "branch": "docs/1725680000000" }, "workflow": { "url": "https://github.com/owner/name/actions/workflows/docs.yml", "id": "owner/name/docs.yml@docs/1725680000000" } }

Notes

• Uses GitHub via GithubRepoService internally; other providers can implement RepoService.
• Writes MDX under content/docs/{developer|user|changelog}/ with frontmatter for OMS compatibility.
• Safe to run repeatedly; if PR creation is enabled, labels like documentation help reviewers triage.
• Useful for integrating with the Healing Loop: after PRs merge, this route can be called to keep docs fresh.