{
  "openapi": "3.0.0",
  "info": {
    "title": "PixelVault Asset API",
    "description": "Compliance-cleared AI asset search and licensing for post production, editorial, and e-commerce. Every asset is sourced from licensed AI platforms (Adobe Firefly, Moonvalley), pre-cleared for commercial use, and delivered with an auto-generated usage agreement.",
    "version": "1.0.0",
    "contact": {
      "name": "PixelVault",
      "email": "outreach@pixelvaultai.com",
      "url": "https://pixelvault-ui.vercel.app"
    },
    "license": {
      "name": "Commercial",
      "url": "https://pixelvault-ui.vercel.app/docs"
    }
  },
  "servers": [
    {
      "url": "https://asset-registry-api-production.up.railway.app",
      "description": "PixelVault Production API"
    }
  ],
  "paths": {
    "/assets": {
      "get": {
        "operationId": "searchAssets",
        "summary": "Search for pre-cleared assets",
        "description": "Returns a list of compliance-cleared AI-generated assets matching the provided filters. All assets are sourced from licensed platforms and pre-cleared for the specified use case.",
        "parameters": [
          {
            "name": "use_case",
            "in": "query",
            "description": "License use case: 'Film & TV' for broadcast/streaming, 'Editorial' for news/publishing, 'Commercial' for brand/ecommerce",
            "schema": {
              "type": "string",
              "enum": ["Film & TV", "Editorial", "Commercial"]
            }
          },
          {
            "name": "type",
            "in": "query",
            "description": "Asset format filter",
            "schema": {
              "type": "string",
              "enum": ["video", "image"]
            }
          },
          {
            "name": "style",
            "in": "query",
            "description": "Visual style filter",
            "schema": { "type": "string" }
          },
          {
            "name": "max_price",
            "in": "query",
            "description": "Maximum price in USD",
            "schema": { "type": "number" }
          },
          {
            "name": "verified_only",
            "in": "query",
            "description": "Return only compliance-verified assets",
            "schema": { "type": "boolean" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of pre-cleared assets",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "assets": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Asset" }
                    },
                    "count": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/asset/{id}": {
      "get": {
        "operationId": "getAssetDetails",
        "summary": "Get full asset metadata and compliance documentation",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Asset ID",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Full asset details with compliance documentation",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AssetDetail" }
              }
            }
          },
          "404": {
            "description": "Asset not found"
          }
        }
      }
    },
    "/create-payment-intent": {
      "post": {
        "operationId": "createPaymentIntent",
        "summary": "Create a Stripe payment intent for asset licensing",
        "description": "Initiates the payment flow for licensing one or more approved assets. Returns a Stripe client secret for frontend payment completion.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["asset_id", "licensee_id"],
                "properties": {
                  "asset_id": {
                    "type": "integer",
                    "description": "ID of the asset to license"
                  },
                  "licensee_id": {
                    "type": "string",
                    "description": "Unique identifier for the licensee"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment intent created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "client_secret": { "type": "string" },
                    "payment_intent_id": { "type": "string" },
                    "amount": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/license": {
      "post": {
        "operationId": "verifyLicense",
        "summary": "Verify payment and issue license with signed delivery URL",
        "description": "After payment is completed, call this endpoint to verify and issue the license. Returns the usage agreement and a time-limited signed URL for full-resolution file delivery.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["payment_intent_id", "asset_id", "licensee_id"],
                "properties": {
                  "payment_intent_id": { "type": "string" },
                  "asset_id": { "type": "integer" },
                  "licensee_id": { "type": "string" },
                  "use_case_description": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "License issued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "license_id": { "type": "string" },
                    "signed_url": { "type": "string" },
                    "agreement_url": { "type": "string" },
                    "expires_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Asset": {
        "type": "object",
        "properties": {
          "asset_id": { "type": "string", "description": "Unique asset identifier" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "source_platform": {
            "type": "string",
            "enum": ["Adobe Firefly", "Moonvalley", "Runway"],
            "description": "Licensed AI platform that generated this asset"
          },
          "compliance_status": {
            "type": "string",
            "enum": ["Cleared", "Pending Review"],
            "description": "Compliance clearance status"
          },
          "license_type": {
            "type": "string",
            "enum": ["Film & TV Commercial", "Editorial", "Commercial Digital"]
          },
          "type": { "type": "string", "enum": ["video", "image"] },
          "duration": { "type": "string", "description": "Duration for video assets (e.g., '00:00:15')" },
          "resolution": { "type": "string", "description": "Resolution (e.g., 'ProRes 4K')" },
          "price": { "type": "number", "description": "License price in USD" },
          "visual_grammar": { "type": "string" },
          "emotional_tone": { "type": "string" },
          "color_profile": { "type": "string" },
          "narrative_function": { "type": "string" },
          "tags": {
            "type": "array",
            "items": { "type": "string" }
          },
          "thumbnail_url": { "type": "string" }
        }
      },
      "AssetDetail": {
        "allOf": [
          { "$ref": "#/components/schemas/Asset" },
          {
            "type": "object",
            "properties": {
              "compliance_docs": {
                "type": "object",
                "properties": {
                  "platform_license": { "type": "string" },
                  "training_data_documented": { "type": "boolean" },
                  "no_ip_ruling": { "type": "boolean" },
                  "commercial_use_confirmed": { "type": "boolean" }
                }
              },
              "signed_url_instructions": { "type": "string" }
            }
          }
        ]
      }
    }
  }
}