Skip to main content

​
Autonomous API Documentation Pipeline

Date: 2026-04-09 Status: Approved Goal: Make the Rhombus API documentation fully autonomous — new endpoints appear automatically with enriched metadata, SEO-optimized, and developer-friendly navigation — with zero manual intervention.

​
Context

The Rhombus Developer Documentation site (built with Mintlify) documents 846+ API endpoints auto-generated from an OpenAPI spec that syncs nightly from production. The current setup manually lists every endpoint in docs.json (making it 107KB+), requiring a build-api-navigation.py script to rebuild navigation on every sync. Several other scripts exist to generate files that Mintlify now handles natively.

​
Design

​
1. Simplified API Reference Navigation

Change: Replace the entire API Reference tab’s 800+ manual endpoint entries in docs.json with Mintlify’s auto-generation. Before (107KB+ docs.json): 
{
  "tab": "API Reference",
  "groups": [
    {
      "group": "Overview",
      "pages": ["api-reference/overview"]
    },
    {
      "group": "Cameras & Video",
      "openapi": "api-reference/openapi.json",
      "pages": [
        {
          "group": "Camera management",
          "pages": [
            "POST /api/camera/calibrateFloorplanProjection",
            "POST /api/camera/createCustomFootageSeekpoints",
            // ... 800+ more entries
          ]
        }
      ]
    }
  ]
}
After (~3KB docs.json): 
{
  "tab": "API Reference",
  "groups": [
    {
      "group": "Overview",
      "pages": ["api-reference/overview"]
    }
  ],
  "openapi": "api-reference/openapi.json"
}
Mintlify auto-generates all endpoint pages, groups them by OpenAPI tags, and builds sidebar navigation. The hand-written api-reference/overview.mdx stays as the landing page.

​
2. Simplified Nightly Sync Pipeline

Change: Remove navigation rebuild step. Add enrichment step. New pipeline (GitHub Action):
  1. Fetch spec from https://api2.rhombussystems.com/api/openapi/public.json
  2. detect_openapi_changes.py — compare old/new specs, produce change report JSON
  3. Copy new spec to api-reference/openapi.json
  4. Run enrichment scripts (in order):
    • enrich-openapi-tags.py — ensure all tags have descriptions (drives Mintlify grouping)
    • inject-xmint-decorators.py — add x-mint metadata for SEO titles/descriptions
    • add-code-samples.py — add x-codeSamples to key endpoints
  5. generate_changelog_entry.py + insert_changelog_entry.py — add changelog entry
  6. Create PR on automated/openapi-sync branch
On merge, Mintlify auto-deploys and regenerates llms.txt, llms-full.txt, skill.md, and sitemap.xml.

​
3. OpenAPI Spec Enrichment

The OpenAPI spec’s quality now directly determines navigation grouping, page titles, descriptions, and SEO. The enrichment scripts become the autonomous “value-add” layer:
  • enrich-openapi-tags.py — Every tag gets a clear description. Tags drive Mintlify’s auto-generated sidebar groups.
  • inject-xmint-decorators.py — Adds x-mint: metadata to endpoints for SEO-optimized titles, descriptions, and keywords.
  • add-code-samples.py — Adds x-codeSamples for richer endpoint pages with multi-language examples.
These run automatically in the nightly pipeline, so every new endpoint gets enriched metadata the same night it appears.

​
4. AI & Discovery Files

Mintlify auto-hosts these at the site root — no repo files or scripts needed:
  • https://api-docs.rhombus.community/llms.txt — page index for AI tools
  • https://api-docs.rhombus.community/llms-full.txt — full docs content for AI
  • https://api-docs.rhombus.community/skill.md — capability summary for AI agents
  • https://api-docs.rhombus.community/sitemap.xml — search engine sitemap
The update-llms-files.py script and local llms.txt/llms-full.txt files are retired.

​
5. SEO Configuration

Add to docs.json: 
"seo": {
  "metatags": {
    "og:site_name": "Rhombus Developer Documentation",
    "og:type": "website",
    "twitter:card": "summary_large_image",
    "robots": "index, follow",
    "language": "en",
    "category": "Technology",
    "keywords": "Rhombus API, security API, camera API, access control API, IoT sensors API, video surveillance, developer documentation"
  },
  "indexing": "all"
}
Hand-written MDX pages should include keywords in frontmatter for page-level SEO. Auto-generated API pages get SEO from the spec’s summary, description, and x-mint: metadata.

​
Scripts

​
Retire (7 scripts)

ScriptReason
build-api-navigation.pyMintlify handles navigation auto-generation
generate-endpoint-docs.pyMintlify auto-generates endpoint pages
update-docs-navigation.pyNavigation is now static + auto-generated
add-service-level-navigation.pyNavigation helper, no longer needed
improve-endpoint-navigation.pyNavigation helper, no longer needed
update-llms-files.pyMintlify auto-serves llms.txt and llms-full.txt

​
Keep (8 scripts)

ScriptRole
update-openapi.shManual spec fetch with validation & backup
detect_openapi_changes.pyChange detection for changelog & PR descriptions
enrich-openapi-tags.pyTag quality for auto-grouping
inject-xmint-decorators.pyx-mint metadata for SEO
add-code-samples.pyCode samples on endpoints
generate_changelog_entry.pyChange report to MDX changelog entry
insert_changelog_entry.pyInsert entry into changelog.mdx
check-content-quality.pyContent quality checks for hand-written pages

​
Files to Remove

  • llms.txt — Mintlify auto-serves this
  • llms-full.txt — Mintlify auto-serves this
  • 7 retired scripts from scripts/

​
Files to Modify

  • docs.json — Replace API Reference tab, add SEO block
  • .github/workflows/sync-openapi.yml — Simplified pipeline with enrichment step
  • CLAUDE.md — Update to reflect new architecture
  • .claude/skills/openapi-sync/SKILL.md — Update to reflect simplified pipeline

​
Guides & Integrations Tabs

No changes in this phase. These will be improved separately in a future iteration.