From 5bb53d7f9d49012b3f91326fd456c2131e50ae96 Mon Sep 17 00:00:00 2001
From: Masahiko AMANO <hiko-19@ya.ru>
Date: Mon, 15 Jun 2026 21:17:02 +0300
Subject: [PATCH] docs(project): document review status (filter token +
 bulk/review)

Add File.needs_review, the POST /files/bulk/review path, and the r=1/r=0
filter tokens to the DSL description.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 openapi.yaml | 37 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/openapi.yaml b/openapi.yaml
index bb3a8a1..aa53d06 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -27,9 +27,11 @@ info:
 
     Operators: `(`, `)`, `&` (AND), `|` (OR), `!` (NOT).
     Conditions: `t=<tag_uuid>` (has tag), `t=00000000-0000-0000-0000-000000000000` (untagged),
-    `m=<mime_id>` (exact MIME), `m~<pattern>` (MIME LIKE pattern, e.g. `m~image%`).
+    `m=<mime_id>` (exact MIME), `m~<pattern>` (MIME LIKE pattern, e.g. `m~image%`),
+    `r=1` (needs review / not yet tagged-done), `r=0` (review done).
 
     Example: `{t=uuid1,&,!,t=uuid2}` → has tag1 AND NOT tag2.
+    Example: `{r=1,&,m~image%}` → needs review AND is an image.
   version: 1.0.0
   license:
     name: Proprietary
@@ -642,6 +644,33 @@ paths:
         '204':
           description: Files moved to trash
 
+  /files/bulk/review:
+    post:
+      tags: [Files]
+      summary: Set the review status on one or more files
+      description: >-
+        Marks the given files as needing review (`needs_review=true`) or as
+        review-done (`false`). A single-file toggle is just a one-element list.
+        Files the caller cannot edit are silently skipped.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [file_ids, needs_review]
+              properties:
+                file_ids:
+                  type: array
+                  items:
+                    type: string
+                    format: uuid
+                needs_review:
+                  type: boolean
+      responses:
+        '204':
+          description: Review status updated
+
   /files/bulk/common-tags:
     post:
       tags: [Files, Tags]
@@ -1775,6 +1804,12 @@ components:
           type: boolean
         is_deleted:
           type: boolean
+        needs_review:
+          type: boolean
+          description: >-
+            True until the file's tagging is explicitly marked done. New uploads
+            and imports start true; cleared via POST /files/bulk/review. Filter
+            with `r=1` (needs review) / `r=0` (done).
         created_at:
           type: string
           format: date-time