From b6f74f69626293c2e50c792f2fc31f738955e452 Mon Sep 17 00:00:00 2001
From: dslovinsky <dslovinsky@users.noreply.github.com>
Date: Fri, 6 Feb 2026 15:44:27 -0500
Subject: [PATCH] feat: add Admin API documentation with remote OpenAPI spec

Adds a hidden admin-api tab with overview/auth MDX pages and API
reference from the remote spec at admin-api.alchemy.com. Extends
generate-open-api.sh to fetch and bundle the remote YAML spec into
the existing GH Pages pipeline. Adds repository_dispatch trigger
for spec freshness and workflow_dispatch for manual re-indexing.
---
 .github/workflows/gh-pages-deploy.yml    |  3 +++
 .github/workflows/index-main-content.yml |  1 +
 fern/admin-api/authentication.mdx        | 22 ++++++++++++++++++++++
 fern/admin-api/overview.mdx              | 20 ++++++++++++++++++++
 fern/docs.yml                            | 15 +++++++++++++++
 scripts/generate-open-api.sh             | 21 +++++++++++++++++++++
 6 files changed, 82 insertions(+)
 create mode 100644 fern/admin-api/authentication.mdx
 create mode 100644 fern/admin-api/overview.mdx

diff --git a/.github/workflows/gh-pages-deploy.yml b/.github/workflows/gh-pages-deploy.yml
index 653f1e552..92331fdeb 100644
--- a/.github/workflows/gh-pages-deploy.yml
+++ b/.github/workflows/gh-pages-deploy.yml
@@ -8,6 +8,9 @@ on:
       - main
     types:
       - completed
+  repository_dispatch:
+    types:
+      - admin-api-spec-updated
 concurrency:
   group: "pages"
   cancel-in-progress: false
diff --git a/.github/workflows/index-main-content.yml b/.github/workflows/index-main-content.yml
index 325504789..03eb98f8e 100644
--- a/.github/workflows/index-main-content.yml
+++ b/.github/workflows/index-main-content.yml
@@ -6,6 +6,7 @@ on:
       - main
     paths:
       - "fern/docs.yml"
+  workflow_dispatch: {}
 
 jobs:
   index-main:
diff --git a/fern/admin-api/authentication.mdx b/fern/admin-api/authentication.mdx
new file mode 100644
index 000000000..ae1c87a14
--- /dev/null
+++ b/fern/admin-api/authentication.mdx
@@ -0,0 +1,22 @@
+---
+title: Authentication
+subtitle: How to authenticate with the Admin API.
+slug: authentication
+---
+
+All Admin API requests require authentication via a bearer token in the `Authorization` header.
+
+## Getting Your Token
+
+1. Go to the [Alchemy Dashboard](https://dashboard.alchemy.com)
+2. Navigate to your team settings
+3. Generate an Admin API token
+
+## Making Requests
+
+Include the token in the `Authorization` header:
+
+```bash
+curl -X GET "https://admin-api.alchemy.com/v1/apps" \
+  -H "Authorization: Bearer YOUR_TOKEN"
+```
diff --git a/fern/admin-api/overview.mdx b/fern/admin-api/overview.mdx
new file mode 100644
index 000000000..02c7fdc0a
--- /dev/null
+++ b/fern/admin-api/overview.mdx
@@ -0,0 +1,20 @@
+---
+title: Admin API Overview
+subtitle: Programmatically manage your Alchemy apps and configurations.
+slug: overview
+---
+
+The Admin API lets you create and manage Alchemy apps, configure network allowlists, and control access settings programmatically.
+
+## Base URL
+
+```
+https://admin-api.alchemy.com
+```
+
+## Features
+
+- **App Management** — Create, update, and delete apps
+- **Network Configuration** — Manage which blockchain networks an app can access
+- **Access Controls** — Configure IP, origin, and address allowlists
+- **Chain Discovery** — List all available blockchain networks
diff --git a/fern/docs.yml b/fern/docs.yml
index 470c61867..49250093f 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -113,6 +113,9 @@ tabs:
   rollups:
     display-name: Rollups
     slug: rollups
+  admin-api:
+    display-name: Admin API
+    slug: admin-api
   changelog:
     display-name: Changelog
     changelog: ./changelog
@@ -2153,6 +2156,18 @@ navigation:
             api-name: mythos
         slug: mythos
 
+  - tab: admin-api
+    layout:
+      - section: Admin API
+        contents:
+          - page: Overview
+            path: admin-api/overview.mdx
+          - page: Authentication
+            path: admin-api/authentication.mdx
+          - api: Admin API Endpoints
+            api-name: admin-api
+            flattened: true
+
   - tab: changelog
 
 analytics:
diff --git a/scripts/generate-open-api.sh b/scripts/generate-open-api.sh
index e02c4aeac..345ac921d 100755
--- a/scripts/generate-open-api.sh
+++ b/scripts/generate-open-api.sh
@@ -69,6 +69,27 @@ for dir in ${input_dir}/*/; do
   fi
 done
 
+# --- Remote specs ---
+# Specs hosted externally that should be included alongside local specs.
+# Format: "URL|output-name"
+remote_specs=("https://admin-api.alchemy.com/openapi.yaml|admin-api")
+
+for entry in "${remote_specs[@]}"; do
+  IFS='|' read -r url name <<< "$entry"
+  filename="${output_dir}/alchemy/rest/${name}.json"
+  (
+    if [ "$validate_only" = true ]; then
+      echo "Skipping remote spec: ${name} (validate-only mode)"
+    else
+      if ! pnpm exec redocly bundle "$url" --dereferenced --output "$filename" --ext json --remove-unused-components; then
+        exit 1
+      fi
+      jq '{"x-generated-warning": "⚠️ Auto-generated from remote spec. Do not edit."} + .' "$filename" > "$filename.tmp" && mv "$filename.tmp" "$filename" || exit 1
+    fi
+  ) &
+  pids+=($!)
+done
+
 # Wait for all background processes and check their exit codes
 for pid in "${pids[@]}"; do
   if ! wait $pid; then