{
  "openapi": "3.1.0",
  "info": {
    "title": "SVG.new API",
    "description": "AI-powered image to SVG vector conversion, editing, and batch processing.",
    "version": "1.0.0",
    "contact": {
      "name": "SVG.new",
      "email": "contact@svg.new",
      "url": "https://svg.new"
    }
  },
  "servers": [
    { "url": "https://svg.new", "description": "Production" }
  ],
  "security": [
    { "bearerAuth": [] }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key starting with svk_. Generate at https://svg.new/account"
      }
    }
  },
  "paths": {
    "/api/agent/vectorize": {
      "post": {
        "operationId": "vectorize",
        "summary": "Convert a raster image to SVG",
        "description": "Upload a base64-encoded PNG, JPG, or WebP image and receive a clean SVG vector. Costs 1 credit.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["image"],
                "properties": {
                  "image": {
                    "type": "string",
                    "description": "Base64 data URL (e.g. data:image/png;base64,...)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Vectorization successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": { "type": "string", "description": "Vectorization ID" },
                    "svg": { "type": "string", "description": "SVG content" },
                    "metadata": {
                      "type": "object",
                      "properties": {
                        "created_at": { "type": "string" },
                        "credits_remaining": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid image data" },
          "401": { "description": "Invalid or missing API key" },
          "402": { "description": "Insufficient credits" },
          "429": { "description": "Rate limited (10 req/min)" }
        }
      }
    },
    "/api/agent/edit/recolor": {
      "post": {
        "operationId": "recolor",
        "summary": "Change colors in an SVG",
        "description": "Replace colors in an SVG according to a color map. Free, no credit cost.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["svg", "color_map"],
                "properties": {
                  "svg": { "type": "string", "description": "SVG content" },
                  "color_map": {
                    "type": "object",
                    "additionalProperties": { "type": "string" },
                    "description": "Map of old hex colors to new hex colors"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recolor successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "svg": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/edit/simplify": {
      "post": {
        "operationId": "simplify",
        "summary": "Reduce SVG color palette",
        "description": "Quantize colors in an SVG to a maximum count using median-cut. Free, no credit cost.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["svg", "max_colors"],
                "properties": {
                  "svg": { "type": "string", "description": "SVG content" },
                  "max_colors": { "type": "integer", "minimum": 1, "maximum": 256, "description": "Target color count" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Simplification successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "svg": { "type": "string" },
                    "colors_before": { "type": "integer" },
                    "colors_after": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/edit/remove-background": {
      "post": {
        "operationId": "removeBackground",
        "summary": "Remove SVG background",
        "description": "Remove background from an SVG using AI on the original raster image. Costs 1 credit.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["svg", "image"],
                "properties": {
                  "svg": { "type": "string", "description": "SVG content" },
                  "image": { "type": "string", "description": "Original raster image as base64 data URL" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Background removal successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "svg": { "type": "string" },
                    "transparent_image": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/batch": {
      "post": {
        "operationId": "batchVectorize",
        "summary": "Batch vectorize images",
        "description": "Submit up to 50 images for async vectorization. Returns a batch ID to poll. Costs 1 credit per image.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["images"],
                "properties": {
                  "images": {
                    "type": "array",
                    "maxItems": 50,
                    "items": {
                      "type": "object",
                      "properties": {
                        "image": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Batch submitted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "batch_id": { "type": "string" },
                    "total_items": { "type": "integer" },
                    "status": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/batch/{id}": {
      "get": {
        "operationId": "getBatchStatus",
        "summary": "Get batch job status",
        "description": "Poll the status of a batch vectorization job. Returns item-level status and signed SVG URLs when complete.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Batch status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "enum": ["pending", "processing", "completed", "failed"] },
                    "total_items": { "type": "integer" },
                    "completed_items": { "type": "integer" },
                    "failed_items": { "type": "integer" },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "index": { "type": "integer" },
                          "status": { "type": "string" },
                          "prompt_id": { "type": "string" },
                          "svg_url": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
