{
  "openapi": "3.0.0",
  "info": {
    "title": "YGO API: List vision images",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.ygo.ai",
      "description": "Production and Sandbox (determined by API key)"
    }
  ],
  "paths": {
    "/v2/project/content/vision/listImages": {
      "post": {
        "summary": "List vision images",
        "description": "List this project's submitted images, newest first, with the enriched image object for every image that is complete.\n\nAnalysis runs asynchronously, so an image listed as `pending` is still being worked on. An empty body `{}` returns the first page of everything this project has submitted.\n\n- `Limit` defaults to 50, caps at 100; `Offset` defaults to 0.\n- `Status` filters to `pending`, `completed` or `failed`; any other value returns 400.\n- Ordered by `SubmittedAt` then `ImageID`, both descending.\n- `Data` is the array itself; `Pagination.Total` counts the match.\n- A `Status` filter covers your newest 10,000 submissions.\n- 404 means Vision AI is not enabled for your project.\n- 429 means the rate limit was hit; wait `Retry-After` seconds.",
        "operationId": "listVisionImages",
        "tags": [
          "Content Enrichment API/Vision AI"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/X-Project-ID"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListVisionImagesRequest"
              },
              "examples": {
                "noFilter": {
                  "summary": "First page of everything this project has submitted",
                  "value": {}
                },
                "completedOnly": {
                  "summary": "Only the analyzed images, two per page",
                  "value": {
                    "Status": "completed",
                    "Limit": 2,
                    "Offset": 0
                  }
                },
                "pastTheEnd": {
                  "summary": "An offset beyond the last entry",
                  "value": {
                    "Offset": 200
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One page of this project's submitted images, newest first.",
            "headers": {
              "X-Trace-ID": {
                "$ref": "#/components/headers/X-Trace-ID"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListVisionImagesResponse"
                },
                "examples": {
                  "noFilter": {
                    "summary": "Four images: one still being analyzed, two analyzed, one unreachable — three submitted without a hotel and one for a hotel",
                    "value": {
                      "Data": [
                        {
                          "ImageID": "0199b2d0-11a5-7c5e-8f21-6d0e4f88b521",
                          "URL": "https://ucarecdn.com/9c1b7e42-5a6d-4f38-9a11-2b7c8d5e6f01/",
                          "Status": "pending",
                          "SubmittedAt": "2026-09-09T16:04:51.812433Z",
                          "BatchID": "0199b2d0-11a4-7c5e-8f21-5c9d3e77a410",
                          "HotelID": "01a086e1-ffaf-7040-b032-76677278f0ae",
                          "HotelName": "Vision AI API placeholder",
                          "IsPlaceholderHotel": true
                        },
                        {
                          "ImageID": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4",
                          "URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/",
                          "Status": "completed",
                          "SubmittedAt": "2026-09-09T16:04:12.550118Z",
                          "BatchID": "0199b2c4-8e30-7b19-9a4d-2e7f6c1b8d33",
                          "HotelID": "01a086e1-ffaf-7040-b032-76677278f0ae",
                          "HotelName": "Vision AI API placeholder",
                          "IsPlaceholderHotel": true,
                          "Image": {
                            "ID": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4",
                            "URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/",
                            "Source": "photo",
                            "Category": "restaurant",
                            "Features": [
                              "indoor_seating",
                              "buffet"
                            ],
                            "Mood": [
                              "warm",
                              "inviting"
                            ],
                            "Tags": [
                              "breakfast"
                            ],
                            "AppealScore": 74,
                            "QualityScore": 81,
                            "AppealScoreVersion": "app-v4",
                            "QualityScoreVersion": "qs-v4",
                            "Width": 2000,
                            "Height": 1333,
                            "Format": "jpeg",
                            "FileSize": 611000,
                            "DominantColor": "#8A6A48",
                            "BlurHash": "L6PZfSjE.AyE_3t7t7R**0o#DgR4",
                            "FileMetadata": {
                              "CaptureDate": "2012-06-14",
                              "Copyright": "© 2012 Hotel Sol S.A."
                            },
                            "Descriptions": {
                              "en-US": "Restaurant with buffet counters and set tables.",
                              "de-DE": "Restaurant mit Buffettheken und eingedeckten Tischen."
                            },
                            "Compliance": {
                              "AIGenerated": true
                            },
                            "FeatureDetections": [
                              {
                                "Label": "buffet",
                                "Confidence": 0.91
                              },
                              {
                                "Label": "indoor_seating",
                                "Confidence": 0.86
                              }
                            ]
                          }
                        },
                        {
                          "ImageID": "0199b2c4-8e31-77aa-9c02-1a4c60b8c7f1",
                          "URL": "https://ucarecdn.com/7d4e9b21-6c3a-4f52-8e10-9b8a7c6d5e4f/",
                          "Status": "failed",
                          "SubmittedAt": "2026-09-09T16:04:12.550118Z",
                          "BatchID": "0199b2c4-8e30-7b19-9a4d-2e7f6c1b8d33",
                          "HotelID": "01a086e1-ffaf-7040-b032-76677278f0ae",
                          "HotelName": "Vision AI API placeholder",
                          "IsPlaceholderHotel": true
                        },
                        {
                          "ImageID": "0199a51f-4c23-7de8-b3a9-1122334455aa",
                          "URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
                          "Status": "completed",
                          "SubmittedAt": "2026-09-08T09:12:44.301882Z",
                          "BatchID": "0199a51f-4c22-7de8-b3a9-0f1e2d3c4b5a",
                          "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
                          "HotelName": "Hotel Bahia Azul",
                          "RoomRef": "DBL-SEA",
                          "Image": {
                            "ID": "0199a51f-4c23-7de8-b3a9-1122334455aa",
                            "URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
                            "Source": "photo",
                            "Category": "room",
                            "Features": [
                              "sea_view",
                              "balcony",
                              "double_bed"
                            ],
                            "Mood": [
                              "bright",
                              "calm"
                            ],
                            "Tags": [
                              "sea_view"
                            ],
                            "AppealScore": 82,
                            "QualityScore": 77,
                            "AppealScoreVersion": "app-v4",
                            "QualityScoreVersion": "qs-v4",
                            "Width": 1600,
                            "Height": 1067,
                            "Format": "jpeg",
                            "FileSize": 412000,
                            "DominantColor": "#2E6F95",
                            "BlurHash": "LEHV6nWB2yk8pyo0adR*",
                            "Descriptions": {
                              "en-US": "Double room with a balcony overlooking the sea.",
                              "de-DE": "Doppelzimmer mit Balkon und Meerblick."
                            },
                            "Compliance": {
                              "AIGenerated": true
                            },
                            "Presence": [
                              {
                                "Label": "adult",
                                "Confidence": 0.81
                              }
                            ],
                            "Safety": {
                              "Inappropriate": 0.02,
                              "OffTopic": null
                            },
                            "FeatureDetections": [
                              {
                                "Label": "sea_view",
                                "Confidence": 0.94
                              },
                              {
                                "Label": "balcony",
                                "Confidence": 0.88
                              }
                            ]
                          }
                        }
                      ],
                      "Pagination": {
                        "Total": 4,
                        "Limit": 50,
                        "Offset": 0
                      }
                    }
                  },
                  "completedOnly": {
                    "summary": "The two analyzed images, one page of two, and Total counts only what the filter matched",
                    "value": {
                      "Data": [
                        {
                          "ImageID": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4",
                          "URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/",
                          "Status": "completed",
                          "SubmittedAt": "2026-09-09T16:04:12.550118Z",
                          "BatchID": "0199b2c4-8e30-7b19-9a4d-2e7f6c1b8d33",
                          "HotelID": "01a086e1-ffaf-7040-b032-76677278f0ae",
                          "HotelName": "Vision AI API placeholder",
                          "IsPlaceholderHotel": true,
                          "Image": {
                            "ID": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4",
                            "URL": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/",
                            "Source": "photo",
                            "Category": "restaurant",
                            "Features": [
                              "indoor_seating",
                              "buffet"
                            ],
                            "Mood": [
                              "warm",
                              "inviting"
                            ],
                            "Tags": [
                              "breakfast"
                            ],
                            "AppealScore": 74,
                            "QualityScore": 81,
                            "AppealScoreVersion": "app-v4",
                            "QualityScoreVersion": "qs-v4",
                            "Width": 2000,
                            "Height": 1333,
                            "Format": "jpeg",
                            "FileSize": 611000,
                            "DominantColor": "#8A6A48",
                            "BlurHash": "L6PZfSjE.AyE_3t7t7R**0o#DgR4",
                            "Descriptions": {
                              "en-US": "Restaurant with buffet counters and set tables.",
                              "de-DE": "Restaurant mit Buffettheken und eingedeckten Tischen."
                            },
                            "Compliance": {
                              "AIGenerated": true
                            }
                          }
                        },
                        {
                          "ImageID": "0199a51f-4c23-7de8-b3a9-1122334455aa",
                          "URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
                          "Status": "completed",
                          "SubmittedAt": "2026-09-08T09:12:44.301882Z",
                          "BatchID": "0199a51f-4c22-7de8-b3a9-0f1e2d3c4b5a",
                          "HotelID": "0192fb17-5dc6-7abc-8def-123456789abc",
                          "HotelName": "Hotel Bahia Azul",
                          "RoomRef": "DBL-SEA",
                          "Image": {
                            "ID": "0199a51f-4c23-7de8-b3a9-1122334455aa",
                            "URL": "https://images.example-client.com/1234567/room-dbl-sea-1.jpg",
                            "Source": "photo",
                            "Category": "room",
                            "Features": [
                              "sea_view",
                              "balcony",
                              "double_bed"
                            ],
                            "Mood": [
                              "bright",
                              "calm"
                            ],
                            "Tags": [
                              "sea_view"
                            ],
                            "AppealScore": 82,
                            "QualityScore": 77,
                            "AppealScoreVersion": "app-v4",
                            "QualityScoreVersion": "qs-v4",
                            "Width": 1600,
                            "Height": 1067,
                            "Format": "jpeg",
                            "FileSize": 412000,
                            "DominantColor": "#2E6F95",
                            "BlurHash": "LEHV6nWB2yk8pyo0adR*",
                            "Descriptions": {
                              "en-US": "Double room with a balcony overlooking the sea.",
                              "de-DE": "Doppelzimmer mit Balkon und Meerblick."
                            },
                            "Compliance": {
                              "AIGenerated": true
                            }
                          }
                        }
                      ],
                      "Pagination": {
                        "Total": 2,
                        "Limit": 2,
                        "Offset": 0
                      }
                    }
                  },
                  "pastTheEnd": {
                    "summary": "An empty page: Images is [], and Total still counts every match",
                    "value": {
                      "Data": [],
                      "Pagination": {
                        "Total": 4,
                        "Limit": 50,
                        "Offset": 200
                      }
                    }
                  }
                }
              }
            }
          },
          "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"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Compliance": {
        "type": "object",
        "properties": {
          "AIGenerated": {
            "type": "boolean",
            "description": "EU AI Act Art. 50(2) machine-readable marker: `true` when the text content of the enclosing object is AI-generated. Always stated explicitly when the envelope is present.",
            "example": true
          }
        }
      },
      "DetectionConfidence": {
        "type": "number",
        "format": "float",
        "nullable": true,
        "minimum": 0,
        "maximum": 1,
        "description": "Confidence between 0 and 1, or null when the entry was asserted without a measured confidence. An entry the analysis did not assert is absent from its list rather than scored zero.",
        "example": 0.94
      },
      "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"
          }
        }
      },
      "FeatureDetection": {
        "type": "object",
        "required": [
          "Label",
          "Confidence"
        ],
        "description": "One feature of the image with the confidence measured for it.",
        "properties": {
          "Label": {
            "type": "string",
            "description": "The feature label, from the same vocabulary as Features.",
            "example": "sea_view"
          },
          "Confidence": {
            "$ref": "#/components/schemas/DetectionConfidence"
          }
        }
      },
      "FieldError": {
        "type": "object",
        "required": [
          "Field",
          "Message"
        ],
        "description": "A single field-level validation error.",
        "properties": {
          "Field": {
            "type": "string",
            "description": "Name of the field that failed validation.",
            "example": "Status"
          },
          "Message": {
            "type": "string",
            "description": "Human-readable validation error message for this field.",
            "example": "Status must be omitted or one of pending, completed, failed"
          },
          "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 and depend on Code. Optional.",
            "example": {
              "Max": 100
            }
          }
        }
      },
      "Image": {
        "type": "object",
        "required": [
          "ID",
          "URL"
        ],
        "properties": {
          "ID": {
            "type": "string",
            "format": "uuid",
            "description": "Unique image UUID.",
            "example": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4"
          },
          "URL": {
            "type": "string",
            "format": "uri",
            "description": "Image URL.",
            "example": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/"
          },
          "Source": {
            "type": "string",
            "description": "Detected provenance of the pixels: `photo`, `render`, `illustration` or `ai_generated`. Omitted when the image carries no provenance assessment.",
            "example": "photo"
          },
          "Category": {
            "type": "string",
            "description": "Vision-derived image category (e.g. exterior, room, pool, restaurant).",
            "example": "room"
          },
          "Features": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Vision-derived feature tags depicted in the image.",
            "example": [
              "sea_view",
              "balcony"
            ]
          },
          "Mood": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Vision-derived mood descriptors.",
            "example": [
              "bright",
              "calm"
            ]
          },
          "Tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Additional vision-derived tags.",
            "example": [
              "sea_view"
            ]
          },
          "Flags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Quality / content flags raised by vision analysis. Omitted when empty."
          },
          "AppealScore": {
            "type": "integer",
            "description": "Appeal score from 0 to 100, or -1 when there is no scorer-stamped value and no value above 0, normally because nothing has scored the image yet. -1 is not a score and does not affect image order.",
            "example": 82
          },
          "QualityScore": {
            "type": "integer",
            "description": "Technical quality score from 0 to 100, or -1 when there is no scorer-stamped value and no value above 0, normally because nothing has scored the image yet. -1 is not a score and does not affect image order.",
            "example": 77
          },
          "AppealScoreVersion": {
            "type": "string",
            "description": "Version stamp of the scorer that produced AppealScore, for example `app-v4`; it may name an earlier version. Absent when AppealScore is -1 or a legacy score from before stamps existed.",
            "example": "app-v4"
          },
          "QualityScoreVersion": {
            "type": "string",
            "description": "Version stamp of the scorer that produced QualityScore, for example `qs-v4`; it may name an earlier version. Absent when QualityScore is -1, a legacy score, or a first-seen image's provisional score.",
            "example": "qs-v4"
          },
          "Width": {
            "type": "integer",
            "description": "Image width in pixels.",
            "example": 1600
          },
          "Height": {
            "type": "integer",
            "description": "Image height in pixels.",
            "example": 1067
          },
          "Format": {
            "type": "string",
            "description": "Image format (e.g. jpeg, png, webp).",
            "example": "jpeg"
          },
          "FileSize": {
            "type": "integer",
            "description": "File size in bytes.",
            "example": 412000
          },
          "DominantColor": {
            "type": "string",
            "description": "Dominant color as a hex string.",
            "example": "#2E6F95"
          },
          "BlurHash": {
            "type": "string",
            "description": "BlurHash placeholder string for progressive loading.",
            "example": "LEHV6nWB2yk8pyo0adR*"
          },
          "FileMetadata": {
            "type": "object",
            "description": "What the image file itself states in its embedded IPTC/EXIF/XMP metadata: capture date and copyright notice. Omitted when the file states neither; inside it, a value the file did not state has no key.",
            "properties": {
              "CaptureDate": {
                "type": "string",
                "pattern": "^\\d{4}(-\\d{2}(-\\d{2})?)?$",
                "description": "Date the photograph was taken, at the precision the file stated: `2012-06-14`, `2012-06` or `2012`. It carries no time of day and no timezone.",
                "example": "2012-06-14"
              },
              "Copyright": {
                "type": "string",
                "description": "The copyright notice the file carries, as the file wrote it. It names who to ask; it is not a machine-readable licence.",
                "example": "© 2012 Hotel Sol S.A."
              }
            },
            "example": {
              "CaptureDate": "2012-06-14",
              "Copyright": "© 2012 Hotel Sol S.A."
            }
          },
          "Descriptions": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Neutral alt text describing what the image shows, not marketing copy, keyed by BCP 47 language tag. More locales may be added after an image is first analyzed.",
            "example": {
              "en-US": "Double room with a balcony overlooking the sea.",
              "de-DE": "Doppelzimmer mit Balkon und Meerblick."
            }
          },
          "Compliance": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Compliance"
              }
            ],
            "description": "EU AI Act Article 50(2) marker for this image. Always present with `AIGenerated` true: the category, features, mood, tags, scores and descriptions are model output, `FileMetadata` is not."
          },
          "Presence": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PresenceDetection"
            },
            "description": "People and animals seen in the image, from the closed vocabulary person, adult, child, animal. Omitted when the image carries no presence measurement."
          },
          "Safety": {
            "type": "object",
            "additionalProperties": {
              "type": "number",
              "format": "float",
              "nullable": true,
              "minimum": 0,
              "maximum": 1
            },
            "description": "Safety confidences keyed by dimension, `Inappropriate` and `OffTopic`, each between 0 and 1 or null. Omitted when the image carries no safety measurement.",
            "example": {
              "Inappropriate": 0.02,
              "OffTopic": null
            }
          },
          "TextDetections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TextDetection"
            },
            "description": "Texts read off the image, each with its kind. Omitted when the image carries no text measurement."
          },
          "FeatureDetections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FeatureDetection"
            },
            "description": "The image's features with the confidence measured for each, running parallel to `Features`. Omitted when the image carries no feature measurement."
          },
          "Nudity": {
            "type": "object",
            "description": "Nudity assessment: exposure score, reason and explicit flag, independent of `Safety.Inappropriate`. Omitted when the assessment did not run or the image's `Presence` shows no person.",
            "required": [
              "Score",
              "Reason",
              "Explicit"
            ],
            "properties": {
              "Score": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100,
                "description": "Exposure score from 0 to 100. Anchors: 20 beach or casual wear, 40 standard swimwear, 60 revealing swimwear or lingerie, 80 partial nudity, 100 explicit.",
                "example": 60
              },
              "Reason": {
                "type": "string",
                "description": "One model-written sentence naming what drives the score, at most 240 characters. Not sanitized for markup, so escape it before rendering.",
                "example": "Adult in revealing swimwear by the pool."
              },
              "Explicit": {
                "type": "boolean",
                "description": "True from a score of 90 up. Whether a child is in the picture is answered by `Presence`, not here.",
                "example": false
              }
            }
          }
        }
      },
      "ListVisionImage": {
        "type": "object",
        "required": [
          "ImageID",
          "URL",
          "Status",
          "SubmittedAt",
          "BatchID",
          "HotelID"
        ],
        "description": "One submitted image: its state, when and how it was submitted, and the enriched image object once the analysis is complete.",
        "properties": {
          "ImageID": {
            "type": "string",
            "format": "uuid",
            "description": "Image UUID, the same ID ingestVisionImages returned and getVisionImages polls.",
            "example": "0199b2c4-8e31-77aa-9c02-3f5b71a2d9e4"
          },
          "URL": {
            "type": "string",
            "format": "uri",
            "description": "The submitted image URL, normalized.",
            "example": "https://ucarecdn.com/3f0a1d55-8b2c-4e79-9d64-7a1c2b3d4e5f/"
          },
          "Status": {
            "type": "string",
            "enum": [
              "pending",
              "completed",
              "failed"
            ],
            "description": "Analysis state: `pending` still being analyzed, `completed` `Image` carries the result, `failed` the URL could not be fetched. `not_found` never appears here.",
            "example": "completed"
          },
          "SubmittedAt": {
            "type": "string",
            "format": "date-time",
            "description": "RFC 3339 timestamp of the submission. It is the sort key, descending; re-submitting the same URL refreshes it, which moves the image back to the top of the list.",
            "example": "2026-09-09T16:04:12.550118Z"
          },
          "BatchID": {
            "type": "string",
            "format": "uuid",
            "description": "Identifier shared by every image submitted in the same ingestVisionImages request.",
            "example": "0199b2c4-8e30-7b19-9a4d-2e7f6c1b8d33"
          },
          "HotelID": {
            "type": "string",
            "format": "uuid",
            "description": "UUID of the hotel this image is stored under.",
            "example": "01a086e1-ffaf-7040-b032-76677278f0ae"
          },
          "HotelName": {
            "type": "string",
            "description": "Name of that hotel. Present for the placeholder hotel and for hotels that belong to your project, omitted otherwise.",
            "example": "Vision AI API placeholder"
          },
          "IsPlaceholderHotel": {
            "type": "boolean",
            "description": "True when the image was submitted without a hotel and therefore sits on the project's placeholder hotel. Present only when it is true; omitted for an image submitted for a hotel.",
            "example": true
          },
          "RoomRef": {
            "type": "string",
            "description": "The room code or name submitted with this image. Omitted when the image was submitted without one.",
            "example": "DBL-SEA"
          },
          "Image": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Image"
              }
            ],
            "description": "The enriched image object. Present only when Status is `completed`."
          }
        }
      },
      "ListVisionImagesRequest": {
        "type": "object",
        "description": "Filter and page this project's submitted images. Every field is optional, so an empty body `{}` returns the first page of every image the project has submitted.",
        "properties": {
          "Status": {
            "type": "string",
            "enum": [
              "pending",
              "completed",
              "failed"
            ],
            "description": "Restrict the list to one state; omit it to list every state. A filter covers your newest 10,000 submissions.",
            "example": "completed"
          },
          "Limit": {
            "type": "integer",
            "default": 50,
            "description": "Page size. Defaults to 50 when omitted or 0; a value above 100 is reduced to 100 rather than refused.",
            "example": 50
          },
          "Offset": {
            "type": "integer",
            "default": 0,
            "description": "Number of images to skip before this page, default 0. An offset past the last image returns an empty page.",
            "example": 0
          }
        }
      },
      "ListVisionImagesResponse": {
        "type": "object",
        "required": [
          "Data",
          "Pagination"
        ],
        "description": "List response envelope: Data is the page of submitted images and Pagination describes the whole matching set.",
        "properties": {
          "Data": {
            "type": "array",
            "description": "The page of submitted images, newest first. Always an array: an empty page is [] and never null.",
            "items": {
              "$ref": "#/components/schemas/ListVisionImage"
            }
          },
          "Pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "Pagination": {
        "type": "object",
        "required": [
          "Total",
          "Limit",
          "Offset"
        ],
        "description": "Pagination metadata for a list response.",
        "properties": {
          "Total": {
            "type": "integer",
            "description": "Number of images matching the request across all pages, not the page size. With a `Status` filter it covers your newest 10,000 submissions.",
            "example": 4
          },
          "Limit": {
            "type": "integer",
            "description": "Page size actually applied, after the default and the cap.",
            "example": 50
          },
          "Offset": {
            "type": "integer",
            "description": "Number of images skipped before this page.",
            "example": 0
          }
        }
      },
      "PresenceDetection": {
        "type": "object",
        "required": [
          "Label",
          "Confidence"
        ],
        "description": "One person or animal seen in the image.",
        "properties": {
          "Label": {
            "type": "string",
            "description": "What was seen: `person`, `adult`, `child` or `animal`.",
            "example": "adult"
          },
          "Confidence": {
            "$ref": "#/components/schemas/DetectionConfidence"
          }
        }
      },
      "TextDetection": {
        "type": "object",
        "required": [
          "Content",
          "Label",
          "Confidence"
        ],
        "description": "One text read off the image.",
        "properties": {
          "Content": {
            "type": "string",
            "description": "The text as it appears on the image. A password or access code printed after a password label is masked.",
            "example": "POOL BAR"
          },
          "Label": {
            "type": "string",
            "description": "Kind of text: `overlay`, `price`, `promotional`, `watermark`, `signage` or `document`.",
            "example": "signage"
          },
          "Confidence": {
            "$ref": "#/components/schemas/DetectionConfidence"
          }
        }
      }
    },
    "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": 30
        }
      },
      "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 `Status` value is invalid. `Limit` and `Offset` are clamped to the accepted range, never rejected.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "invalidStatus": {
                "summary": "Status is not one of the three states",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "Status",
                        "Message": "Status must be omitted or one of pending, completed, failed"
                      }
                    ]
                  }
                }
              },
              "malformedBody": {
                "summary": "The request body is not valid JSON, or a field has the wrong type",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Invalid request body"
                  }
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden: the API key may not act on this project, or does not carry the `content.catalog:read` permission this endpoint requires (`INSUFFICIENT_SCOPE`).",
        "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.catalog:read"
                  }
                }
              },
              "noProjectAccess": {
                "summary": "Project access required",
                "value": {
                  "Error": {
                    "Code": "FORBIDDEN",
                    "Message": "Project access required"
                  }
                }
              }
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal Server Error: unexpected server error. Quote the `X-Trace-ID` response header when contacting support.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "internalError": {
                "summary": "Internal server error",
                "value": {
                  "Error": {
                    "Code": "INTERNAL_ERROR",
                    "Message": "Failed to load images"
                  }
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Not Found: Vision AI is not enabled for your project, or the project does not exist. A project with no submissions is an empty page, not a 404.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "notFound": {
                "summary": "Project or resource not found",
                "value": {
                  "Error": {
                    "Code": "NOT_FOUND",
                    "Message": "Not found"
                  }
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too Many Requests: the rate limit was exceeded. `Retry-After` carries 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: the API key is missing or invalid.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "invalidKey": {
                "summary": "Invalid API key",
                "value": {
                  "Error": {
                    "Code": "UNAUTHORIZED",
                    "Message": "Invalid API key"
                  }
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Project-scoped API key"
      }
    }
  }
}
