diff --git a/static/openapi.yaml b/static/openapi.yaml
index 1093137..0670aa8 100644
--- a/static/openapi.yaml
+++ b/static/openapi.yaml
@@ -397,6 +397,138 @@ paths:
         '404':
           description: File not found, is private, or link has expired
 
+  /api/images/random/:
+    get:
+      summary: Get a random image
+      description: |
+        Returns a randomly selected image from the server's image library, resized to the
+        default dimensions. Each request returns a different image.
+
+        **Cache busting:** Add a `?v={timestamp}` query parameter to prevent browsers from
+        caching repeated calls (the server ignores this parameter).
+      tags:
+        - Images
+      parameters:
+        - in: query
+          name: fit
+          schema:
+            type: string
+            enum: [clip, crop, fill, scale]
+            default: scale
+          description: |
+            How to fit the image into the requested dimensions.
+            - `scale` — scale to fit, maintaining aspect ratio (may add letterbox)
+            - `crop` — crop to exact dimensions
+            - `clip` — clip to fit, no upscaling
+            - `fill` — fill exact dimensions, may distort
+        - in: query
+          name: v
+          schema:
+            type: integer
+          description: Cache-busting value (e.g. Unix timestamp). Ignored by the server.
+          example: 1774152070
+      responses:
+        '200':
+          description: Image file (JPEG or PNG)
+          headers:
+            Cache-Control:
+              schema:
+                type: string
+              description: Caching directives (e.g. `public, max-age=3600`)
+            X-Image-Source:
+              schema:
+                type: string
+              description: Relative path of the source image that was served
+          content:
+            image/jpeg:
+              schema:
+                type: string
+                format: binary
+            image/png:
+              schema:
+                type: string
+                format: binary
+        '404':
+          description: |
+            No images available, folder not configured, or invalid parameters.
+
+  /api/images/random/{width}/{height}/:
+    get:
+      summary: Get a random image at specific dimensions
+      description: |
+        Returns a randomly selected image resized to `{width}×{height}` pixels.
+        Minimum 300 px and maximum 4096 px for each dimension.
+
+        **Cache busting:** Add a `?v={timestamp}` query parameter to prevent browsers from
+        caching repeated calls (the server ignores this parameter).
+
+        **Use in Markdown / posts:**
+        ```
+        ![Random image](http://your-domain/api/images/random/300/450/?fit=crop&v=1234567890)
+        ```
+      tags:
+        - Images
+      parameters:
+        - in: path
+          name: width
+          required: true
+          schema:
+            type: integer
+            minimum: 300
+            maximum: 4096
+          description: Target width in pixels
+          example: 300
+        - in: path
+          name: height
+          required: true
+          schema:
+            type: integer
+            minimum: 300
+            maximum: 4096
+          description: Target height in pixels
+          example: 450
+        - in: query
+          name: fit
+          schema:
+            type: string
+            enum: [clip, crop, fill, scale]
+            default: scale
+          description: |
+            How to fit the image into the requested dimensions.
+            - `scale` — scale to fit, maintaining aspect ratio (may add letterbox)
+            - `crop` — crop to exact dimensions
+            - `clip` — clip to fit, no upscaling
+            - `fill` — fill exact dimensions, may distort
+        - in: query
+          name: v
+          schema:
+            type: integer
+          description: Cache-busting value (e.g. Unix timestamp). Ignored by the server.
+          example: 1774152070
+      responses:
+        '200':
+          description: Image file (JPEG or PNG) at the requested dimensions
+          headers:
+            Cache-Control:
+              schema:
+                type: string
+            X-Image-Source:
+              schema:
+                type: string
+              description: Relative path of the source image that was served
+          content:
+            image/jpeg:
+              schema:
+                type: string
+                format: binary
+            image/png:
+              schema:
+                type: string
+                format: binary
+        '404':
+          description: |
+            No images available, folder not configured, invalid dimensions, or invalid fit mode.
+
   /import/images/{image_url}:
     get:
       summary: Import and cache an external image