{
  "openapi": "3.1.0",
  "info": {
    "title": "YouTube API",
    "version": "1.0.0",
    "description": "Independent authenticated media resolve, Music song matching and asynchronous audio download API. Media URLs may expire and depend on the resolving server's IP. One shared API key grants access to the shared job list. Default per-minute quotas per TCP peer are 900 for single-job progress reads across all job IDs, 10 for job creation, 20 for file requests including HEAD and Range, and 60 for other authenticated operations. Authentication failures have a separate quota of 60. X-RateLimit-Limit reports the applicable limit."
  },
  "servers": [{"url": "/", "description": "Current API server"}],
  "security": [{"bearerAuth": []}],
  "tags": [{"name": "System"}, {"name": "Resolve"}, {"name": "Jobs"}],
  "paths": {
    "/health": {
      "get": {
        "tags": ["System"], "operationId": "health", "summary": "Public health check", "security": [],
        "responses": {"200": {"description": "Server is running", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "string", "examples": ["ok"]}, "version": {"type": "string"}}, "required": ["status", "version"]}}}}}
      }
    },
    "/docs": {
      "get": {
        "tags": ["System"], "operationId": "docs", "summary": "Local standalone HTML documentation", "security": [],
        "responses": {"200": {"description": "Documentation", "content": {"text/html": {"schema": {"type": "string"}}}}}
      }
    },
    "/openapi.json": {
      "get": {
        "tags": ["System"], "operationId": "openapi", "summary": "This OpenAPI document", "security": [],
        "responses": {"200": {"description": "OpenAPI JSON document", "content": {"application/json": {"schema": {"type": "object"}}}}}
      }
    },
    "/v1/tools": {
      "get": {
        "tags": ["System"], "operationId": "tools", "summary": "Check local media tools without exposing local paths",
        "responses": {
          "200": {"description": "Tool availability and version information", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object"}}, "required": ["data"]}}}},
          "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/Busy"}
        }
      }
    },
    "/v1/youtube/resolve": {
      "post": {
        "tags": ["Resolve"], "operationId": "resolveYouTube", "summary": "Resolve a single YouTube or YouTube Music audio source",
        "description": "Returns sanitized metadata and available audio-only formats. Signed media URLs are temporary and may be bound to the resolving server's IP or require the returned non-sensitive request headers. This is not a permanent public media URL service.",
        "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ResolveInput"}, "example": {"url": "https://music.youtube.com/watch?v=EIiC8gIAMgE"}}}},
        "responses": {
          "200": {"description": "Resolved audio metadata", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/ResolvedAudio"}}, "required": ["data"]}}}},
          "400": {"$ref": "#/components/responses/InvalidInput"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/Busy"}, "502": {"$ref": "#/components/responses/Upstream"}, "504": {"$ref": "#/components/responses/Timeout"}
        }
      }
    },
    "/v1/music/match": {
      "post": {
        "tags": ["Resolve"], "operationId": "matchMusic", "summary": "Match a platform link or song metadata to a Music song",
        "description": "Accepts supported single-track platform links or a title and artist with optional album, duration in seconds and ISRC. It returns a validated YouTube Music song, never an arbitrary video search result.",
        "requestBody": {"required": true, "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/LinkInput"}, {"$ref": "#/components/schemas/MetadataInput"}]}, "examples": {"link": {"value": {"url": "https://music.apple.com/cn/song/6781807531"}}, "metadata": {"value": {"title": "Hawk Em", "artist": "Pop Smoke", "album": "Meet The Woo", "duration": 118.8}}}}}},
        "responses": {
          "200": {"description": "A validated song source", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "object", "properties": {"metadata": {"$ref": "#/components/schemas/Metadata"}, "source": {"$ref": "#/components/schemas/Source"}}, "required": ["metadata", "source"]}}, "required": ["data"]}}}},
          "400": {"$ref": "#/components/responses/InvalidInput"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/Busy"}, "502": {"$ref": "#/components/responses/Upstream"}, "504": {"$ref": "#/components/responses/Timeout"}
        }
      }
    },
    "/v1/jobs": {
      "post": {
        "tags": ["Jobs"], "operationId": "createJob", "summary": "Create an asynchronous audio download job",
        "description": "The server controls the output directory. Supported platform single-track URLs are matched to YouTube Music before download. The shared queue has bounded capacity.",
        "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/JobInput"}, "example": {"url": "https://music.youtube.com/watch?v=EIiC8gIAMgE", "format": "mp3"}}}},
        "responses": {
          "202": {"description": "Accepted into the queue", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/JobEnvelope"}}}},
          "400": {"$ref": "#/components/responses/InvalidInput"}, "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/Busy"}
        }
      },
      "get": {
        "tags": ["Jobs"], "operationId": "listJobs", "summary": "List retained jobs shared by this API key",
        "responses": {
          "200": {"description": "Bounded retained job list", "content": {"application/json": {"schema": {"type": "object", "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Job"}}}, "required": ["data"]}}}},
          "401": {"$ref": "#/components/responses/Unauthorized"}, "429": {"$ref": "#/components/responses/Busy"}
        }
      }
    },
    "/v1/jobs/{id}": {
      "parameters": [{"$ref": "#/components/parameters/JobId"}],
      "get": {
        "tags": ["Jobs"], "operationId": "getJob", "summary": "Read job state and progress",
        "responses": {
          "200": {"description": "Current job view", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/JobEnvelope"}}}},
          "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/Busy"}
        }
      }
    },
    "/v1/jobs/{id}/cancel": {
      "parameters": [{"$ref": "#/components/parameters/JobId"}],
      "post": {
        "tags": ["Jobs"], "operationId": "cancelJob", "summary": "Cancel one pending or active job",
        "description": "Cancels processing, not a general filesystem delete operation. Other jobs are not cancelled.",
        "responses": {
          "200": {"description": "Job cancellation result", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/JobEnvelope"}}}},
          "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "429": {"$ref": "#/components/responses/Busy"}
        }
      }
    },
    "/v1/jobs/{id}/file": {
      "parameters": [{"$ref": "#/components/parameters/JobId"}],
      "get": {
        "tags": ["Jobs"], "operationId": "downloadFile", "summary": "Download a completed job's audio file",
        "description": "Requires the Bearer header even when file.downloadPath is known. Files expire according to JOB_TTL_HOURS; expiry refuses API access but does not delete stored media automatically.",
        "parameters": [{"name": "Range", "in": "header", "schema": {"type": "string"}, "example": "bytes=0-1023"}],
        "responses": {
          "200": {"$ref": "#/components/responses/AudioFile"},
          "206": {"description": "Requested byte range", "headers": {"Content-Range": {"schema": {"type": "string"}}, "Accept-Ranges": {"schema": {"type": "string", "const": "bytes"}}}, "content": {"application/octet-stream": {"schema": {"type": "string", "format": "binary"}}}},
          "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "410": {"$ref": "#/components/responses/Expired"}, "416": {"description": "The requested byte range cannot be satisfied"}, "429": {"$ref": "#/components/responses/Busy"}
        }
      },
      "head": {
        "tags": ["Jobs"], "operationId": "headFile", "summary": "Read completed audio file headers",
        "responses": {"200": {"description": "File headers, no body", "headers": {"Content-Length": {"schema": {"type": "integer"}}, "Accept-Ranges": {"schema": {"type": "string", "const": "bytes"}}}}, "401": {"$ref": "#/components/responses/Unauthorized"}, "404": {"$ref": "#/components/responses/NotFound"}, "409": {"$ref": "#/components/responses/Conflict"}, "410": {"$ref": "#/components/responses/Expired"}, "429": {"$ref": "#/components/responses/Busy"}}
      }
    }
  },
  "components": {
    "securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer", "description": "Shared API_KEY configured on the server"}},
    "parameters": {"JobId": {"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}}},
    "schemas": {
      "LinkInput": {"type": "object", "additionalProperties": false, "properties": {"url": {"type": "string", "format": "uri", "maxLength": 2048}}, "required": ["url"]},
      "ResolveInput": {"type": "object", "additionalProperties": false, "properties": {"url": {"type": "string", "format": "uri", "maxLength": 2048}, "formatId": {"type": "string", "maxLength": 80}}, "required": ["url"]},
      "MetadataInput": {"type": "object", "additionalProperties": false, "properties": {"title": {"type": "string", "minLength": 1, "maxLength": 200}, "artist": {"type": "string", "minLength": 1, "maxLength": 200}, "album": {"type": "string", "maxLength": 200}, "duration": {"type": "number", "exclusiveMinimum": 0, "maximum": 86400, "description": "Original recording duration in seconds"}, "isrc": {"type": "string", "maxLength": 20}}, "required": ["title", "artist"], "anyOf": [{"required": ["duration"]}, {"required": ["album"], "properties": {"album": {"minLength": 1}}}]},
      "Metadata": {"type": "object", "properties": {"title": {"type": "string"}, "artist": {"type": "string"}, "album": {"type": "string"}, "duration": {"type": ["number", "null"]}, "thumbnail": {"type": ["string", "null"], "format": "uri"}, "isrc": {"type": ["string", "null"]}, "source": {"type": "string"}, "sourceLabel": {"type": "string"}, "metadataSource": {"type": "string"}}, "required": ["title", "artist"]},
      "AudioFormat": {
        "type": "object",
        "properties": {
          "formatId": {"type": "string"}, "ext": {"type": "string"}, "codec": {"type": "string"}, "bitrate": {"type": ["number", "null"], "description": "kbps when supplied"}, "sampleRate": {"type": ["integer", "null"]}, "fileSize": {"type": ["integer", "null"]},
          "url": {"type": ["string", "null"], "format": "uri", "description": "Temporary signed media address, not the video page URL"},
          "expiresAt": {"type": ["string", "null"], "format": "date-time"}, "requestHeaders": {"type": "object", "additionalProperties": {"type": "string"}, "description": "Allowlisted non-sensitive headers only; no cookie or authorization values"}
        },
        "required": ["formatId", "ext", "codec"]
      },
      "ResolvedAudio": {
        "type": "object",
        "properties": {"videoId": {"type": "string"}, "url": {"type": "string", "format": "uri"}, "title": {"type": "string"}, "artist": {"type": "string"}, "album": {"type": "string"}, "duration": {"type": ["number", "null"]}, "thumbnail": {"type": ["string", "null"], "format": "uri"}, "audioFormats": {"type": "array", "items": {"$ref": "#/components/schemas/AudioFormat"}}, "selectedAudio": {"anyOf": [{"$ref": "#/components/schemas/AudioFormat"}, {"type": "null"}]}, "resolvedAt": {"type": "string", "format": "date-time"}},
        "required": ["videoId", "url", "title", "audioFormats", "selectedAudio", "resolvedAt"]
      },
      "Source": {"type": "object", "properties": {"id": {"type": "string"}, "url": {"type": "string", "format": "uri", "description": "Canonical song page, not a signed media URL"}, "title": {"type": "string"}, "artist": {"type": "string"}, "album": {"type": "string"}, "duration": {"type": ["number", "null"]}, "thumbnail": {"type": ["string", "null"], "format": "uri"}, "matchMethod": {"type": "string"}, "confidence": {"type": "string"}}, "required": ["id", "url", "title"]},
      "JobInput": {"type": "object", "additionalProperties": false, "properties": {"url": {"type": "string", "format": "uri", "maxLength": 2048}, "format": {"type": "string", "enum": ["mp3", "m4a", "best"], "default": "mp3"}}, "required": ["url"]},
      "Progress": {"type": "object", "properties": {"percent": {"type": "number", "minimum": 0, "maximum": 100}, "speed": {"type": ["string", "null"]}, "eta": {"type": ["string", "null"]}}},
      "JobFile": {"type": "object", "properties": {"name": {"type": "string"}, "size": {"type": "integer", "minimum": 0}, "downloadPath": {"type": "string", "description": "Authenticated relative file endpoint"}}, "required": ["name", "size", "downloadPath"]},
      "Job": {
        "type": "object",
        "properties": {
          "id": {"type": "string", "format": "uuid"}, "status": {"type": "string", "enum": ["queued", "resolving", "downloading", "completed", "failed", "cancelled", "expired"]},
          "progress": {"$ref": "#/components/schemas/Progress"}, "source": {"anyOf": [{"$ref": "#/components/schemas/Source"}, {"type": "null"}]}, "createdAt": {"type": "string", "format": "date-time"}, "updatedAt": {"type": "string", "format": "date-time"}, "finishedAt": {"type": ["string", "null"], "format": "date-time"},
          "error": {"anyOf": [{"$ref": "#/components/schemas/ErrorDetail"}, {"type": "null"}]}, "file": {"anyOf": [{"$ref": "#/components/schemas/JobFile"}, {"type": "null"}]}
        },
        "required": ["id", "status", "progress", "createdAt", "updatedAt"]
      },
      "JobEnvelope": {"type": "object", "properties": {"data": {"$ref": "#/components/schemas/Job"}}, "required": ["data"]},
      "ErrorDetail": {"type": "object", "properties": {"code": {"type": "string"}, "message": {"type": "string"}}, "required": ["code", "message"]},
      "ErrorEnvelope": {"type": "object", "properties": {"error": {"$ref": "#/components/schemas/ErrorDetail"}, "requestId": {"type": "string"}}, "required": ["error", "requestId"]}
    },
    "responses": {
      "InvalidInput": {"description": "Invalid URL, unsupported link or request body", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}},
      "Unauthorized": {"description": "Missing or invalid Bearer key", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}},
      "NotFound": {"description": "No validated source, job or file found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}},
      "Conflict": {"description": "The requested action is incompatible with the current job state", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}},
      "Expired": {"description": "The task's file access has expired", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}},
      "Busy": {"description": "Request quota, concurrency or capacity limit reached. RATE_LIMITED includes Retry-After in seconds.", "headers": {"Retry-After": {"schema": {"type": "string"}}, "X-RateLimit-Limit": {"description": "Requests allowed per minute for this group", "schema": {"type": "integer"}}}, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}},
      "Upstream": {"description": "Media tool or upstream platform failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}},
      "Timeout": {"description": "The upstream resolve operation timed out", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorEnvelope"}}}},
      "AudioFile": {"description": "Completed audio attachment", "headers": {"Content-Disposition": {"schema": {"type": "string"}}, "Content-Length": {"schema": {"type": "integer"}}, "Accept-Ranges": {"schema": {"type": "string", "const": "bytes"}}}, "content": {"application/octet-stream": {"schema": {"type": "string", "format": "binary"}}}}
    }
  }
}
