{
  "openapi": "3.0.0",
  "info": {
    "title": "YGO API: Accept 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/acceptApprovalImageUpload": {
      "post": {
        "summary": "Accept approval image upload",
        "description": "Accept one pending photo upload: the photo becomes an image of the hotel and is appended to the approval page's photo list, and the upload's feedback item is resolved. The page serves it from the next `get`. When the hotel has no list yet, the photo is appended to the photos the page serves now, which then become its list.\n\nAccept checks, in order: hotel photo uploads are enabled for the project (400 `INVALID_STATUS_TRANSITION` otherwise, because an accepted photo would never be served; ask YGO support to enable them); hotel photo uploads are not switched off for the project (400 `INVALID_STATUS_TRANSITION` otherwise; contact YGO support); and the page's photo list can be read (503). The write then locks the upload and refuses one whose stored photo record is incomplete and cannot be read (400 `INVALID_STATUS_TRANSITION`; contact YGO support), an upload that is no longer pending (400 `INVALID_STATUS_TRANSITION`), a photo whose URL is not an Uploadcare CDN file URL `https://ucarecdn.com/<uuid>/` (400 `VALIDATION_ERROR` on `FeedbackID`; uploadImage records no other form), a list that changed since it was read (400 `INVALID_STATUS_TRANSITION`), a list that would hold more than 10 photos (400 `INVALID_STATUS_TRANSITION`) and a list that holds a photo that can no longer be listed (400 `VALIDATION_ERROR` on `FeedbackID`, field code `CONFLICT`). Works after the hotel approved. The reviewer is recorded as the user's ID, or `project:<project id>` for a project API key.",
        "operationId": "acceptApprovalImageUpload",
        "tags": [
          "Content Enrichment API/Approval Links"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AcceptApprovalImageUploadRequest"
              },
              "examples": {
                "accept": {
                  "summary": "Accept one pending upload",
                  "value": {
                    "HotelID": "019d9c2e-0ef8-7458-b0fa-8bed7182eb30",
                    "FeedbackID": "01a0f1c9-3e8a-7c12-b4d5-8e9f0a1b2c3d"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The accepted upload, `Status` `accepted` with its `ReviewedAt`.",
            "headers": {
              "X-Trace-ID": {
                "$ref": "#/components/headers/X-Trace-ID"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AcceptApprovalImageUploadResponse"
                },
                "examples": {
                  "accept": {
                    "summary": "The photo is on the page's list",
                    "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": "accepted",
                        "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"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Project-ID"
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "AcceptApprovalImageUploadRequest": {
        "type": "object",
        "required": [
          "HotelID",
          "FeedbackID"
        ],
        "description": "The upload to accept 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"
          }
        }
      },
      "AcceptApprovalImageUploadResponse": {
        "type": "object",
        "required": [
          "Data"
        ],
        "description": "Single-object response envelope wrapping the decided upload.",
        "properties": {
          "Data": {
            "$ref": "#/components/schemas/ApprovalImageUpload"
          }
        }
      },
      "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
            }
          }
        }
      }
    },
    "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, the upload cannot be accepted as stored (`VALIDATION_ERROR` on `FeedbackID`), or the upload or the project is in a state that refuses the accept (`INVALID_STATUS_TRANSITION`: hotel photo uploads not enabled or switched off for the project, an upload whose stored photo record is incomplete, an upload already decided, or a photo list that changed or is full).",
        "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"
                      }
                    ]
                  }
                }
              },
              "uploadsNotEnabled": {
                "summary": "Hotel photo uploads are not enabled for the project",
                "value": {
                  "Error": {
                    "Code": "INVALID_STATUS_TRANSITION",
                    "Message": "Accepted photos cannot be shown for this project yet. Please ask YGO support to enable hotel photo uploads for it."
                  }
                }
              },
              "uploadsSwitchedOff": {
                "summary": "Hotel photo uploads are switched off for the project",
                "value": {
                  "Error": {
                    "Code": "INVALID_STATUS_TRANSITION",
                    "Message": "Accepted photos are currently switched off for this project. Please contact YGO support."
                  }
                }
              },
              "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."
                  }
                }
              },
              "listFull": {
                "summary": "The page's list already holds 10 photos",
                "value": {
                  "Error": {
                    "Code": "INVALID_STATUS_TRANSITION",
                    "Message": "This page already shows the maximum number of photos. Please hide a photo first."
                  }
                }
              },
              "listChanged": {
                "summary": "The page's photo list changed after it was read; retry",
                "value": {
                  "Error": {
                    "Code": "INVALID_STATUS_TRANSITION",
                    "Message": "The photos changed in the meantime. Please reload the page."
                  }
                }
              },
              "notOurStore": {
                "summary": "The upload's URL is not an Uploadcare CDN file URL",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "the photo is not stored in this environment's image store, so it cannot be accepted",
                    "Fields": [
                      {
                        "Field": "FeedbackID",
                        "Code": "NOT_ALLOWED",
                        "Message": "the photo is not stored in this environment's image store, so it cannot be accepted"
                      }
                    ]
                  }
                }
              },
              "listNotWritable": {
                "summary": "The page's list holds a photo that can no longer be listed",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "the page's photo list holds an image that can no longer be listed; fix the list before accepting",
                    "Fields": [
                      {
                        "Field": "FeedbackID",
                        "Code": "CONFLICT",
                        "Message": "the page's photo list holds an image that can no longer be listed; fix the list before accepting"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "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"
                  }
                }
              },
              "loadFailed": {
                "summary": "The hotel's approval page could not be loaded",
                "value": {
                  "Error": {
                    "Code": "INTERNAL_ERROR",
                    "Message": "Failed to load hotel"
                  }
                }
              },
              "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"
                  }
                }
              }
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "Service Unavailable - nothing was written; retry later. The page's ordered photo list could not be read.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "pageDegraded": {
                "summary": "The page's photo list could not be read; nothing was written",
                "value": {
                  "Error": {
                    "Code": "SERVICE_UNAVAILABLE",
                    "Message": "The photos cannot be loaded right now. Please try again shortly."
                  }
                }
              }
            }
          }
        }
      },
      "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"
      }
    }
  }
}
