{
  "openapi": "3.0.0",
  "info": {
    "title": "YGO API: List approval image uploads",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.ygo.ai",
      "description": "Production and Sandbox (determined by API key)"
    }
  ],
  "paths": {
    "/v2/project/content/listApprovalImageUploads": {
      "post": {
        "summary": "List approval image uploads",
        "description": "List one member hotel's photo uploads in every state but withdrawn (an upload the hotel undid), newest first, at most 200. Each upload carries its photo and its `ID`, the id of its feedback item, so a client can show the photo beside the item that `listHotelFeedback` returns. Pass the `ID` of a `pending` upload as `FeedbackID` to acceptApprovalImageUpload or rejectApprovalImageUpload.",
        "operationId": "listApprovalImageUploads",
        "tags": [
          "Content Enrichment API/Approval Links"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListApprovalImageUploadsRequest"
              },
              "examples": {
                "listUploads": {
                  "summary": "List one hotel's photo uploads",
                  "value": {
                    "HotelID": "019d9c2e-0ef8-7458-b0fa-8bed7182eb30"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The hotel's uploads, newest first. `Uploads` is always an array, empty when there are none.",
            "headers": {
              "X-Trace-ID": {
                "$ref": "#/components/headers/X-Trace-ID"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListApprovalImageUploadsResponse"
                },
                "examples": {
                  "listUploads": {
                    "summary": "One pending and one accepted upload",
                    "value": {
                      "Data": {
                        "Uploads": [
                          {
                            "ID": "01a0f1c9-3e8a-7c12-b4d5-8e9f0a1b2c3d",
                            "HotelID": "019d9c2e-0ef8-7458-b0fa-8bed7182eb30",
                            "URL": "https://ucarecdn.com/8f14e45f-ceea-467a-9575-7d3b1c2a9e10/",
                            "Width": 1600,
                            "Height": 1200,
                            "FileSize": 0,
                            "Format": "",
                            "Status": "pending",
                            "CreatedAt": "2026-10-12T09:14:03.512874Z"
                          },
                          {
                            "ID": "01a0e7b4-52c1-7f6d-8a3e-0b9c4d2e1f70",
                            "HotelID": "019d9c2e-0ef8-7458-b0fa-8bed7182eb30",
                            "URL": "https://ucarecdn.com/3c59dc04-8e4a-4f7c-9c1d-6a2b5e8f0d31/",
                            "Width": 1600,
                            "Height": 1200,
                            "FileSize": 0,
                            "Format": "",
                            "Status": "accepted",
                            "CreatedAt": "2026-10-11T16:40:12.305918Z",
                            "ReviewedAt": "2026-10-11T17:05:44.118203Z"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Project-ID"
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ApprovalImageUpload": {
        "type": "object",
        "required": [
          "ID",
          "HotelID",
          "URL",
          "Width",
          "Height",
          "FileSize",
          "Format",
          "Status",
          "CreatedAt"
        ],
        "description": "One photo a hotel contact uploaded on the approval page.",
        "properties": {
          "ID": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the upload: the id of its feedback item. Pass it as `FeedbackID` to acceptApprovalImageUpload or rejectApprovalImageUpload.",
            "example": "01a0f1c9-3e8a-7c12-b4d5-8e9f0a1b2c3d"
          },
          "HotelID": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the hotel the photo was uploaded for.",
            "example": "019d9c2e-0ef8-7458-b0fa-8bed7182eb30"
          },
          "URL": {
            "type": "string",
            "format": "uri",
            "description": "Where the photo is served from.",
            "example": "https://ucarecdn.com/8f14e45f-ceea-467a-9575-7d3b1c2a9e10/"
          },
          "Width": {
            "type": "integer",
            "description": "Width of the photo in pixels: for a photo recorded as uploaded (uploadImage names its Uploadcare URL), the width the hotel's browser reported (YGO-4317), unverified; 0 when none was sent. Uploads recorded before YGO-4286 (multipart) carry the stored photo's width.",
            "example": 1600
          },
          "Height": {
            "type": "integer",
            "description": "Height of the photo in pixels: for a photo recorded as uploaded (uploadImage names its Uploadcare URL), the height the hotel's browser reported (YGO-4317), unverified; 0 when none was sent. Uploads recorded before YGO-4286 (multipart) carry the stored photo's height.",
            "example": 1200
          },
          "FileSize": {
            "type": "integer",
            "description": "Size of the photo's file in bytes: 0 for a photo recorded as uploaded (uploadImage names its Uploadcare URL), whose size is not read. Uploads recorded before YGO-4286 (multipart) carry the stored photo's file size.",
            "example": 0
          },
          "Format": {
            "type": "string",
            "enum": [
              "jpeg",
              "png",
              ""
            ],
            "description": "File type of the photo: empty for a photo recorded as uploaded (uploadImage names its Uploadcare URL), whose type is not read. Uploads recorded before YGO-4286 (multipart) carry `jpeg` or `png`.",
            "example": ""
          },
          "Status": {
            "type": "string",
            "enum": [
              "pending",
              "accepted",
              "rejected"
            ],
            "description": "State of the upload: `pending` until a reviewer decides, `accepted` once it is on the page's photo list, `rejected` when it was refused and is never served.",
            "example": "pending"
          },
          "CreatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the photo was uploaded (RFC3339).",
            "example": "2026-10-12T09:14:03.512874Z"
          },
          "ReviewedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When a reviewer accepted or rejected the upload (RFC3339). Omitted while it is pending.",
            "example": "2026-10-12T11:02:39.660142Z"
          }
        }
      },
      "ApprovalImageUploadList": {
        "type": "object",
        "required": [
          "Uploads"
        ],
        "description": "The hotel's photo uploads.",
        "properties": {
          "Uploads": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApprovalImageUpload"
            },
            "description": "The uploads in every state but withdrawn, newest first, at most 200. Always present; empty when the hotel has none."
          }
        }
      },
      "ErrorDetail": {
        "type": "object",
        "required": [
          "Code",
          "Message"
        ],
        "description": "Error detail containing a machine-readable code and human-readable message.",
        "properties": {
          "Code": {
            "type": "string",
            "description": "Machine-readable error code for programmatic handling.",
            "example": "VALIDATION_ERROR"
          },
          "Message": {
            "type": "string",
            "description": "Human-readable error message.",
            "example": "Validation failed"
          },
          "Fields": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FieldError"
            },
            "description": "Field-level validation errors. Only present for VALIDATION_ERROR responses."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "Error"
        ],
        "description": "Standard v2 error response wrapper.",
        "properties": {
          "Error": {
            "$ref": "#/components/schemas/ErrorDetail"
          }
        }
      },
      "FieldError": {
        "type": "object",
        "required": [
          "Field",
          "Message"
        ],
        "description": "A single field-level validation error.",
        "properties": {
          "Field": {
            "type": "string",
            "description": "Path of the field that failed validation, as the request sends it: a dotted path for a field inside a nested request object, a bare name for a top-level one.",
            "example": "Name"
          },
          "Message": {
            "type": "string",
            "description": "Human-readable validation error message for this field.",
            "example": "Name is required"
          },
          "Code": {
            "type": "string",
            "enum": [
              "REQUIRED",
              "TOO_LONG",
              "TOO_SHORT",
              "OUT_OF_RANGE",
              "TOO_MANY",
              "INVALID_FORMAT",
              "NOT_ALLOWED",
              "CONFLICT",
              "INVALID_ENCODING",
              "INSECURE_SCHEME",
              "UNSAFE_CONTENT",
              "REQUIRED_WHEN_ENABLED"
            ],
            "description": "Machine-readable reason the field failed validation. Optional; clients should fall back to Message when it is absent or unrecognized.",
            "example": "TOO_LONG"
          },
          "Params": {
            "type": "object",
            "additionalProperties": true,
            "description": "Machine-readable values the message is built from, such as limits or allowed values. Keys are PascalCase; which keys are present depends on Code. Optional.",
            "example": {
              "Max": 200
            }
          }
        }
      },
      "ListApprovalImageUploadsRequest": {
        "type": "object",
        "required": [
          "HotelID"
        ],
        "description": "The hotel whose uploads to list.",
        "properties": {
          "HotelID": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the hotel. Required, a valid non-nil UUID, and a live member of the calling project.",
            "example": "019d9c2e-0ef8-7458-b0fa-8bed7182eb30"
          }
        }
      },
      "ListApprovalImageUploadsResponse": {
        "type": "object",
        "required": [
          "Data"
        ],
        "description": "Single-object response envelope wrapping the hotel's uploads.",
        "properties": {
          "Data": {
            "$ref": "#/components/schemas/ApprovalImageUploadList"
          }
        }
      }
    },
    "parameters": {
      "X-Project-ID": {
        "name": "X-Project-ID",
        "in": "header",
        "required": true,
        "description": "Project UUID. Required for all project-scoped endpoints.",
        "example": "$YGO_PROJECT_ID",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "headers": {
      "Retry-After": {
        "description": "Number of seconds to wait before retrying the request. Present on 429 responses.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "example": 39
        }
      },
      "X-Trace-ID": {
        "description": "Request trace ID for debugging (OpenTelemetry). Include this ID when contacting support about specific requests.",
        "schema": {
          "type": "string",
          "example": "abc123def456ghi789"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad Request - the request body or the X-Project-ID header failed validation.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "missingProjectHeader": {
                "summary": "X-Project-ID header missing",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "X-Project-ID header is required"
                  }
                }
              },
              "invalidBody": {
                "summary": "Malformed request body",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Invalid request body"
                  }
                }
              },
              "invalidHotelID": {
                "summary": "HotelID missing or not a valid UUID",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "HotelID",
                        "Message": "HotelID must be a valid UUID"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden - the caller is authenticated but may not act on this project. Also returned with code INSUFFICIENT_SCOPE when the API key does not carry the content.authoring:read permission this endpoint requires.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "insufficientScope": {
                "summary": "Missing required scope",
                "value": {
                  "Error": {
                    "Code": "INSUFFICIENT_SCOPE",
                    "Message": "token lacks scope content.authoring:read"
                  }
                }
              },
              "accessDenied": {
                "summary": "The user token has no editor access to the project",
                "value": {
                  "Error": {
                    "Code": "FORBIDDEN",
                    "Message": "Access denied to project"
                  }
                }
              },
              "noProjectScope": {
                "summary": "The request carries no project scope",
                "value": {
                  "Error": {
                    "Code": "FORBIDDEN",
                    "Message": "Project access required"
                  }
                }
              }
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal Server Error - Unexpected server error. Include the X-Trace-ID header value when contacting support.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "listFailed": {
                "summary": "The uploads could not be read",
                "value": {
                  "Error": {
                    "Code": "INTERNAL_ERROR",
                    "Message": "Failed to list uploads"
                  }
                }
              },
              "membershipFailed": {
                "summary": "Hotel membership could not be verified",
                "value": {
                  "Error": {
                    "Code": "INTERNAL_ERROR",
                    "Message": "Failed to verify hotel"
                  }
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Not Found - the project or the hotel is not reachable for this caller.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "projectNotFound": {
                "summary": "The project does not exist or was deleted (user tokens)",
                "value": {
                  "Error": {
                    "Code": "NOT_FOUND",
                    "Message": "Project not found"
                  }
                }
              },
              "hotelNotFound": {
                "summary": "The hotel is not a live member of the project",
                "value": {
                  "Error": {
                    "Code": "NOT_FOUND",
                    "Message": "Hotel not found"
                  }
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too Many Requests. The response includes a `Retry-After` header with the number of seconds to wait before retrying.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          },
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "rateLimited": {
                "summary": "Limit exceeded",
                "value": {
                  "Error": {
                    "Code": "RATE_LIMIT_EXCEEDED",
                    "Message": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header."
                  }
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized - Invalid or missing bearer token.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "missingToken": {
                "summary": "No Authorization header",
                "value": {
                  "Error": {
                    "Code": "UNAUTHORIZED",
                    "Message": "Missing bearer token"
                  }
                }
              },
              "invalidToken": {
                "summary": "The bearer token is not valid",
                "value": {
                  "Error": {
                    "Code": "UNAUTHORIZED",
                    "Message": "Invalid bearer token"
                  }
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Project-scoped API key"
      }
    }
  }
}
