Docs — Generate from Diff
Generate developer, user, and changelog MDX from a base..head diff. Optionally open a docs PR and trigger a workflow build.
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
GithubRepoServiceinternally; other providers can implementRepoService. - Writes MDX under
content/docs/{developer|user|changelog}/with frontmatter for OMS compatibility. - Safe to run repeatedly; if PR creation is enabled, labels like
documentationhelp reviewers triage. - Useful for integrating with the Healing Loop: after PRs merge, this route can be called to keep docs fresh.