{
  "openapi": "3.0.3",
  "info": {
    "title": "Aqua Developer API",
    "description": "Stateless B2B API for programmatically generating iOS App Store icons and polished App Store screenshots. Credits are managed via the Aqua dashboard. Failed requests are refunded automatically.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.aqua-app.com",
      "description": "Production API Server"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local Development Server"
    }
  ],
  "paths": {
    "/api/v1/icons/generate": {
      "post": {
        "summary": "Generate App Icon Set",
        "description": "Deducts 1 credit from the API key owner's account to synchronously generate an App Store icon set (.icon ZIP file). Returns the binary asset directly in the response; no dashboard app ID is required.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompt": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500,
                    "description": "Description of the icon visual concept (max 500 characters). Must not contain HTTP links or URLs."
                  }
                },
                "required": ["prompt"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Icon set ZIP generated successfully",
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request. Invalid JSON body or invalid prompt (empty, over 500 characters, or contains URLs/links)."
          },
          "401": {
            "description": "Unauthorized. Missing or invalid API key."
          },
          "402": {
            "description": "Payment Required. Insufficient credit balance."
          },
          "500": {
            "description": "Server or image generation failure. Failed requests are refunded automatically."
          }
        }
      }
    },
    "/api/v1/icons/png": {
      "post": {
        "summary": "Generate App Icon PNG",
        "description": "Deducts 1 credit from the API key owner's account to synchronously generate an App Store master icon PNG. Returns the binary asset directly in the response; no dashboard app ID is required.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "prompt": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 500,
                    "description": "Description of the icon visual concept (max 500 characters). Must not contain HTTP links or URLs."
                  }
                },
                "required": ["prompt"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Icon PNG generated successfully",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request. Invalid JSON body or invalid prompt (empty, over 500 characters, or contains URLs/links)."
          },
          "401": {
            "description": "Unauthorized. Missing or invalid API key."
          },
          "402": {
            "description": "Payment Required. Insufficient credit balance."
          },
          "500": {
            "description": "Server or image generation failure. Failed requests are refunded automatically."
          }
        }
      }
    },
    "/api/v1/screenshots/generate": {
      "post": {
        "summary": "Generate App Store Screenshots",
        "description": "Deducts 1 credit per screenshot (max 5) to synchronously generate polished App Store screenshots from raw iPhone captures (1206×2622). Returns a ZIP of PNG files directly in the response; no dashboard app ID is required.",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": ["manifest"],
                "properties": {
                  "manifest": {
                    "type": "string",
                    "description": "JSON string: { appDisplayName (string, max 120), screenshots: [{ slot (1-5, unique values), position (iphone_full_with_text_top | iphone_bottom_with_text_top | iphone_top_with_text_bottom), copy ('auto' | { title, subtitle } with per-position length limits), backgroundColor ('auto' | hex | linear-gradient | Unsplash url()) }] }. Explicit copy limits: iphone_full_with_text_top title/subtitle 1-20; iphone_bottom_with_text_top title 22-50 subtitle 20-80; iphone_top_with_text_bottom title 22-50 subtitle 20-80."
                  },
                  "capture_1": {
                    "type": "string",
                    "format": "binary",
                    "description": "PNG raw capture for slot 1"
                  },
                  "capture_2": {
                    "type": "string",
                    "format": "binary",
                    "description": "PNG raw capture for slot 2"
                  },
                  "capture_3": {
                    "type": "string",
                    "format": "binary",
                    "description": "PNG raw capture for slot 3"
                  },
                  "capture_4": {
                    "type": "string",
                    "format": "binary",
                    "description": "PNG raw capture for slot 4"
                  },
                  "capture_5": {
                    "type": "string",
                    "format": "binary",
                    "description": "PNG raw capture for slot 5"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Screenshot ZIP generated successfully",
            "content": {
              "application/zip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request. Invalid manifest or capture uploads."
          },
          "401": {
            "description": "Unauthorized. Missing or invalid API key."
          },
          "402": {
            "description": "Payment Required. Insufficient credit balance."
          },
          "500": {
            "description": "Server failure (e.g. credit transaction failure). Failed requests are refunded automatically."
          },
          "502": {
            "description": "Screenshot render service failure. Failed requests are refunded automatically."
          },
          "503": {
            "description": "Screenshot render service is not configured. Failed requests are refunded automatically."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      }
    }
  }
}