Browse and clean up the media library through the API

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

public/openapi.yaml

@@ -133,7 +133,7 @@ tags:
   - name: Users
     description: Local user administration
   - name: Media
-    description: Images uploaded for a record to point at
+    description: The media library, and images uploaded for a record to point at
   - name: Roles
     description: Local authorisation model (read-only)
 
@@ -2651,6 +2651,43 @@ paths:
         "422": { $ref: "#/components/responses/ValidationError" }
 
   /v1/media:
+    get:
+      tags: [Media]
+      summary: List the media library
+      description: Every image on the media disk, newest first. Requires `media.view_any`.
+      parameters:
+        - $ref: "#/components/parameters/PerPage"
+        - name: for
+          in: query
+          description: The kind of record it was uploaded for.
+          schema: { $ref: "#/components/schemas/MediaFor" }
+        - name: mime
+          in: query
+          description: "e.g. `image/svg+xml`."
+          schema: { type: string }
+        - name: search
+          in: query
+          description: "Matches the path."
+          schema: { type: string }
+        - name: pending
+          in: query
+          description: "Only those the queue has not processed yet."
+          schema: { type: boolean }
+        - name: failed
+          in: query
+          description: "Only those whose processing failed."
+          schema: { type: boolean }
+        - name: orphans
+          in: query
+          description: "Only those nothing points at \u2014 what `content:prune --media` would delete."
+          schema: { type: boolean }
+      responses:
+        "200":
+          description: Paginated media
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/MediaCollection" }
+        "403": { $ref: "#/components/responses/Forbidden" }
     post:
       tags: [Media]
       summary: Upload an image
@@ -2715,6 +2752,60 @@ paths:
         "403": { $ref: "#/components/responses/Forbidden" }
         "422": { $ref: "#/components/responses/ValidationError" }
 
+  /v1/media/{media}:
+    parameters:
+      - name: media
+        in: path
+        required: true
+        schema: { type: integer }
+    get:
+      tags: [Media]
+      summary: Show an image
+      responses:
+        "200":
+          description: The image, with whether anything uses it
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data: { $ref: "#/components/schemas/Media" }
+        "403": { $ref: "#/components/responses/Forbidden" }
+        "404": { description: Not found }
+    delete:
+      tags: [Media]
+      summary: Delete an image
+      description: |
+        The file, its derived versions and its record. Only when nothing points
+        at it — a page, a logo, an image inside a text — since deleting one in
+        use would put a broken image on the public site. Requires
+        `media.delete`.
+      responses:
+        "204": { description: Deleted }
+        "403": { $ref: "#/components/responses/Forbidden" }
+        "409": { description: The image is in use. }
+
+  /v1/media/{media}/reprocess:
+    post:
+      tags: [Media]
+      summary: Process an image again
+      description: Queues deriving the smaller versions and the placeholder again.
+      parameters:
+        - name: media
+          in: path
+          required: true
+          schema: { type: integer }
+      responses:
+        "202":
+          description: Processing queued
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data: { $ref: "#/components/schemas/Media" }
+        "403": { $ref: "#/components/responses/Forbidden" }
+
   /v1/users:
     get:
       tags: [Users]
@@ -4305,6 +4396,7 @@ components:
     Media:
       type: object
       properties:
+        id: { type: integer }
         path:
           type: string
           description: What a record stores, e.g. as a page's `featured_image`.
@@ -4319,6 +4411,21 @@ components:
           description: |
             Whether the queue has derived the smaller versions and the
             placeholder yet. The image serves either way.
+        error: { type: string, nullable: true, description: "Why processing failed, when it did." }
+        referenced:
+          type: boolean
+          nullable: true
+          description: Whether anything points at it. Sent by the library only, not on upload.
+        created_at: { type: string, format: date-time }
+
+    MediaCollection:
+      type: object
+      properties:
+        data:
+          type: array
+          items: { $ref: "#/components/schemas/Media" }
+        links: { $ref: "#/components/schemas/PaginationLinks" }
+        meta: { $ref: "#/components/schemas/PaginationMeta" }
 
     Category:
       type: object