From f5e4d4604a7982c44777a69a30c8173b62384926 Mon Sep 17 00:00:00 2001
From: Javier Cicchelli <javier@rock-n-code.com>
Date: Thu, 16 Oct 2025 02:36:41 +0200
Subject: [PATCH] Implemented the POST
 /users/{username}/collection/folders/{folder_id}/releases/{release_id}/instances/{instance_id}
 endpoint for the Open API specification document in the library target.

---
 Sources/DiscogsService/openapi.yaml | 48 ++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/Sources/DiscogsService/openapi.yaml b/Sources/DiscogsService/openapi.yaml
index 06eaf4956..f7381dfef 100644
--- a/Sources/DiscogsService/openapi.yaml
+++ b/Sources/DiscogsService/openapi.yaml
@@ -1377,6 +1377,44 @@ paths:
           $ref: '#/components/responses/NotFound'
         '500':
           $ref: '#/components/responses/InternalError'
+  /users/{username}/collection/folders/{folder_id}/releases/{release_id}/instances/{instance_id}:
+    post:
+      tags:
+        - User Collection
+      summary: Update a rating for a specified release instance in a specified collection folder of a user.
+      description: |
+        Changes the rating on a release and/or move the instance to another folder.
+
+        This endpoint potentially takes 2 `folder_id` parameters: 1) in the URL (which is the folder you are requesting, and is required), and 2) in the request body (representing the folder you want to move the instance to, which is optional)
+
+        This endpoints requires authentication as the collection owner.
+      operationId: postChangeRatingOfRelease
+      parameters:
+        - $ref: '#/components/parameters/Username'
+        - $ref: '#/components/parameters/FolderId'
+        - $ref: '#/components/parameters/ReleaseId'
+        - $ref: '#/components/parameters/InstanceId'
+        - $ref: '#/components/parameters/Rating'
+      security:
+        - ConsumerKeySecret: []
+        - UserToken: []
+        - OAuth: []
+      responses:
+        '204':
+          description: Successfully updated a rating for a specific release instance inside a collection folder of a user.
+          headers:
+            X-Discogs-RateLimit:
+              $ref: '#/components/headers/RateLimit'
+            X-Discogs-RateLimit-Used:
+              $ref: '#/components/headers/RateLimitUsed'
+            X-Discogs-RateLimit-Remaining:
+              $ref: '#/components/headers/RateLimitRemaining'
+        '403':
+          $ref: '#/components/responses/NotAccessable'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalError'
 components:
   headers:
     Link:
@@ -1499,6 +1537,15 @@ components:
         type: string
         format: uri
       example: https://www.some-home.page
+    InstanceId:
+      description: An identifier of a release instance.
+      name: instance_id
+      in: path
+      required: true
+      schema:
+        type: integer
+        minimum: 0
+      example: 3
     Label:
       description: A filter by label.
       name: label
@@ -1575,7 +1622,6 @@ components:
       description: A number (between 1 and 5) for a rating of a release.
       name: rating
       in: query
-      required: true
       schema:
         type: integer
         minimum: 1