{
  "openapi": "3.0.3",
  "info": {
    "title": "Classical Sync licensing API",
    "version": "1.0.0",
    "description": "Search and preview public-domain classical recordings (software-rendered masters). Purchase a Creator ($29), Commercial ($99), or Broadcast & Film ($499) master license via Stripe. Composition is public domain; this API licenses the sound recording only."
  },
  "servers": [
    { "url": "https://sync.thepodcastapp.dev" }
  ],
  "paths": {
    "/api/licensing/v1/health": {
      "get": { "summary": "Health", "responses": { "200": { "description": "ok" } } }
    },
    "/api/licensing/v1/tracks": {
      "get": {
        "summary": "Search catalog",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "mood", "in": "query", "schema": { "type": "string" } },
          { "name": "era", "in": "query", "schema": { "type": "string" } },
          { "name": "era_style", "in": "query", "schema": { "type": "string" } },
          { "name": "instrument", "in": "query", "schema": { "type": "string" } },
          { "name": "tempo", "in": "query", "schema": { "type": "string" } },
          { "name": "duration", "in": "query", "schema": { "type": "number" } },
          { "name": "max_duration_sec", "in": "query", "schema": { "type": "number" } }
        ],
        "responses": { "200": { "description": "ranked tracks with honest count" } }
      }
    },
    "/api/licensing/v1/search": {
      "get": { "summary": "Alias of GET /tracks", "responses": { "200": { "description": "ranked tracks" } } }
    },
    "/api/licensing/v1/tracks/{id}": {
      "get": {
        "summary": "Track detail",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "track" }, "404": { "description": "missing" } }
      }
    },
    "/api/licensing/v1/tracks/{id}/preview": {
      "get": {
        "summary": "Watermarked MP3 preview, up to 30 seconds",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "audio/mpeg" } }
      }
    },
    "/api/licensing/v1/tiers": {
      "get": { "summary": "License tiers", "responses": { "200": { "description": "tiers" } } }
    },
    "/api/licensing/v1/quotes": {
      "post": {
        "summary": "Quote Creator, Commercial, or Broadcast & Film. Optional upgrade_from_license_id credits the prior purchase.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["track_id", "tier"],
                "properties": {
                  "track_id": { "type": "string" },
                  "tier": { "type": "string", "enum": ["creator", "commercial", "broadcast"] },
                  "upgrade_from_license_id": { "type": "string" },
                  "licensee_email": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "quote" }, "400": { "description": "invalid upgrade or tier" } }
      }
    },
    "/api/licensing/v1/licenses": {
      "post": {
        "summary": "Purchase a master license via Stripe. Requires licensee_email and terms_accepted=true (clickwrap). Declined card returns 402.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["track_id", "tier", "licensee_name", "licensee_email", "terms_accepted", "payment"],
                "properties": {
                  "track_id": { "type": "string" },
                  "tier": { "type": "string", "enum": ["creator", "commercial", "broadcast"] },
                  "upgrade_from_license_id": { "type": "string" },
                  "licensee_name": { "type": "string" },
                  "licensee_email": { "type": "string" },
                  "project_name": { "type": "string" },
                  "terms_accepted": { "type": "boolean" },
                  "payment": {
                    "type": "object",
                    "properties": {
                      "provider": { "type": "string", "enum": ["stripe"] },
                      "payment_method": { "type": "string" },
                      "payment_intent_id": { "type": "string" }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "license issued" }, "400": { "description": "bad request" }, "402": { "description": "payment declined" } }
      }
    },
    "/api/licensing/v1/licenses/{id}": {
      "get": {
        "summary": "Public license verification (licensee name, no email)",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": { "200": { "description": "valid license" } }
      }
    },
    "/api/licensing/v1/licenses/{id}/pdf": {
      "get": { "summary": "License PDF", "responses": { "200": { "description": "application/pdf" } } }
    },
    "/api/licensing/v1/licenses/{id}/download": {
      "get": {
        "summary": "Signed WAV download",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "exp", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "audio/wav" }, "403": { "description": "bad token" } }
      }
    }
  }
}