diff --git a/server/app.js b/server/app.js
index e3f0b87..4f8259b 100644
--- a/server/app.js
+++ b/server/app.js
@@ -102,10 +102,75 @@ function createApp({ skipRateLimits = false } = {}) {
   app.use(express.json({ limit: '64kb' }));
 
   // Health / readiness (no auth, no rate-limit)
+  /**
+   * @openapi
+   * /health:
+   *   get:
+   *     tags: [Health]
+   *     summary: Health check
+   *     description: Returns server uptime and status. No authentication required. Used for liveness probes.
+   *     security: []
+   *     responses:
+   *       '200':
+   *         description: Server is healthy
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 status:
+   *                   type: string
+   *                   example: "ok"
+   *                 uptime:
+   *                   type: number
+   *                   description: Server uptime in seconds
+   *                   example: 3600.5
+   *     x-code-samples:
+   *       - lang: curl
+   *         label: cURL
+   *         source: curl http://localhost:3001/health
+   */
   app.get('/health', (req, res) => {
     res.json({ status: 'ok', uptime: process.uptime() });
   });
 
+  /**
+   * @openapi
+   * /ready:
+   *   get:
+   *     tags: [Health]
+   *     summary: Readiness check
+   *     description: Checks if critical configuration (EMBY_URL) is present. Used by Docker HEALTHCHECK and orchestrators. No authentication required.
+   *     security: []
+   *     responses:
+   *       '200':
+   *         description: Server is ready
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 status:
+   *                   type: string
+   *                   example: "ready"
+   *       '503':
+   *         description: Server not ready
+   *         content:
+   *           application/json:
+   *             schema:
+   *               type: object
+   *               properties:
+   *                 status:
+   *                   type: string
+   *                   example: "not ready"
+   *                 reason:
+   *                   type: string
+   *                   example: "EMBY_URL not configured"
+   *     x-code-samples:
+   *       - lang: curl
+   *         label: cURL
+   *         source: curl http://localhost:3001/ready
+   */
   app.get('/ready', (req, res) => {
     const ready = !!(process.env.EMBY_URL);
     if (ready) {
diff --git a/server/index.js b/server/index.js
index 4a64095..323eb78 100644
--- a/server/index.js
+++ b/server/index.js
@@ -218,10 +218,71 @@ app.use(express.json({ limit: '64kb' })); // prevent oversized JSON payloads
 // Health / readiness endpoints (no auth, no rate-limit)
 // Used by Docker HEALTHCHECK and orchestrators.
 // ---------------------------------------------------------------------------
+/**
+ * @openapi
+ * /health:
+ *   get:
+ *     tags: [Health]
+ *     summary: Health check
+ *     description: Returns server uptime and status. No authentication required. Used for liveness probes.
+ *     security: []
+ *     responses:
+ *       '200':
+ *         description: Server is healthy
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status:
+ *                   type: string
+ *                   example: "ok"
+ *                 uptime:
+ *                   type: number
+ *                   description: Server uptime in seconds
+ *                   example: 3600.5
+ *                 version:
+ *                   type: string
+ *                   description: sofarr version
+ *                   example: "1.6.0"
+ */
 app.get('/health', (req, res) => {
   res.json({ status: 'ok', uptime: process.uptime(), version });
 });
 
+/**
+ * @openapi
+ * /ready:
+ *   get:
+ *     tags: [Health]
+ *     summary: Readiness check
+ *     description: Checks if critical configuration (EMBY_URL) is present. Used by Docker HEALTHCHECK and orchestrators. No authentication required.
+ *     security: []
+ *     responses:
+ *       '200':
+ *         description: Server is ready
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status:
+ *                   type: string
+ *                   example: "ready"
+ *       '503':
+ *         description: Server not ready
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *               properties:
+ *                 status:
+ *                   type: string
+ *                   example: "not ready"
+ *                 reason:
+ *                   type: string
+ *                   example: "EMBY_URL not configured"
+ */
 app.get('/ready', (req, res) => {
   // Confirm critical config is present
   const ready = !!(process.env.EMBY_URL);