{
  "openapi": "3.0.0",
  "info": {
    "title": "YGO API: Delete 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/deleteImages": {
      "post": {
        "summary": "Delete vision images",
        "description": "Delete images this project submitted, by image ID.\n\nSynchronous. A delete removes your access, not the picture or its analysis; other clients keep the image.\n\n- Requires an org admin's or owner's user token; a project API key gets 403.\n- 1 to 100 image IDs per request; one entry per ID, in request order.\n- `Status` is `deleted` or `not_found`; an ID you do not own reports `not_found`.\n- Idempotent: an already deleted image answers `deleted` again.\n- The image leaves `listImages`, `getImages` and your `getEnrichedHotel` gallery, and its pin is cleared.\n- Submitting the URL again restores it under the same image ID, unbilled.\n- 404 means Vision AI is not enabled for your project.",
        "operationId": "deleteVisionImages",
        "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/DeleteVisionImagesRequest"
              },
              "examples": {
                "twoImages": {
                  "summary": "Delete two images you uploaded",
                  "value": {
                    "ImageIDs": [
                      "0192fb20-1aa2-7def-9abc-1122334455aa",
                      "0192fb21-2bb3-7def-9abc-2233445566bb"
                    ]
                  }
                },
                "oneNotOwned": {
                  "summary": "One of your images and one ID this project never submitted",
                  "value": {
                    "ImageIDs": [
                      "0192fb20-1aa2-7def-9abc-1122334455aa",
                      "0192fb99-9ff9-7def-9abc-999999999999"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "One entry per requested image ID, in request order. A batch in which every ID answers not_found is still a 200.",
            "headers": {
              "X-Trace-ID": {
                "$ref": "#/components/headers/X-Trace-ID"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteVisionImagesResponse"
                },
                "examples": {
                  "allDeleted": {
                    "summary": "Both images were this project's and are now deleted",
                    "value": {
                      "Data": {
                        "Images": [
                          {
                            "ImageID": "0192fb20-1aa2-7def-9abc-1122334455aa",
                            "Status": "deleted"
                          },
                          {
                            "ImageID": "0192fb21-2bb3-7def-9abc-2233445566bb",
                            "Status": "deleted"
                          }
                        ]
                      }
                    }
                  },
                  "mixed": {
                    "summary": "One deleted, one ID this project does not own",
                    "value": {
                      "Data": {
                        "Images": [
                          {
                            "ImageID": "0192fb20-1aa2-7def-9abc-1122334455aa",
                            "Status": "deleted"
                          },
                          {
                            "ImageID": "0192fb99-9ff9-7def-9abc-999999999999",
                            "Status": "not_found"
                          }
                        ]
                      }
                    }
                  },
                  "repeatCall": {
                    "summary": "The same call again: an already-deleted image still answers deleted",
                    "value": {
                      "Data": {
                        "Images": [
                          {
                            "ImageID": "0192fb20-1aa2-7def-9abc-1122334455aa",
                            "Status": "deleted"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "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": {
      "DeleteVisionImagesRequest": {
        "type": "object",
        "required": [
          "ImageIDs"
        ],
        "description": "Request body for deleting images this project submitted, by image ID.",
        "properties": {
          "ImageIDs": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Image UUIDs returned by ingestVisionImages, between 1 and 100 per request. The response returns one entry per ID, in this order.",
            "example": [
              "0192fb20-1aa2-7def-9abc-1122334455aa",
              "0192fb21-2bb3-7def-9abc-2233445566bb"
            ]
          }
        }
      },
      "DeleteVisionImagesResponse": {
        "type": "object",
        "description": "Standard v2 envelope. Data is an object carrying the per-image results; there is no pagination on this endpoint.",
        "properties": {
          "Data": {
            "$ref": "#/components/schemas/DeleteVisionImagesResult"
          }
        }
      },
      "DeleteVisionImagesResult": {
        "type": "object",
        "required": [
          "Images"
        ],
        "properties": {
          "Images": {
            "type": "array",
            "description": "One entry per requested image ID, in request order.",
            "items": {
              "$ref": "#/components/schemas/DeletedVisionImageState"
            }
          }
        }
      },
      "DeletedVisionImageState": {
        "type": "object",
        "required": [
          "ImageID",
          "Status"
        ],
        "description": "The verdict for one requested image ID. The entry carries no other field in either case, so a not_found entry is indistinguishable in shape from a deleted one.",
        "properties": {
          "ImageID": {
            "type": "string",
            "format": "uuid",
            "description": "Echoes the requested image ID.",
            "example": "0192fb20-1aa2-7def-9abc-1122334455aa"
          },
          "Status": {
            "type": "string",
            "enum": [
              "deleted",
              "not_found"
            ],
            "description": "`deleted`: this project's image is now deleted, or already was. `not_found`: the ID is unknown, belongs to another client or is not a Vision AI image, and these cases are indistinguishable."
          }
        }
      },
      "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": "Name of the field that failed validation. Per-entry errors carry the entry's position, for example ImageIDs[2].",
            "example": "ImageIDs[2]"
          },
          "Message": {
            "type": "string",
            "description": "Human-readable validation error message for this field.",
            "example": "ImageID must be a valid UUID"
          },
          "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
            }
          }
        }
      }
    },
    "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 an image ID is invalid.",
        "headers": {
          "X-Trace-ID": {
            "$ref": "#/components/headers/X-Trace-ID"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "emptyImageIDs": {
                "summary": "No image IDs provided",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "ImageIDs",
                        "Message": "ImageIDs must contain at least one image id"
                      }
                    ]
                  }
                }
              },
              "tooManyImageIDs": {
                "summary": "More than 100 image IDs in one request",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "ImageIDs",
                        "Message": "ImageIDs cannot exceed 100 entries"
                      }
                    ]
                  }
                }
              },
              "malformedImageID": {
                "summary": "An entry is not a valid UUID",
                "value": {
                  "Error": {
                    "Code": "VALIDATION_ERROR",
                    "Message": "Validation failed",
                    "Fields": [
                      {
                        "Field": "ImageIDs[2]",
                        "Message": "ImageID must be a valid UUID"
                      }
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden: the token is a project API key, its user is below org admin, it may not act on this project, or it lacks the `content.catalog:write` permission (`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:write"
                  }
                }
              },
              "noProjectAccess": {
                "summary": "Project access required",
                "value": {
                  "Error": {
                    "Code": "FORBIDDEN",
                    "Message": "Project access required"
                  }
                }
              },
              "roleRequired": {
                "summary": "A project (proj_) token or a user below org admin, the most common refusal",
                "value": {
                  "Error": {
                    "Code": "FORBIDDEN",
                    "Message": "Deleting images requires a user token with the org admin role or higher"
                  }
                }
              }
            }
          }
        }
      },
      "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 delete images"
                  }
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "Not Found: Vision AI is not enabled for your project, or the project does not exist. An unknown image ID is not a 404; it is reported per image as `not_found`.",
        "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 user token 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": "User token (user_...) of an org admin or owner. Project-scoped API keys (proj_...) are refused with 403."
      }
    }
  }
}
