{
  "openapi": "3.0.0",
  "info": {
    "title": "YGO API: Reject approval image upload",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.ygo.ai",
      "description": "Production and Sandbox (determined by API key)"
    }
  ],
  "paths": {
    "/v2/project/content/rejectApprovalImageUpload": {
      "post": {
        "summary": "Reject approval image upload",
        "description": "Reject one pending photo upload: the upload's feedback item is rejected and the photo is never served. The page's photo list is not touched and the stored file is kept. The upload is checked when it is locked: one whose stored photo record is incomplete and cannot be read answers 400 `INVALID_STATUS_TRANSITION` (contact YGO support), and then an upload that was already decided answers 400 `INVALID_STATUS_TRANSITION`. Works after the hotel approved. The reviewer is recorded as the user's ID, or `project:<project id>` for a project API key.",
        "operationId": "rejectApprovalImageUpload",
        "tags": [
          "Content Enrichment API/Approval Links"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RejectApprovalImageUploadRequest"
              },
              "examples": {
                "reject": {
                  "summary": "Reject one pending upload",
                  "value": {
                    "HotelID": "019d9c2e-0ef8-7458-b0fa-8bed7182eb30",
                    "FeedbackID": "01a0f1c9-3e8a-7c12-b4d5-8e9f0a1b2c3d"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The rejected upload, `Status` `rejected` with its `ReviewedAt`.",
            "headers": {
              "X-Trace-ID": {
                "$ref": "#/components/headers/X-Trace-ID"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RejectApprovalImageUploadResponse"
                },
                "examples": {
                  "reject": {
                    "summary": "The photo is refused and never served",
                    "value": {
                      "Data": {
                        "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": "rejected",
                        "CreatedAt": "2026-10-12T09:14:03.512874Z",
                        "ReviewedAt": "2026-10-12T11:02:39.660142Z"
                      }
                    }
                  }
                }
              }
            }
          },
          "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"
          }
        }
      },
      "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
            }
          }
        }
      },
      "RejectApprovalImageUploadRequest": {
        "type": "object",
        "required": [
          "HotelID",
          "FeedbackID"
        ],
        "description": "The upload to reject and its hotel.",
        "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"
          },
          "FeedbackID": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the upload: its `ID` from listApprovalImageUploads, the id of its feedback item. Required, a valid non-nil UUID.",
            "example": "01a0f1c9-3e8a-7c12-b4d5-8e9f0a1b2c3d"
          }
        }
      },
      "RejectApprovalImageUploadResponse": {
        "type": "object",
        "required": [
          "Data"
        ],
        "description": "Single-object response envelope wrapping the decided upload.",
        "properties": {
          "Data": {
            "$ref": "#/components/schemas/ApprovalImageUpload"
          }
        }
      }
    },
    "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, or the upload cannot be decided (`INVALID_STATUS_TRANSITION`: its stored photo record is incomplete, or it was already decided).",
        "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"
                      }
                    ]
                  }
                }
              },
              "invalidFeedbackID": {
                "summary": "FeedbackID missing or not a valid UUID",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "FeedbackID",
                        "Message": "FeedbackID must be a valid UUID"
                      }
                    ]
                  }
                }
              },
              "uploadUnreadable": {
                "summary": "The upload's stored photo record is incomplete and cannot be read",
                "value": {
                  "Error": {
                    "Code": "INVALID_STATUS_TRANSITION",
                    "Message": "This upload cannot be reviewed: its photo record is incomplete. Please contact YGO support."
                  }
                }
              },
              "alreadyReviewed": {
                "summary": "The upload was already accepted or rejected",
                "value": {
                  "Error": {
                    "Code": "INVALID_STATUS_TRANSITION",
                    "Message": "This photo was already reviewed."
                  }
                }
              }
            }
          }
        }
      },
      "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:write 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:write"
                  }
                }
              },
              "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": {
              "reviewFailed": {
                "summary": "The decision could not be stored",
                "value": {
                  "Error": {
                    "Code": "INTERNAL_ERROR",
                    "Message": "Failed to review the upload"
                  }
                }
              },
              "membershipFailed": {
                "summary": "Hotel membership could not be verified",
                "value": {
                  "Error": {
                    "Code": "INTERNAL_ERROR",
                    "Message": "Failed to verify hotel"
                  }
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Not Found - the project, the hotel or the upload 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"
                  }
                }
              },
              "uploadNotFound": {
                "summary": "No upload of this hotel in this project has this id",
                "value": {
                  "Error": {
                    "Code": "NOT_FOUND",
                    "Message": "Upload 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"
      }
    }
  }
}
