DocuGardenerDocs

API Reference

The DocuGardener analysis engine exposes a REST API on port 8000. All endpoints return JSON. Interactive docs are available at /docs (Swagger UI) and /redoc when running in development mode.

Authentication: Most endpoints authenticate via tenant context derived from the GitHub App installation. Plugin endpoints require a X-Plugin-Key header. Webhook endpoints use HMAC-SHA256 signature verification.

Health

GET/health
Returns service health including database connectivity and component status. Used by Docker health checks.
{ "status": "healthy", "database": "ok", "redis": "ok" }
GET/ready
Readiness probe. Returns 200 when the service is ready to handle requests, 503 during startup.

Webhooks

POST/webhooks/github

Receives GitHub App webhook events. Validates X-Hub-Signature-256 header using HMAC-SHA256 against GITHUB_WEBHOOK_SECRET. Returns 200 immediately and enqueues analysis asynchronously.

Handled events: pull_request (actions: opened, synchronize)

Returns 429 if per-installation rate limit exceeded (20 req/min).

Triage Inbox

GET/
Returns all open drift alerts for the tenant. Excludes QUOTA_EXCEEDED jobs. Sorted by createdAt DESC.
GET/{job_id}
Returns the full analysis result for a single job including drift reasons, suggested fixes, policy violations, and auto-fix status.
PATCH/{job_id}

Update the triage status of a job. Used to dismiss, resolve, or mark as reviewed.

{
  "triageStatus": "DISMISSED",  // DISMISSED | RESOLVED | REVIEW_REQUIRED
  "dismissReason": "Not applicable to this PR"
}

Agent Rules

GET/{repo_id}/rules
Returns the compiled agent rules for a repository.
POST/{repo_id}/rules/generate
Generates suggested agent rules for a repository by analysing its existing documentation structure using the LLM.
POST/{repo_id}/rules/preview
Dry-runs a set of agent rules against a sample prompt and returns the rendered output without saving.

Prompts

GET/prompts/
Returns the tenant's active prompt customisations. Requires PRO+.
POST/prompts/
Saves a prompt customisation for the tenant. Requires PRO+.
POST/prompts/reset
Resets all prompt customisations to defaults for the tenant. Requires PRO+.

Billing (internal)

GET/billing/profile
Returns the tenant's current plan, granted features, and deployment identity. Proxied by the Next.js API.