From 3b31134e89325a11850d9abd34b7c609fa7e0ec3 Mon Sep 17 00:00:00 2001
From: Rafael Ferreira <36054+rferreira@users.noreply.github.com>
Date: Sun, 30 Aug 2026 09:04:58 -0400
Subject: [PATCH] Correct the DELETE /v2.2/files/{id} contract

Taken from the springdoc output of jackfruit#1560, which changes the endpoint
the spec was written against:

* 403 - the delete now requires an api key. A temporary auth token carries
  ROLE_USER and authenticates as the key that minted it, so it was able to
  erase every result filed under that key
* 404 - the delete reports whether anything was there. S3 answers the delete of
  a missing key as a success, so the old blanket 204 could not tell a caller
  that it had erased nothing. A repeated delete of the same id returns 404 too
* 401 - carries an ErrorResponse body, which it always did: the entry point
  writes one regardless of method

Also drops "hard" from the summary, which described the implementation rather
than the contract.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 src/v22.yaml | 35 ++++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/src/v22.yaml b/src/v22.yaml
index 19b721d..49224e8 100644
--- a/src/v22.yaml
+++ b/src/v22.yaml
@@ -463,8 +463,10 @@ paths:
     delete:
       tags:
         - Files
-      summary: Hard deletes a previously created processing result and its trace
-      description: Permanently deletes the processing result and associated processing trace for the supplied id.
+      summary: Deletes a previously created processing result
+      description: "Permanently deletes the processing result, and its trace, for\
+        \ the supplied processing id. A 404 means there was nothing to delete, which\
+        \ is also what a repeated delete of the same id returns."
       operationId: deleteFile
       parameters:
         - name: id
@@ -475,7 +477,7 @@ paths:
             type: string
       responses:
         "204":
-          description: Processing result and trace successfully deleted
+          description: Processing result deleted
           headers:
             X-Scanii-Request-Id:
               $ref: "#/components/headers/X-Scanii-Request-Id"
@@ -489,6 +491,33 @@ paths:
               $ref: "#/components/headers/X-Scanii-Request-Id"
             X-Scanii-Host-Id:
               $ref: "#/components/headers/X-Scanii-Host-Id"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "403":
+          description: "The credentials are valid but not privileged enough to delete,\
+            \ which is the case for a temporary authentication token"
+          headers:
+            X-Scanii-Request-Id:
+              $ref: "#/components/headers/X-Scanii-Request-Id"
+            X-Scanii-Host-Id:
+              $ref: "#/components/headers/X-Scanii-Host-Id"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "404":
+          description: No processing result exists for the supplied id
+          headers:
+            X-Scanii-Request-Id:
+              $ref: "#/components/headers/X-Scanii-Request-Id"
+            X-Scanii-Host-Id:
+              $ref: "#/components/headers/X-Scanii-Host-Id"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
   /v2.2/auth/tokens/{id}:
     get:
       tags: