{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent SVG Registry API",
    "version": "1.0.0",
    "description": "Search, preview, license, and export SVG UI assets for agent-built interfaces."
  },
  "externalDocs": {
    "description": "Agent integration guide",
    "url": "https://agent-svg-registry.vercel.app/agent-integration"
  },
  "servers": [
    {
      "url": "https://agent-svg-registry.vercel.app"
    }
  ],
  "paths": {
    "/api/stats": {
      "get": {
        "summary": "Catalog stats",
        "operationId": "getCatalogStats",
        "responses": {
          "200": {
            "description": "Category and style counts"
          }
        }
      }
    },
    "/api/assets": {
      "get": {
        "summary": "Search SVG assets",
        "operationId": "searchSvg",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Search query such as passkey, billing, agent, or empty state."
          },
          {
            "name": "category",
            "in": "query",
            "schema": { "type": "string" }
          },
          {
            "name": "style",
            "in": "query",
            "schema": { "type": "string", "enum": ["outline", "filled", "duotone", "illustration"] }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 500 }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results with public asset metadata"
          }
        }
      }
    },
    "/invoke": {
      "post": {
        "summary": "Marketplace invoke endpoint",
        "operationId": "invokeAgentOffer",
        "description": "Simple REST endpoint for agent marketplaces. Returns search, quote, checkout, and licensed export links for an input request.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "input": { "type": "string" },
                  "text": { "type": "string" },
                  "query": { "type": "string" },
                  "prompt": { "type": "string" },
                  "capability": { "type": "string" }
                }
              },
              "examples": {
                "licenseSvg": {
                  "value": {
                    "input": "Need a paid-ready passkey SVG for a SaaS app.",
                    "capability": "licensed-svg-export"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent-readable offer with checkout and export links"
          }
        }
      },
      "get": {
        "summary": "Invoke endpoint metadata",
        "operationId": "getInvokeMetadata",
        "responses": {
          "200": {
            "description": "Invoke endpoint metadata"
          }
        }
      }
    },
    "/api/assets/{asset_id}": {
      "get": {
        "summary": "Asset detail",
        "operationId": "getAsset",
        "parameters": [
          {
            "name": "asset_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Asset metadata and quality gate status"
          },
          "404": {
            "description": "Asset not found"
          }
        }
      }
    },
    "/api/previews/{asset_id}": {
      "get": {
        "summary": "Watermarked preview SVG",
        "operationId": "previewSvg",
        "parameters": [
          {
            "name": "asset_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Watermarked SVG preview"
          }
        }
      }
    },
    "/api/packs/founding-saas-ui-states-v1": {
      "get": {
        "summary": "Founding commercial pack",
        "operationId": "getFoundingPack",
        "responses": {
          "200": {
            "description": "Commercial-ready asset pack metadata"
          }
        }
      }
    },
    "/api/packs/founding-saas-ui-states-v1/export": {
      "get": {
        "summary": "Licensed founding pack export",
        "operationId": "exportFoundingPack",
        "description": "Requires a paid commercial license token in the x-agent-svg-license header or Bearer authorization. Returns all paid-ready pack assets with SVG, React, and inline HTML payloads.",
        "parameters": [
          {
            "name": "x-agent-svg-license",
            "in": "header",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Bulk SVG, React, and inline HTML payloads for the paid-ready pack"
          },
          "402": {
            "description": "Payment required before licensed export",
            "content": {
              "application/json": {
                "examples": {
                  "paymentRequired": {
                    "value": {
                      "error": "A valid commercial license token is required for pack export.",
                      "license_required": true,
                      "payment_required": {
                        "type": "payment_required",
                        "price": { "amount": 0.5, "currency": "USD", "cadence": "one-time" },
                        "requires_human_approval": true,
                        "approval_prompt": "I found a paid-ready SVG pack in Agent SVG Registry. Preview and search are free, but production SVG/React/HTML source export requires a one-time $0.50 commercial license through Stripe Checkout. May I open https://agent-svg-registry.vercel.app/buy/launch?pack_id=founding-saas-ui-states-v1?",
                        "checkout_url": "https://agent-svg-registry.vercel.app/buy/launch?pack_id=founding-saas-ui-states-v1",
                        "checkout_intent_url": "https://agent-svg-registry.vercel.app/api/checkout-intents",
                        "license_token_header": "x-agent-svg-license"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/quote": {
      "get": {
        "summary": "Quote commercial license",
        "operationId": "quoteLicense",
        "description": "Returns launch license pricing, human approval copy, checkout URL, receipt schema, and export endpoints before purchase.",
        "parameters": [
          {
            "name": "plan",
            "in": "query",
            "schema": { "type": "string", "default": "launch" }
          }
        ],
        "responses": {
          "200": {
            "description": "Commercial license quote for an agent approval prompt",
            "content": {
              "application/json": {
                "example": {
                  "product": "agent-svg-registry-commercial-license",
                  "price": { "amount": 0.5, "currency": "USD", "cadence": "one-time" },
                  "requires_human_approval": true,
                  "approval_copy": "This task needs a licensed SVG export; price is $0.50 total, non-recurring, and I need human approval before checkout.",
                  "approval_prompt": "I found a paid-ready SVG in Agent SVG Registry. Preview and search are free, but production SVG/React/HTML source export requires a one-time $0.50 commercial license through Stripe Checkout. May I open https://agent-svg-registry.vercel.app/buy/launch?",
                  "checkout_url": "https://agent-svg-registry.vercel.app/buy/launch",
                  "checkout_intent_url": "https://agent-svg-registry.vercel.app/api/checkout-intents",
                  "checkout_intent_body": {
                    "plan_id": "launch",
                    "pack_id": "founding-saas-ui-states-v1"
                  },
                  "license_terms_url": "https://agent-svg-registry.vercel.app/license",
                  "export_urls": {
                    "pack": "https://agent-svg-registry.vercel.app/api/packs/founding-saas-ui-states-v1/export",
                    "asset_template": "https://agent-svg-registry.vercel.app/api/reuse/{asset_id}"
                  },
                  "receipt_schema_url": "https://agent-svg-registry.vercel.app/schemas/export-receipt.schema.json",
                  "license_token_header": "x-agent-svg-license"
                }
              }
            }
          }
        }
      }
    },
    "/api/reuse/{asset_id}": {
      "get": {
        "summary": "Licensed export payloads",
        "operationId": "exportSvg",
        "description": "Requires a paid commercial license token in the x-agent-svg-license header or Bearer authorization.",
        "parameters": [
          {
            "name": "asset_id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "x-agent-svg-license",
            "in": "header",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "SVG, React, and inline HTML payloads"
          },
          "402": {
            "description": "Payment required before licensed export",
            "content": {
              "application/json": {
                "examples": {
                  "paymentRequired": {
                    "value": {
                      "error": "A valid commercial license token is required for exports.",
                      "license_required": true,
                      "payment_required": {
                        "type": "payment_required",
                        "price": { "amount": 0.5, "currency": "USD", "cadence": "one-time" },
                        "requires_human_approval": true,
                        "approval_prompt": "I found a paid-ready SVG asset review-auth-passkey-outline-01 in Agent SVG Registry. Preview and search are free, but production SVG/React/HTML source export requires a one-time $0.50 commercial license through Stripe Checkout. May I open https://agent-svg-registry.vercel.app/buy/launch?asset_id=review-auth-passkey-outline-01?",
                        "checkout_url": "https://agent-svg-registry.vercel.app/buy/launch?asset_id=review-auth-passkey-outline-01",
                        "checkout_intent_url": "https://agent-svg-registry.vercel.app/api/checkout-intents",
                        "license_token_header": "x-agent-svg-license"
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Asset is not cleared for commercial export"
          }
        }
      }
    },
    "/api/checkout-intents": {
      "post": {
        "summary": "Create checkout intent",
        "operationId": "createCheckoutSession",
        "description": "Creates a commercial-license checkout intent for a human-approved purchase. In production this returns a live Stripe Checkout URL for the requested plan.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "plan_id": {
                    "type": "string",
                    "default": "launch",
                    "enum": ["launch", "founding", "pro", "team-agent", "saas-pack", "enterprise"]
                  },
                  "asset_id": {
                    "type": "string",
                    "description": "Optional asset the buyer started from."
                  },
                  "pack_id": {
                    "type": "string",
                    "description": "Optional pack the buyer started from."
                  }
                }
              },
              "examples": {
                "launchLicense": {
                  "value": {
                    "plan_id": "launch",
                    "asset_id": "review-auth-passkey-outline-01"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Checkout URL and plan metadata"
          },
          "400": {
            "description": "Invalid checkout request"
          }
        }
      }
    },
    "/api/licenses/fulfill": {
      "get": {
        "summary": "Redeem paid Checkout Session",
        "operationId": "redeemLicense",
        "description": "Verifies a live paid Stripe Checkout Session and returns a signed commercial license token for export APIs. Unpaid sessions return HTTP 402.",
        "parameters": [
          {
            "name": "session_id",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Stripe Checkout Session ID returned to /license/success."
          }
        ],
        "responses": {
          "200": {
            "description": "Signed license token and receipt metadata"
          },
          "402": {
            "description": "Checkout Session exists but has not been paid"
          }
        }
      },
      "post": {
        "summary": "Redeem paid Checkout Session",
        "operationId": "redeemLicensePost",
        "description": "POST variant of license fulfillment for agents that prefer JSON bodies.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["session_id"],
                "properties": {
                  "session_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed license token and receipt metadata"
          },
          "402": {
            "description": "Checkout Session exists but has not been paid"
          }
        }
      }
    },
    "/api/stripe/webhook": {
      "post": {
        "summary": "Stripe webhook receiver",
        "operationId": "receiveStripeWebhook",
        "description": "Receives live Stripe checkout.session.completed events and verifies them with STRIPE_WEBHOOK_SECRET.",
        "responses": {
          "200": {
            "description": "Webhook received and, when paid, license fulfillment verified"
          },
          "400": {
            "description": "Invalid webhook signature or payload"
          },
          "501": {
            "description": "Webhook secret is not configured"
          }
        }
      }
    }
  }
}