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

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):

Fetch spec from https://api2.rhombussystems.com/api/openapi/public.json
detect_openapi_changes.py — compare old/new specs, produce change report JSON
Copy new spec to api-reference/openapi.json
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
generate_changelog_entry.py + insert_changelog_entry.py — add changelog entry
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)

Script	Reason
`build-api-navigation.py`	Mintlify handles navigation auto-generation
`generate-endpoint-docs.py`	Mintlify auto-generates endpoint pages
`update-docs-navigation.py`	Navigation is now static + auto-generated
`add-service-level-navigation.py`	Navigation helper, no longer needed
`improve-endpoint-navigation.py`	Navigation helper, no longer needed
`update-llms-files.py`	Mintlify auto-serves llms.txt and llms-full.txt

Keep (8 scripts)

Script	Role
`update-openapi.sh`	Manual spec fetch with validation & backup
`detect_openapi_changes.py`	Change detection for changelog & PR descriptions
`enrich-openapi-tags.py`	Tag quality for auto-grouping
`inject-xmint-decorators.py`	x-mint metadata for SEO
`add-code-samples.py`	Code samples on endpoints
`generate_changelog_entry.py`	Change report to MDX changelog entry
`insert_changelog_entry.py`	Insert entry into changelog.mdx
`check-content-quality.py`	Content 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.

Low Code / No Code

AI & LLMs

2026 04 09 autonomous api docs design

Autonomous API Documentation Pipeline

Context

Design

1. Simplified API Reference Navigation

2. Simplified Nightly Sync Pipeline

3. OpenAPI Spec Enrichment

4. AI & Discovery Files

5. SEO Configuration

Scripts

Retire (7 scripts)

Keep (8 scripts)

Files to Remove

Files to Modify

Guides & Integrations Tabs

​Autonomous API Documentation Pipeline

​Context

​Design

​1. Simplified API Reference Navigation

​2. Simplified Nightly Sync Pipeline

​3. OpenAPI Spec Enrichment

​4. AI & Discovery Files

​5. SEO Configuration

​Scripts

​Retire (7 scripts)

​Keep (8 scripts)

​Files to Remove

​Files to Modify

​Guides & Integrations Tabs

Autonomous API Documentation Pipeline

Context

Design

1. Simplified API Reference Navigation

2. Simplified Nightly Sync Pipeline

3. OpenAPI Spec Enrichment

4. AI & Discovery Files

5. SEO Configuration

Scripts

Retire (7 scripts)

Keep (8 scripts)

Files to Remove

Files to Modify

Guides & Integrations Tabs