Skip to main content

​
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: 
{
  "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)