Refine open API docs

docs/api.md

@@ -1,44 +0,0 @@
-# API Reference
-
-This page contains the interactive API documentation for ntfy. You can try out the API endpoints directly from this page.
-
-## Using the API Documentation
-
-### Server Selection
-
-The API reference includes a server selector dropdown at the top of the page. By default, it's configured to use the **public ntfy.sh server**.
-
-To use your own ntfy instance, edit `docs/api/openapi.yaml` and add your server URL to the `servers` section:
-
-```yaml
-servers:
-  - url: https://ntfy.sh
-    description: Public ntfy server
-  - url: https://your-ntfy-instance.com
-    description: Your custom server
-```
-
-After editing the file, rebuild the docs with `mkdocs build`.
-
-### Authentication
-
-Click the **Authorize** button (lock icon) in the API reference to add your access token. Use the format `Bearer <your_token>` or `Basic <base64_encoded_credentials>`.
-
-### Try It Out
-
-Click **Try it out** on any endpoint to test it directly. Parameters will be empty by default - enter your own values to test.
-
----
-
-<script>
-  // Redirect to standalone Scalar page - use absolute path from root
-  var currentPath = window.location.pathname;
-  // Get base path (everything before /api/)
-  var basePath = currentPath.substring(0, currentPath.indexOf('/api/'));
-  if (basePath === -1 || basePath === '') {
-    basePath = '';
-  }
-  window.location.href = basePath + '/api/scalar.html';
-</script>
-
-If you are not redirected automatically, [click here to view the API Reference](api/scalar.html).

docs/api/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <title>ntfy API Reference</title>
-    <link rel="icon" type="image/svg+xml" href="https://ntfy.sh/static/img/favicon.svg">
+    <link rel="icon" type="image/png" href="/static/img/favicon.png">
     <style>
         * {
             margin: 0;
@@ -70,43 +70,22 @@
             opacity: 1;
         }
 
-        /* Proxy toggle checkbox */
-        .proxy-toggle {
-            display: flex;
-            align-items: center;
-            gap: 8px;
-            margin-left: 20px;
-            padding: 8px 12px;
-            background: rgba(255, 255, 255, 0.15);
-            border-radius: 6px;
-            cursor: pointer;
-            transition: background 0.2s;
-        }
-
-        .proxy-toggle:hover {
-            background: rgba(255, 255, 255, 0.25);
-        }
-
-        .proxy-toggle input[type="checkbox"] {
-            cursor: pointer;
-            width: 16px;
-            height: 16px;
-        }
-
-        .proxy-toggle label {
-            color: white;
-            font-size: 13px;
-            font-weight: 500;
-            cursor: pointer;
-            user-select: none;
-        }
-
         /* Scalar container */
         #scalar-api-reference {
             width: 100%;
             min-height: calc(100vh - 100px);
         }
 
+        /* Hide Share and Generate SDKs menu items */
+        [data-scalar-menu-item="share"],
+        [data-scalar-menu-item="sdk"],
+        .scalar-card-header-actions button[title="Share"],
+        .scalar-card-header-actions button[title="Generate SDK"],
+        button:has(> span:contains("Share")),
+        button:has(> span:contains("SDK")) {
+            display: none !important;
+        }
+
         /* Responsive */
         @media (max-width: 768px) {
             .header-content {
@@ -126,7 +105,7 @@
     <div class="header">
         <div class="header-content">
             <a href="/" style="display: flex; align-items: center; text-decoration: none;">
-                <img src="https://docs.ntfy.sh/static/img/ntfy.png" width="35" height="35" alt="ntfy logo" style="margin-right: 10px;">
+                <img src="/static/img/ntfy.png" width="35" height="35" alt="ntfy logo" style="margin-right: 10px;">
             </a>
             <div class="header-text">
                 <h1>ntfy</h1>
@@ -136,61 +115,16 @@
                 <a href="/">Documentation Home</a>
                 <a href="https://ntfy.sh">ntfy.sh</a>
                 <a href="https://github.com/binwiederhier/ntfy">GitHub</a>
-                <div class="proxy-toggle" title="Enable CORS proxy to make requests through Scalar's proxy server">
-                    <input type="checkbox" id="proxy-toggle-checkbox" checked>
-                    <label for="proxy-toggle-checkbox">Use CORS Proxy</label>
-                </div>
             </div>
         </div>
     </div>
     <!-- Scalar API Reference -->
     <div id="scalar-api-reference"></div>
 
-    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.43.8/dist/browser/style.css" />
+    <link rel="stylesheet" type="text/css" href="./scalar-style.css" />
-    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.43.8/dist/browser/standalone.js"></script>
+    <script src="./scalar-standalone.js"></script>
 
     <script>
-        // Store the Scalar instance globally so we can reinitialize it
-        let scalarInstance = null;
-        
-        // Get proxy preference from localStorage (default: true)
-        function getProxyEnabled() {
-            const stored = localStorage.getItem('scalar-proxy-enabled');
-            return stored === null ? true : stored === 'true';
-        }
-        
-        // Save proxy preference to localStorage
-        function setProxyEnabled(enabled) {
-            localStorage.setItem('scalar-proxy-enabled', enabled.toString());
-        }
-        
-        // Initialize checkbox state
-        function initProxyCheckbox() {
-            const checkbox = document.getElementById('proxy-toggle-checkbox');
-            if (checkbox) {
-                checkbox.checked = getProxyEnabled();
-                
-                // Add change listener
-                checkbox.addEventListener('change', function() {
-                    const enabled = checkbox.checked;
-                    setProxyEnabled(enabled);
-                    // Reinitialize Scalar with new proxy setting
-                    reinitializeScalar();
-                });
-            }
-        }
-        
-        // Reinitialize Scalar with current proxy setting
-        function reinitializeScalar() {
-            const targetElement = document.getElementById('scalar-api-reference');
-            if (targetElement) {
-                // Clear the container
-                targetElement.innerHTML = '<div style="padding: 20px; text-align: center; color: #6b7280;">Reinitializing API Reference...</div>';
-                // Reinitialize
-                setTimeout(initScalar, 100);
-            }
-        }
-        
         function initScalar() {
             const targetElement = document.getElementById('scalar-api-reference');
             
@@ -204,14 +138,25 @@
                 return;
             }
             
-            // Get proxy setting
-            const useProxy = getProxyEnabled();
-            
-            // Build config object
             const config = {
                 url: './openapi.yaml',
                 layout: 'modern',
                 theme: 'default',
+                customCss: `
+                    /* Hide Share and Generate SDKs menu items in dropdowns */
+                    [data-testid="share-button"],
+                    [data-testid="sdk-button"],
+                    .context-menu-item:has(svg[data-icon="share"]),
+                    .context-menu-item:has(svg[data-icon="sdk"]),
+                    .dropdown-item:has(span:contains("Share")),
+                    .dropdown-item:has(span:contains("SDK")),
+                    .scalar-dropdown-item[data-action="share"],
+                    .scalar-dropdown-item[data-action="generate-sdk"],
+                    button[aria-label="Share"],
+                    button[aria-label="Generate SDK"] {
+                        display: none !important;
+                    }
+                `,
                 configuration: {
                     hideSidebar: false,
                     hideSearch: false,
@@ -225,34 +170,21 @@
                 },
             };
             
-            // Only add proxyUrl if enabled
-            if (useProxy) {
-                config.proxyUrl = 'https://proxy.scalar.com';
-            }
-            
             try {
-                const apiRef = Scalar.createApiReference('#scalar-api-reference', config);
+                Scalar.createApiReference('#scalar-api-reference', config);
-                console.log('Scalar initialized successfully', useProxy ? 'with proxy' : 'without proxy');
             } catch (error) {
                 console.error('Error initializing Scalar:', error);
                 targetElement.innerHTML = '<div style="padding: 20px; color: red;">Error loading API reference: ' + error.message + '</div>';
             }
         }
         
-        // Initialize checkbox first
         if (document.readyState === 'loading') {
-            document.addEventListener('DOMContentLoaded', function() {
+            document.addEventListener('DOMContentLoaded', initScalar);
-                initProxyCheckbox();
-                initScalar();
-            });
         } else {
-            initProxyCheckbox();
             setTimeout(initScalar, 100);
         }
         
-        // Also try on window load as fallback
         window.addEventListener('load', function() {
-            initProxyCheckbox();
             setTimeout(initScalar, 200);
         });
     </script>

docs/api/openapi.yaml

@@ -34,34 +34,6 @@ info:
 
     Requests may be rate-limited based on IP address or user tier.
 
-    ## CORS Proxy
-
-    If you are running ntfy locally and accessing this documentation from "localhost" and attempting to make requests to a hosted ntfy server (like ntfy.sh) you may need to enable the "CORS Proxy" checkbox in the top right corner of the page. 
-    This will proxy the requests through the Scalar server to the hosted ntfy server. **BE Aware** this will count against the rate limit of the Scalar Proxy Server. So you may recieve 429 responses from the remote ntfy server.. 
-
-    ## Experimental Endpoints
-
-    The following endpoints are experimental and may be changed or removed in the future. Use at your own risk.
-    
-    - Account Management Endpoints
-    
-    - Admin Endpoints
-
-    ## Add your own ntfy server
-    
-    To add your own ntfy server to the drop down menu, add the following to the `servers` section of "docs/api/openapi.yaml" (or replace the exsiting server with your own https://myntfyserver.editinyaml.com):
-    
-    ```yaml
-
-    servers:
-      - url: https://your-ntfy-instance.com
-      
-        description: Your custom server
-    
-    ```
-    
-    Once you have added your own custom server you will need to run `mkdocs build` to rebuild the documentation.
-
     '
   version: 2.0.0
   contact:
@@ -73,27 +45,32 @@ info:
 servers:
   - url: https://ntfy.sh
     description: Public ntfy server
-- url: https://myntfyserver.editinyaml.com
-  description: My NTFY Server
 tags:
-- name: Publish
+  - name: Publish API
-  description: Publishing messages to topics
+    description: |
-- name: Subscribe
+      Publishing messages to topics.
+      
+      **For detailed examples and usage, please check out the [Publishing documentation](../publish/).**
+  - name: Subscribe API
     description: Subscribing to topics and receiving messages
-- name: Account - **EXPERIMENTAL**
+  - name: Account API (Internal)
-  description: User account management (EXPERIMENTAL) - THESE ENDPOINTS MAY CHANGE, BE REMOVED, OR ADDED TO IN THE FUTURE.
+    description: |
-- name: Admin - **EXPERIMENTAL**
+      User account management.
-  description: Administrative operations (EXPERIMENTAL) - THESE ENDPOINTS MAY CHANGE, BE REMOVED, OR ADDED TO IN THE FUTURE.
+      
+      **These are internal endpoints and may change or be removed in the future.**
+  - name: Admin API (Internal)
+    description: |
+      Administrative operations.
+      
+      **These are internal endpoints and may change or be removed in the future.**
   - name: Matrix
     description: Matrix push gateway
-- name: WebPush 
-  description: Web Push subscriptions 
 paths:
   /{topic}:
     post:
       tags:
-      - Publish
+        - Publish API
-      summary: Publish message to topic
+      summary: Publish message
       description: 'Publishes a message to a topic. The message body can be plain
         text, or you can use various headers to customize the notification.
 
@@ -157,8 +134,8 @@ paths:
           $ref: '#/components/responses/TooManyRequests'
     put:
       tags:
-      - Publish
+        - Publish API
-      summary: Publish message to topic (PUT)
+      summary: Publish message (PUT)
       description: Same as POST but uses PUT method
       operationId: publishMessagePut
       security:
@@ -213,45 +190,10 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '429':
           $ref: '#/components/responses/TooManyRequests'
-    get:
-      tags:
-      - Subscribe
-      summary: Get topic (web UI)
-      description: Returns the web UI for the topic
-      operationId: getTopic
-      parameters:
-      - name: topic
-        in: path
-        required: true
-        description: Topic name
-        schema:
-          type: string
-          pattern: ^[-_A-Za-z0-9]{1,64}$
-      - name: x-unifiedpush
-        in: query
-        description: UnifiedPush discovery
-        schema:
-          type: boolean
-      responses:
-        '200':
-          description: Web UI or UnifiedPush info
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  unifiedpush:
-                    type: object
-                    properties:
-                      version:
-                        type: integer
-            text/html:
-              schema:
-                type: string
   /{topic}/json:
     get:
       tags:
-      - Subscribe
+        - Subscribe API
       summary: Subscribe to JSON stream
       description: 'Subscribes to a topic and returns a streaming HTTP response with
         JSON messages.
@@ -302,8 +244,8 @@ paths:
   /{topic}/sse:
     get:
       tags:
-      - Subscribe
+        - Subscribe API
-      summary: Subscribe to Server-Sent Events stream
+      summary: Subscribe to SSE stream
       description: 'Subscribes to a topic using Server-Sent Events (SSE). This is
         ideal for JavaScript clients using EventSource.
 
@@ -348,7 +290,7 @@ paths:
   /{topic}/raw:
     get:
       tags:
-      - Subscribe
+        - Subscribe API
       summary: Subscribe to raw stream
       description: 'Subscribes to a topic and returns raw text messages, one per line.
 
@@ -390,7 +332,7 @@ paths:
   /{topic}/ws:
     get:
       tags:
-      - Subscribe
+        - Subscribe API
       summary: Subscribe via WebSocket
       description: 'Subscribes to a topic using WebSocket. Messages are sent as JSON
         objects.
@@ -439,7 +381,7 @@ paths:
   /{topic}/publish:
     get:
       tags:
-      - Publish
+        - Publish API
       summary: Publish message (GET alias)
       description: Alias for publishing a message via GET request. Message parameters
         must be passed via headers.
@@ -494,7 +436,7 @@ paths:
   /{topic}/send:
     get:
       tags:
-      - Publish
+        - Publish API
       summary: Publish message (send alias)
       description: Alias for publishing a message via GET request
       operationId: publishMessageSend
@@ -548,7 +490,7 @@ paths:
   /{topic}/trigger:
     get:
       tags:
-      - Publish
+        - Publish API
       summary: Publish message (trigger alias)
       description: Alias for publishing a message via GET request
       operationId: publishMessageTrigger
@@ -602,7 +544,7 @@ paths:
   /{topic}/auth:
     get:
       tags:
-      - Subscribe
+        - Subscribe API
       summary: Check topic authentication
       description: Check if the client is authenticated to access the topic
       operationId: checkTopicAuth
@@ -634,7 +576,7 @@ paths:
   /v1/health:
     get:
       tags:
-      - Admin - **EXPERIMENTAL**
+        - Admin API (Internal)
       summary: Health check
       description: Returns server health status
       operationId: healthCheck
@@ -652,7 +594,7 @@ paths:
   /v1/stats:
     get:
       tags:
-      - Admin - **EXPERIMENTAL**
+        - Admin API (Internal)
       summary: Server statistics
       description: Returns public server statistics
       operationId: getStats
@@ -675,7 +617,7 @@ paths:
   /v1/tiers:
     get:
       tags:
-      - Account - **EXPERIMENTAL**
+        - Account API (Internal)
       summary: List available tiers
       description: Returns list of available subscription tiers with pricing
       operationId: getTiers
@@ -710,7 +652,7 @@ paths:
   /v1/users:
     get:
       tags:
-      - Admin - **EXPERIMENTAL**
+        - Admin API (Internal)
       summary: List users
       description: Returns list of all users (admin only)
       operationId: listUsers
@@ -731,7 +673,7 @@ paths:
           $ref: '#/components/responses/Forbidden'
     post:
       tags:
-      - Admin - **EXPERIMENTAL**
+        - Admin API (Internal)
       summary: Create user
       description: Creates a new user (admin only)
       operationId: createUser
@@ -774,7 +716,7 @@ paths:
           $ref: '#/components/responses/TooManyRequests'
     put:
       tags:
-      - Admin - **EXPERIMENTAL**  
+        - Admin API (Internal)
       summary: Update user
       description: Updates an existing user (admin only)
       operationId: updateUser
@@ -811,7 +753,7 @@ paths:
           $ref: '#/components/responses/NotFound'
     delete:
       tags:
-      - Admin - **EXPERIMENTAL**  
+        - Admin API (Internal)
       summary: Delete user
       description: Deletes a user (admin only)
       operationId: deleteUser
@@ -840,7 +782,7 @@ paths:
   /v1/users/access:
     put:
       tags:
-      - Admin - **EXPERIMENTAL**    
+        - Admin API (Internal)
       summary: Grant user access to topic
       description: Grants a user access to a topic or topic pattern (admin only)
       operationId: grantAccess
@@ -879,7 +821,7 @@ paths:
           $ref: '#/components/responses/TooManyRequests'
     delete:
       tags:
-      - Admin - **EXPERIMENTAL**
+        - Admin API (Internal)
       summary: Reset user access to topic
       description: Resets user access to a topic (admin only)
       operationId: resetAccess
@@ -909,7 +851,7 @@ paths:
   /v1/account:
     post:
       tags:
-      - Account - **EXPERIMENTAL**
+        - Account API (Internal)
       summary: Create account
       description: Creates a new user account
       operationId: createAccount
@@ -944,7 +886,7 @@ paths:
           $ref: '#/components/responses/TooManyRequests'
     get:
       tags:
-      - Account - **EXPERIMENTAL**
+        - Account API (Internal)
       summary: Get account info
       description: Returns information about the authenticated user's account
       operationId: getAccount
@@ -962,7 +904,7 @@ paths:
           $ref: '#/components/responses/Unauthorized'
     delete:
       tags:
-      - Account - **EXPERIMENTAL**
+        - Account API (Internal)
       summary: Delete account
       description: Deletes the authenticated user's account
       operationId: deleteAccount
@@ -991,7 +933,7 @@ paths:
   /v1/account/password:
     post:
       tags:
-      - Account - **EXPERIMENTAL**
+        - Account API (Internal)
       summary: Change password
       description: Changes the authenticated user's password
       operationId: changePassword
@@ -1026,7 +968,7 @@ paths:
   /v1/account/token:
     post:
       tags:
-      - Account - **EXPERIMENTAL**
+        - Account API (Internal)
       summary: Create access token
       description: Creates a new API access token for the authenticated user
       operationId: createToken
@@ -1058,7 +1000,7 @@ paths:
           $ref: '#/components/responses/TooManyRequests'
     patch:
       tags:
-      - Account - **EXPERIMENTAL**
+        - Account API (Internal)
       summary: Update access token
       description: Updates an existing access token
       operationId: updateToken
@@ -1095,7 +1037,7 @@ paths:
           $ref: '#/components/responses/NotFound'
     delete:
       tags:
-      - Account - **EXPERIMENTAL**
+        - Account API (Internal)
       summary: Delete access token
       description: Deletes an access token
       operationId: deleteToken
@@ -1123,7 +1065,7 @@ paths:
   /v1/account/settings:
     patch:
       tags:
-      - Account - **EXPERIMENTAL**  
+        - Account API (Internal)
       summary: Update account settings
       description: Updates the authenticated user's account settings
       operationId: updateSettings
@@ -1158,7 +1100,7 @@ paths:
   /v1/account/subscription:
     post:
       tags:
-      - Account - **EXPERIMENTAL**  
+        - Account API (Internal)
       summary: Add topic subscription
       description: Subscribes to a topic
       operationId: addSubscription
@@ -1187,7 +1129,7 @@ paths:
           $ref: '#/components/responses/TooManyRequests'
     patch:
       tags:
-      - Account - **EXPERIMENTAL**  
+        - Account API (Internal)
       summary: Update topic subscription
       description: Updates a topic subscription
       operationId: updateSubscription
@@ -1216,7 +1158,7 @@ paths:
           $ref: '#/components/responses/NotFound'
     delete:
       tags:
-      - Account - **EXPERIMENTAL**  
+        - Account API (Internal)
       summary: Delete topic subscription
       description: Unsubscribes from a topic
       operationId: deleteSubscription
@@ -1244,7 +1186,7 @@ paths:
   /v1/account/reservation:
     post:
       tags:
-      - Account - **EXPERIMENTAL**    
+        - Account API (Internal)
       summary: Reserve topic
       description: Reserves a topic for exclusive use
       operationId: reserveTopic
@@ -1283,7 +1225,7 @@ paths:
   /v1/account/reservation/{topic}:
     delete:
       tags:
-      - Account - **EXPERIMENTAL**    
+        - Account API (Internal)
       summary: Delete topic reservation
       description: Removes a topic reservation
       operationId: deleteReservation
@@ -1308,7 +1250,7 @@ paths:
   /v1/account/phone:
     put:
       tags:
-      - Account - **EXPERIMENTAL**    
+        - Account API (Internal)
       summary: Add phone number
       description: Adds and verifies a phone number for voice call notifications
       operationId: addPhoneNumber
@@ -1340,7 +1282,7 @@ paths:
           $ref: '#/components/responses/TooManyRequests'
     delete:
       tags:
-      - Account - **EXPERIMENTAL**    
+        - Account API (Internal)
       summary: Delete phone number
       description: Removes a phone number
       operationId: deletePhoneNumber
@@ -1369,7 +1311,7 @@ paths:
   /v1/account/phone/verify:
     put:
       tags:
-      - Account - **EXPERIMENTAL**      
+        - Account API (Internal)
       summary: Request phone verification code
       description: Requests a verification code via SMS
       operationId: verifyPhoneNumber
@@ -1401,33 +1343,10 @@ paths:
           $ref: '#/components/responses/Unauthorized'
         '429':
           $ref: '#/components/responses/TooManyRequests'
-  /v1/account/billing/portal:
-    post:
-      tags:
-      - Account - **EXPERIMENTAL**      
-      summary: Create billing portal session
-      description: Creates a Stripe billing portal session
-      operationId: createBillingPortal
-      security:
-      - BearerAuth: []
-      - BasicAuth: []
-      responses:
-        '200':
-          description: Portal session created
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  redirect_url:
-                    type: string
-                    format: uri
-        '401':
-          $ref: '#/components/responses/Unauthorized'
   /v1/account/billing/subscription:
     post:
       tags:
-      - Account - **EXPERIMENTAL**      
+        - Account API (Internal)
       summary: Create subscription
       description: Creates a paid subscription via Stripe checkout
       operationId: createSubscription
@@ -1462,7 +1381,7 @@ paths:
           $ref: '#/components/responses/Unauthorized'
     put:
       tags:
-      - Account - **EXPERIMENTAL**      
+        - Account API (Internal)
       summary: Update subscription
       description: Modifies an existing subscription
       operationId: updateSubscription
@@ -1489,7 +1408,7 @@ paths:
           $ref: '#/components/responses/Unauthorized'
     delete:
       tags:
-      - Account - **EXPERIMENTAL**      
+        - Account API (Internal)
       summary: Cancel subscription
       description: Cancels the paid subscription
       operationId: cancelSubscription
@@ -1501,119 +1420,6 @@ paths:
           description: Subscription cancelled successfully
         '401':
           $ref: '#/components/responses/Unauthorized'
-  /v1/account/billing/subscription/success/{CHECKOUT_SESSION_ID}:
-    get:
-      tags:
-      - Account - **EXPERIMENTAL**        
-      summary: Subscription checkout success
-      description: Handles successful Stripe checkout redirect
-      operationId: subscriptionCheckoutSuccess
-      security:
-      - BearerAuth: []
-      - BasicAuth: []
-      parameters:
-      - name: CHECKOUT_SESSION_ID
-        in: path
-        required: true
-        description: Stripe checkout session ID
-        schema:
-          type: string
-      responses:
-        '200':
-          description: Checkout processed successfully
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
-  /v1/account/billing/webhook:
-    post:
-      tags:
-      - Account - **EXPERIMENTAL**        
-      summary: Stripe webhook handler
-      description: Handles incoming webhooks from Stripe
-      operationId: stripeWebhook
-      security: []
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-      responses:
-        '200':
-          description: Webhook processed successfully
-  /v1/webpush:
-    post:
-      tags:
-      - WebPush
-      summary: Register Web Push subscription
-      description: Registers a Web Push subscription for browser notifications
-      operationId: registerWebPush
-      security:
-      - BearerAuth: []
-      - BasicAuth: []
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-              - endpoint
-              - auth
-              - p256dh
-              - topics
-              properties:
-                endpoint:
-                  type: string
-                  format: uri
-                  description: Push service endpoint URL
-                auth:
-                  type: string
-                  description: Authentication secret
-                p256dh:
-                  type: string
-                  description: P-256 ECDH key
-                topics:
-                  type: array
-                  items:
-                    type: string
-                  description: List of topics to subscribe to
-      responses:
-        '200':
-          description: Subscription registered successfully
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '429':
-          $ref: '#/components/responses/TooManyRequests'
-    delete:
-      tags:
-      - WebPush
-      summary: Delete Web Push subscription
-      description: Removes a Web Push subscription
-      operationId: deleteWebPush
-      security:
-      - BearerAuth: []
-      - BasicAuth: []
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-              - endpoint
-              properties:
-                endpoint:
-                  type: string
-                  format: uri
-      responses:
-        '200':
-          description: Subscription deleted successfully
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-        '404':
-          $ref: '#/components/responses/NotFound'
   /_matrix/push/v1/notify:
     get:
       tags:
@@ -1670,60 +1476,10 @@ paths:
                     items:
                       type: string
                     description: List of rejected pushkeys
-  /file/{messageId}:
-    get:
-      tags:
-      - Publish
-      summary: Download attachment
-      description: Downloads a file attachment by message ID
-      operationId: downloadAttachment
-      security: []
-      parameters:
-      - name: messageId
-        in: path
-        required: true
-        description: Message ID
-        schema:
-          type: string
-          pattern: ^[-_A-Za-z0-9]{12}$
-      responses:
-        '200':
-          description: File content
-          content:
-            application/octet-stream:
-              schema:
-                type: string
-                format: binary
-          image/*:
-            schema:
-              type: string
-              format: binary
-        '404':
-          $ref: '#/components/responses/NotFound'
-    head:
-      tags:
-      - Publish
-      summary: Check attachment exists
-      description: Checks if an attachment exists without downloading it
-      operationId: headAttachment
-      security: []
-      parameters:
-      - name: messageId
-        in: path
-        required: true
-        description: Message ID
-        schema:
-          type: string
-          pattern: ^[-_A-Za-z0-9]{12}$
-      responses:
-        '200':
-          description: Attachment exists
-        '404':
-          $ref: '#/components/responses/NotFound'
   /metrics:
     get:
       tags:
-      - Admin - **EXPERIMENTAL**
+        - Admin API (Internal)
       summary: Prometheus metrics
       description: Returns Prometheus-compatible metrics
       operationId: getMetrics
@@ -1735,61 +1491,21 @@ paths:
             text/plain:
               schema:
                 type: string
-  /:
+  /v1/config:
     get:
       tags:
-      - Subscribe
+        - Admin API (Internal)
-      summary: Web app root
+      summary: Server configuration
-      description: Returns the web application
+      description: Returns the server configuration as JSON. Used by the web app to determine enabled features.
-      operationId: getRoot
+      operationId: getServerConfig
       security: [ ]
       responses:
         '200':
-          description: Web app HTML
+          description: Server configuration
           content:
-            text/html:
+            application/json:
               schema:
-                type: string
+                $ref: '#/components/schemas/ServerConfig'
-    head:
-      tags:
-      - Subscribe
-      summary: Server check
-      description: Returns empty response to verify server is running
-      operationId: headRoot
-      security: []
-      responses:
-        '200':
-          description: Server is running
-  /config.js:
-    get:
-      tags:
-      - Subscribe
-      summary: Web app configuration
-      description: Returns JavaScript configuration for the web app
-      operationId: getConfig
-      security: []
-      responses:
-        '200':
-          description: Configuration JavaScript
-          content:
-            text/javascript:
-              schema:
-                type: string
-  /manifest.webmanifest:
-    get:
-      tags:
-      - Subscribe
-      summary: Web app manifest
-      description: Returns the Progressive Web App manifest
-      operationId: getManifest
-      security: []
-      responses:
-        '200':
-          description: Web app manifest
-          content:
-            application/manifest+json:
-              schema:
-                type: object
 components:
   securitySchemes:
     BasicAuth:
@@ -2112,6 +1828,54 @@ components:
             error_code: 42901
             message: Rate limit exceeded. Please try again later.
   schemas:
+    ServerConfig:
+      type: object
+      description: Server configuration
+      properties:
+        base_url:
+          type: string
+          description: Base URL of the server (empty means use window.location.origin)
+        app_root:
+          type: string
+          description: Web app root path
+        enable_login:
+          type: boolean
+          description: Whether login is enabled
+        require_login:
+          type: boolean
+          description: Whether login is required to use the server
+        enable_signup:
+          type: boolean
+          description: Whether user signup is enabled
+        enable_payments:
+          type: boolean
+          description: Whether Stripe payments are enabled
+        enable_calls:
+          type: boolean
+          description: Whether phone calls are enabled (Twilio)
+        enable_emails:
+          type: boolean
+          description: Whether email forwarding is enabled
+        enable_reservations:
+          type: boolean
+          description: Whether topic reservations are enabled
+        enable_web_push:
+          type: boolean
+          description: Whether Web Push notifications are enabled
+        billing_contact:
+          type: string
+          description: Billing contact email
+        web_push_public_key:
+          type: string
+          description: VAPID public key for Web Push
+        disallowed_topics:
+          type: array
+          items:
+            type: string
+          description: List of disallowed topic names
+        config_hash:
+          type: string
+          description: Hash of the current configuration (for change detection)
     Message:
       type: object
       description: A notification message

mkdocs.yml

@@ -74,7 +74,6 @@ plugins:
   - search
   - minify:
       minify_html: true
-  - swagger-ui-tag
 
 nav:
   - "Getting started": index.md
@@ -90,9 +89,9 @@ nav:
       - "Installation": install.md
       - "Configuration": config.md
   - "Other things":
-      - "API Reference": api.md
       - "FAQs": faq.md
       - "Examples": examples.md
+      - "API Reference": /api/
       - "Integrations + projects": integrations.md
       - "Release notes": releases.md
       - "Emojis 🥳 🎉": emojis.md