Document minimal acknowledgements for write-only API keys

e2e/fixtures/openapi.json

@@ -777,11 +777,14 @@
         "x-required-scope": "jobs:write",
         "responses": {
           "201": {
-            "description": "Успех",
+            "description": "Cookie-сессия или ключ с jobs:read получает полный Job. Ключ без jobs:read получает только JobAcknowledgement: id, status, cancel_requested.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Job"
+                  "oneOf": [
+                    { "$ref": "#/components/schemas/Job" },
+                    { "$ref": "#/components/schemas/JobAcknowledgement" }
+                  ]
                 }
               }
             }
@@ -987,7 +990,7 @@
           "Задания"
         ],
         "summary": "Подробности задания",
-        "description": "Полный Job с Attempts и их report/video/artifacts. Исторические попытки не удаляются.",
+        "description": "Полный Job с Attempts и их report/video/artifacts. jobs:read включает эти вложенные метаданные артефактов и видео, но скачивание содержимого, отдельный список артефактов и отдельный видео-манифест требуют artifacts:read. Исторические попытки не удаляются.",
         "security": [
           {
             "BearerAuth": []
@@ -1071,7 +1074,7 @@
           "Задания"
         ],
         "summary": "Запросить отмену задания",
-        "description": "Для queued/running выставляет cancel_requested=true, остановка асинхронна. Для terminal job не меняет состояние. Возвращает текущее Job, не гарантию завершённого cleanup.",
+        "description": "Для queued/running выставляет cancel_requested=true, остановка асинхронна. Для terminal job не меняет состояние. Возвращает Job либо ограниченное подтверждение в зависимости от jobs:read, не гарантию завершённого cleanup.",
         "security": [
           {
             "BearerAuth": []
@@ -1084,11 +1087,14 @@
         "x-required-scope": "jobs:write",
         "responses": {
           "200": {
-            "description": "Успех",
+            "description": "Cookie-сессия или ключ с jobs:read получает полный Job. Ключ без jobs:read получает только JobAcknowledgement: id, status, cancel_requested.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Job"
+                  "oneOf": [
+                    { "$ref": "#/components/schemas/Job" },
+                    { "$ref": "#/components/schemas/JobAcknowledgement" }
+                  ]
                 }
               }
             }
@@ -1178,11 +1184,14 @@
         "x-required-scope": "jobs:write",
         "responses": {
           "200": {
-            "description": "Успех",
+            "description": "Cookie-сессия или ключ с jobs:read получает полный Job. Ключ без jobs:read получает только JobAcknowledgement: id, status, cancel_requested.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Job"
+                  "oneOf": [
+                    { "$ref": "#/components/schemas/Job" },
+                    { "$ref": "#/components/schemas/JobAcknowledgement" }
+                  ]
                 }
               }
             }
@@ -4014,6 +4023,24 @@
         ],
         "description": "Список и dashboard: нет queue_ahead и вложенных attempts. Runs упорядочены по profile_name, id."
       },
+      "JobAcknowledgement": {
+        "type": "object",
+        "description": "Ограниченное подтверждение create/cancel/retry для API-ключа с jobs:write без jobs:read. Не содержит настроек, отчётов, Runs, Attempts и метаданных артефактов.",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid",
+            "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["queued", "running", "completed", "cancelled", "failed"]
+          },
+          "cancel_requested": { "type": "boolean" }
+        },
+        "required": ["id", "status", "cancel_requested"],
+        "additionalProperties": false
+      },
       "Job": {
         "type": "object",
         "properties": {

src/pages/Docs.tsx

@@ -203,6 +203,18 @@ export function DocsPage() {
             дней, максимум 20 активных ключей. Выдавайте только необходимые
             независимые права: запись не включает чтение.
           </p>
+          <p>
+            Ключ с jobs:write без jobs:read получает от создания, отмены и
+            повтора задания только id, status и cancel_requested, без отчётов и
+            настроек. Cookie-сессия или ключ с jobs:read получает полный Job.
+            Независимость прав относится к маршрутам и объёму ответа записи.
+          </p>
+          <p>
+            jobs:read включает метаданные артефактов и видео, уже вложенные в
+            подробности Job. Скачивание содержимого, отдельный список артефактов
+            и отдельный видео-манифест требуют artifacts:read. Ссылка в Job сама
+            по себе не даёт права скачать файл.
+          </p>
           <pre>
             <code>{"Authorization: Bearer $OTCHE_API_KEY"}</code>
           </pre>