Okay, building upon the previous definition for the "Endpoint: Get Listing Details" and drawing directly from the processes and requirements outlined in the provided ACQUA and DIRT sources, particularly regarding the use of listings for reconciliation and the need for metadata capture by operators in the field, here is the definition for the "Endpoint: Update Listing Reconciliation Status".
As established, these specific API structures are derived from the described workflows and data management needs, as the sources do not provide explicit API definitions.
Endpoint: Update Listing Reconciliation Status HTTP Method: PATCH Path: /listings/{listingId}/reconciliation Purpose: To allow camera operators or other authorized staff to update the reconciliation status of specific items within a listing based on their observations in the field and the capture process. This update includes marking items as captured, missing, or noting exceptions, and providing relevant details for each item.
JSON Request Body Structure (application/json):
The request body is an array of objects, where each object represents an update for a specific item listed within the overall listing identified by listingId in the path.
[
  {
    "itemIdentifier": "string", // Unique identifier for the specific item within the listing that is being updated
    "reconciliationStatus": "string", // The new reconciliation status for this item (e.g., "Captured", "Missing", "Exception", "Not Applicable")
    "reconciliationNotes": "string" or null, // Notes added by the operator or auditor regarding the reconciliation outcome for this item
    "capturedFolderId": "string" or null, // REQUIRED if reconciliationStatus is "Captured". The identifier of the folder where this item's images were captured.
    "capturedSequenceNumber": "number" or null // OPTIONAL if reconciliationStatus is "Captured". The starting sequence number within the captured folder for this item.
  }
  // ... potentially more item update objects in the array
]
Field Descriptions (Request Body):
•
itemIdentifier (string): Required. The unique identifier for the specific item as it appears in the listing. This corresponds to the itemIdentifier field in the Get Listing Details response [prev_turn]. It is crucial for the backend to know which listed item is being updated.
•
reconciliationStatus (string): Required. The outcome of the reconciliation process for this specific item. Operators reconcile the listing with captured volumes and record information on missing items. Possible values could include:
◦
"Captured": The item was found and captured.
◦
"Missing": The item was expected per the listing but could not be located at the archive.
◦
"Exception": An issue prevented capture or required a deviation (e.g., item too fragile, restricted access).
◦
"Not Applicable": The item on the original listing is not relevant to the current capture project (derived from the process of paring down initial listings).
•
reconciliationNotes (string or null): Optional. Textual notes added by the operator or auditor to provide context for the reconciliation status (e.g., where a missing item might be, description of an exception).
•
capturedFolderId (string or null): Required if reconciliationStatus is "Captured". A reference to the digital folder (corresponding to the /folders resource) where the images for this specific listed item were captured. This links the listing item to the captured output, which is essential for the "listing, images, and image metadata match" requirement [12, 16, prev_turn].
•
capturedSequenceNumber (number or null): Optional if reconciliationStatus is "Captured". If the captured item corresponds to a specific sequence of images within the folder, this indicates the first image number. Useful for navigation and verification within the folder [prev_turn].
JSON Response Body Structure (application/json):
The response body should confirm the success of the operation and potentially indicate which items were successfully updated and their resulting status.
{
  "success": boolean, // Indicates if the overall update request was processed successfully
  "message": "string", // Optional: A human-readable message about the outcome
  "updatedItems": [ // Optional: An array confirming the items that were updated and their resulting status
    {
      "itemIdentifier": "string", // Identifier of the item that was targeted for update
      "reconciliationStatus": "string", // The final reconciliation status recorded for this item
      "status": "string" // Indicates the status of the update attempt for this specific item (e.g., "Updated", "Failed", "NotFound")
    }
    // ... potentially more item confirmation objects
  ]
}
Field Descriptions (Response Body):
•
success (boolean): Required. true if the backend successfully processed the request and attempted to apply the updates for all items listed in the request body. false if there was a critical error with the request itself (e.g., invalid format).
•
message (string): Optional. Provides additional detail about the outcome, especially in case of partial success or failure.
•
updatedItems (array of objects): Optional. An array detailing the outcome for each item included in the request. This is useful for the client application to confirm which specific items were updated and their final status recorded by the system.
◦
itemIdentifier (string): The identifier of the item from the request.
◦
reconciliationStatus (string): The final reconciliation status recorded in the system for this item. This should match the requested status if the update was successful for this item.
◦
status (string): Indicates the processing status for this specific item within the request (e.g., "Updated" if the status was successfully changed, "Failed" if an error occurred processing this item, "NotFound" if the itemIdentifier didn't exist in the listing).
Real Example Data (application/json):
This example shows an operator updating the status for two items in the listing previously defined (LST-ARCHIVE-001-20241101): Volume 3 is marked as Captured, and Volume 5 (not shown in the GET example but assumed to be on the full listing) is marked as Missing.
Example Request Body:
[
  {
    "itemIdentifier": "ITEM-LST-001-VOL3",
    "reconciliationStatus": "Captured",
    "reconciliationNotes": "Found Volume 3. Captured as folder 004784310.",
    "capturedFolderId": "004784310",
    "capturedSequenceNumber": 1
  },
  {
    "itemIdentifier": "ITEM-LST-001-VOL5",
    "reconciliationStatus": "Missing",
    "reconciliationNotes": "Volume 5 could not be located on the shelves or with archive staff.",
    "capturedFolderId": null,
    "capturedSequenceNumber": null
  }
]
Example Response Body (assuming successful update):
{
  "success": true,
  "message": "Reconciliation status updated for 2 items.",
  "updatedItems": [
    {
      "itemIdentifier": "ITEM-LST-001-VOL3",
      "reconciliationStatus": "Captured",
      "status": "Updated"
    },
    {
      "itemIdentifier": "ITEM-LST-001-VOL5",
      "reconciliationStatus": "Missing",
      "status": "Updated"
    }
  ]
}
This structure allows field operators to communicate the outcome of their physical and digital reconciliation efforts back to the system, fulfilling the standard's requirement for documenting what was captured vs. what was listed.