> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.rhombus.community/llms.txt
> Use this file to discover all available pages before exploring further.

# 2026 03 18 api docs restructure

# API Documentation Restructure Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Restructure the API Reference tab from a flat 61-tag auto-generated list into a curated hierarchical navigation with overview page, tag descriptions, code samples, and global anchors.

**Architecture:** Six changes to the Mintlify docs site: (1) API Reference overview page, (2) curated hierarchical endpoint groups in docs.json, (3) `api.openapi` root config, (4) tag descriptions in the OpenAPI spec, (5) `x-codeSamples` on key endpoints, (6) global navigation anchors. Changes 1-3 modify docs.json and add one MDX file. Changes 4-5 modify the OpenAPI spec via a post-processing script. Change 6 is a docs.json addition.

**Tech Stack:** Mintlify (MDX, docs.json), OpenAPI 3.0.1 JSON, Python 3.11+ (scripts)

***

### Task 1: Create API Reference overview page

**Files:**

* Create: `api-reference/overview.mdx`

* [ ] **Step 1: Create the overview page**

Create `api-reference/overview.mdx` with authentication guide, base URL, common patterns, and category map.

* [ ] **Step 2: Verify file has valid frontmatter**

Run: `head -5 api-reference/overview.mdx`

***

### Task 2: Add `api.openapi` to docs.json root config

**Files:**

* Modify: `docs.json` (api section, \~line 19)

* [ ] **Step 1: Add openapi to the api config object**

Add `"openapi": "api-reference/openapi.json"` to the existing `"api"` block in docs.json.

***

### Task 3: Build curated hierarchical navigation in docs.json

**Files:**

* Modify: `docs.json` (navigation.tabs\[2] — the API Reference tab)

* [ ] **Step 1: Replace the flat API Reference tab with hierarchical groups**

Replace the current API Reference tab:

```json theme={null}
{
  "tab": "API Reference",
  "groups": [
    { "group": "Endpoints", "openapi": "api-reference/openapi.json" }
  ]
}
```

With curated groups organizing the 61 tags into \~10 categories, each with nested subgroups. The `openapi` key on each group tells Mintlify which spec to use. Individual endpoints are listed as `"METHOD /path"` strings.

Categories:

1. **Overview** — manual page (api-reference/overview)
2. **Cameras & Video** — Camera Webservice, Video Webservice, Doorbell Camera Webservice, Export Webservice, Scene Query Webservice
3. **Audio** — AudioGateway Webservice, AudioPlayback Webservice
4. **Access Control** — Access Control Webservice, Door Webservice, Door Controller Webservice, Badge Reader Webservice, Lockdown Plan Webservice, Guest Management Kiosk Webservice
5. **Sensors & Environment** — Climate Webservice, IoT Integrations Webservice, Sensor Webservice, Button Webservice, BLE Webservice, Proximity Webservice
6. **Events & Alerts** — Event Webservice, Alert Monitoring Webservice, Alarm Monitoring Keypad Webservice, Incident Management Integrations Webservice, Event Search Webservice
7. **Analytics & AI** — Face Recognition Matchmaker Webservice, Face Recognition Person Webservice, Face Recognition Event Webservice, Vehicle Webservice, Search Webservice, Occupancy Webservice, Logistics Webservice
8. **Users & Organization** — User Webservice, User Metadata Webservice, Permission Webservice, Org Webservice, Location Webservice, Customer Webservice, Partner Webservice
9. **Integrations** — Integrations Webservice, Access Control Integrations Webservice, Storage Integrations Webservice, Service Management Integrations Webservice, Webhook Integrations Webservice, Org Integrations Webservice
10. **Platform & Config** — Component Webservice, Policy Webservice, Rules Webservice, Rules Records Webservice, Schedule Webservice, License Webservice, Feature Webservice, Device Config Webservice, Media Device Webservice, Upload Webservice, Help Webservice, Developer Webservice, OAuth Webservice, TvOs Config Webservice, Report Webservice, Elevator Webservice, RapidSOS Webservice

* [ ] **Step 2: Validate docs.json is valid JSON**

Run: `python3 -c "import json; json.load(open('docs.json')); print('Valid JSON')"`

***

### Task 4: Add tag descriptions to OpenAPI spec

**Files:**

* Create: `scripts/enrich-openapi-tags.py`

* Modify: `api-reference/openapi.json` (add top-level `tags` array)

* [ ] **Step 1: Create the enrichment script**

Write a Python script that adds a `tags` array with descriptions for all 61 tags to the OpenAPI spec.

* [ ] **Step 2: Run the script**

Run: `python3 scripts/enrich-openapi-tags.py`

* [ ] **Step 3: Verify tags were added**

Run: `python3 -c "import json; spec=json.load(open('api-reference/openapi.json')); print(f'{len(spec.get(\"tags\",[]))} tags defined')"`

***

### Task 5: Add `x-codeSamples` to key endpoints

**Files:**

* Create: `scripts/add-code-samples.py`

* Modify: `api-reference/openapi.json`

* [ ] **Step 1: Create code samples script**

Write a Python script that adds `x-codeSamples` (cURL + Python) to \~10 high-value endpoints covering the most common use cases.

* [ ] **Step 2: Run the script**

Run: `python3 scripts/add-code-samples.py`

***

### Task 6: Add global navigation anchors

**Files:**

* Modify: `docs.json` (navigation section)

* [ ] **Step 1: Add global anchors**

Add a `global` object with anchors for Changelog and Community to the navigation section.

***

### Task 7: Validate everything

* [ ] **Step 1: Validate docs.json**

Run: `python3 -c "import json; d=json.load(open('docs.json')); print('Valid'); print(f'Tabs: {len(d[\"navigation\"][\"tabs\"])}')"`

* [ ] **Step 2: Validate OpenAPI spec**

Run: `python3 -c "import json; s=json.load(open('api-reference/openapi.json')); print(f'Tags: {len(s.get(\"tags\",[]))}'); print(f'Paths: {len(s[\"paths\"])}')"`

* [ ] **Step 3: Check for broken internal links**

Run: `mint broken-links` (if available)