feat: add Admin API docs with remote OpenAPI spec

.github/workflows/gh-pages-deploy.yml

@@ -8,6 +8,9 @@ on:
       - main
     types:
       - completed
+  repository_dispatch:
+    types:
+      - remote-spec-updated
 concurrency:
   group: "pages"
   cancel-in-progress: false

.github/workflows/index-main-content.yml

@@ -6,6 +6,7 @@ on:
       - main
     paths:
       - "fern/docs.yml"
+  workflow_dispatch: {}
 
 jobs:
   index-main:

.gitignore

@@ -41,3 +41,6 @@ coverage/
 
 # gha testing
 aa-sdk-docs/
+
+# git worktrees
+.worktrees/

fern/admin-api/overview.mdx

@@ -0,0 +1,37 @@
+---
+title: App Management API Overview
+subtitle: Programmatically create, configure, and manage Alchemy apps.
+slug: reference/admin-api/overview
+---
+
+The App Management API lets you programmatically create, configure, and manage Alchemy apps without using the dashboard. It is designed for automation, compliance, and enterprise workflows.
+
+An App represents a single Alchemy project. You create an app, configure which networks it can access, and optionally restrict usage via allowlists. All changes are applied immediately.
+
+***
+
+## Overview
+
+Use this API to:
+
+* Create and delete apps
+* Update app metadata and configuration
+* Manage network and allowlist settings
+* Retrieve app details
+* Query supported networks
+
+Each request is authenticated using an access key and returns JSON responses.
+
+***
+
+## Authentication
+
+All requests must include an access key with App Management permissions.
+
+To create an access key:
+
+1. Open the Alchemy Dashboard
+2. Go to the [Security Tab](https://dashboard.alchemy.com/settings/security)
+3. Create a new access key
+4. Enable App Management with Read & Write permissions
+

fern/admin-api/quickstart.mdx

@@ -0,0 +1,174 @@
+---
+title: Admin API Quickstart
+subtitle: Create, configure, and manage an app using the Admin API.
+slug: reference/admin-api/quickstart
+---
+
+## Getting Started
+
+This guide walks through creating an app, retrieving its details, updating its configuration, and deleting it.
+
+### Prerequisites
+
+* An access key with App Management **write** permissions
+  * Refer to the overview authentication section for instructions to create an access key
+
+## Set up Environment Variables
+
+```bash
+export ALCHEMY_ADMIN_BASE_URL="https://admin-api.alchemy.com/v1"
+export ALCHEMY_ADMIN_ACCESS_KEY="YOUR_ACCESS_KEY_HERE"
+```
+
+Auth Header
+
+```bash
+export ALCHEMY_ADMIN_AUTH_HEADER="Authorization: Bearer $ALCHEMY_ADMIN_ACCESS_KEY"
+```
+
+## Get chain network options
+
+Use this endpoint to retrieve the list of supported networks and their identifiers. These values are required when configuring network allowlists.
+
+```bash
+curl "$ALCHEMY_ADMIN_BASE_URL/chains" \
+  -H "$ALCHEMY_ADMIN_AUTH_HEADER"
+```
+
+## 1. Create an app
+
+Create a new app by providing a name, description, and supported networks.
+
+```bash
+curl -X POST "$ALCHEMY_ADMIN_BASE_URL/apps" \
+  -H "Content-Type: application/json" \
+  -H "$ALCHEMY_ADMIN_AUTH_HEADER" \
+  -d '{
+    "name": "My App",
+    "description": "Example app",
+    "networkAllowlist": ["ETH_MAINNET", "ARB_MAINNET"],
+    "products": ["node-api", "webhooks"]
+  }'
+```
+
+Example response:
+
+```json
+{
+  "data": {
+    "id": "k5c99fzeegrljz2i",
+    "name": "Test App",
+    "description": "App for full workflow test",
+    "apiKey": "Ow7sB2EbdOgDvAU5P3N0V",
+    "webhookApiKey": "1JIfTRjWbCv4gZS2IWEyTxKHO8eqa2C7",
+    "chainNetworks": [
+      {
+        "name": "Ethereum Mainnet",
+        "id": "ETH_MAINNET",
+        "networkChainId": "1",
+        "rpcUrl": "https://eth-mainnet.g.alchemy.com/v2/Ow7sB2EbdOgDvAU5P3N0V",
+        "wsUrl": "wss://eth-mainnet.g.alchemy.com/v2/Ow7sB2EbdOgDvAU5P3N0V"
+      }
+    ],
+    "products": [],
+    "addressAllowlist": [],
+    "originAllowlist": [],
+    "ipAllowlist": [],
+    "createdAt": "2026-02-05T16:03:03.121+00:00"
+  }
+}
+```
+
+## 2. Get app info
+
+Retrieve details for a single app using its `app_id`.
+
+```bash
+APP_ID="app_123"
+
+curl "$ALCHEMY_ADMIN_BASE_URL/apps/$APP_ID" \
+  -H "$ALCHEMY_ADMIN_AUTH_HEADER"
+```
+
+***
+
+## 3. Update app configuration
+
+App updates are split between **metadata updates** and **configuration updates**.
+
+* Use `PATCH /apps/{app_id}` to update name or description
+* Use configuration sub-endpoints to update networks, allowlists, and IP restrictions
+
+### Update app name and description
+
+```bash
+APP_ID="app_123"
+
+curl -X PATCH "$ALCHEMY_ADMIN_BASE_URL/apps/$APP_ID" \
+  -H "Content-Type: application/json" \
+  -H "$ALCHEMY_ADMIN_AUTH_HEADER" \
+  -d '{
+    "name": "Renamed App",
+    "description": "Updated description"
+  }'
+```
+
+### Update network allowlist (optional)
+
+Update the set of networks this app is allowed to access. Network values must come from the Chains endpoint. The networks provided will replace the current list.
+
+```bash
+APP_ID="app_123"
+
+curl -X PUT "$ALCHEMY_ADMIN_BASE_URL/apps/$APP_ID/networks" \
+  -H "Content-Type: application/json" \
+  -H "$ALCHEMY_ADMIN_AUTH_HEADER" \
+  -d '{
+    "networkAllowlist": ["ETH_MAINNET", "OPT_MAINNET"]
+  }'
+```
+
+### Update origin allowlist (optional)
+
+Update the origin URLs available for this app.
+
+```bash
+APP_ID="app_123"
+
+curl -X PUT "$ALCHEMY_ADMIN_BASE_URL/apps/$APP_ID/origin-allowlist" \
+  -H "Content-Type: application/json" \
+  -H "$ALCHEMY_ADMIN_AUTH_HEADER" \
+  -d '{
+    "originAllowlist": [
+      { "name": "Test Origin", "value": "https://example.com" }
+    ]
+  }'
+```
+
+### Update IP allowlist (optional)
+
+Update the IP addresses that can send requests via this app.
+
+```bash
+APP_ID="app_123"
+
+curl -X PUT "$ALCHEMY_ADMIN_BASE_URL/apps/$APP_ID/ip-allowlist" \
+  -H "Content-Type: application/json" \
+  -H "$ALCHEMY_ADMIN_AUTH_HEADER" \
+  -d '{
+    "ipAllowlist": [
+      { "name": "Test IP", "value": "203.0.113.1" }
+    ]
+  }'
+```
+
+## 4. Delete the app
+
+Permanently delete an app. This action cannot be undone.
+
+```bash
+APP_ID="app_123"
+
+curl -X DELETE "$ALCHEMY_ADMIN_BASE_URL/apps/$APP_ID" \
+  -H "$ALCHEMY_ADMIN_AUTH_HEADER"
+```

fern/apis/admin-api/generators.yaml

@@ -0,0 +1,3 @@
+api:
+  specs:
+    - openapi: ../../api-specs/alchemy/rest/admin-api.json

fern/docs.yml

@@ -198,6 +198,16 @@ navigation:
             path: tutorials/getting-started/dashboard/dashboard-roles.mdx
           - page: Single Sign-On (SSO)
             path: tutorials/getting-started/dashboard/dashboard-sso.mdx
+          - section: Admin API
+            hidden: true
+            contents:
+              - page: Overview
+                path: admin-api/overview.mdx
+              - page: Quickstart
+                path: admin-api/quickstart.mdx
+              - api: Admin API Endpoints
+                api-name: admin-api
+                flattened: true
       - section: Tutorials
         contents:
           - section: Transactions

fern/remote-specs.json

@@ -0,0 +1,6 @@
+[
+  {
+    "name": "admin-api",
+    "url": "https://admin-api.alchemy.com/openapi.yaml"
+  }
+]

scripts/generate-open-api.sh

@@ -69,6 +69,32 @@ for dir in ${input_dir}/*/; do
   fi
 done
 
+# --- Remote specs ---
+# Specs hosted externally that should be included alongside local specs.
+# Config lives in fern/remote-specs.json as an array of { name, url } objects.
+remote_specs_file="fern/remote-specs.json"
+
+if [ -f "$remote_specs_file" ]; then
+  for entry in $(jq -c '.[]' "$remote_specs_file"); do
+    name=$(echo "$entry" | jq -r '.name')
+    url=$(echo "$entry" | jq -r '.url')
+    filename="${output_dir}/alchemy/rest/${name}.json"
+    (
+      if [ "$validate_only" = true ]; then
+        if ! pnpm exec redocly lint "$url" --format json; then
+          exit 1
+        fi
+      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
+fi
+
 # Wait for all background processes and check their exit codes
 for pid in "${pids[@]}"; do
   if ! wait $pid; then