{
  "openapi": "3.1.0",
  "info": {
    "title": "Codec API",
    "version": "1.0.0",
    "description": "Read-only TMDB codec lookups. Public access, CORS enabled. Per IP: 30 requests/10 seconds, 120/minute, 3,000 lookups/UTC day; IPv6 addresses share a /64 allowance. Short limits are approximate Cloudflare edge limits. Movie and TV IDs are separate namespaces. TV defaults to S1E1. Features come from at most 3 title-matched advertised samples per source, not file probing. Coverage is incomplete; empty arrays mean unknown, not unsupported. No listing, bulk export, arbitrary SQL or live scrape endpoint."
  },
  "servers": [
    {
      "url": "https://api.raycodec.com"
    }
  ],
  "paths": {
    "/v1/movie/{id}": {
      "get": {
        "summary": "Get a movie by TMDB ID",
        "description": "Returns stored metadata and codec samples. A known title with unavailable samples returns 200 with status not_collected or no_matched_samples. No live scraping occurs.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2147483647
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Stored title and sample availability",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Lookup"
                }
              }
            }
          },
          "400": {
            "description": "Invalid ID or unsupported query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "TMDB title not in dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Burst, minute or daily allowance exceeded",
            "headers": {
              "Retry-After": {
                "description": "Seconds before retry",
                "schema": {
                  "type": "integer"
                }
              },
              "X-DailyLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Database or abuse protection unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tv/{id}": {
      "get": {
        "summary": "Get a TV show and its collected S1E1 sample",
        "description": "Returns stored metadata and codec samples. A known title with unavailable samples returns 200 with status not_collected or no_matched_samples. No live scraping occurs.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2147483647
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Stored title and sample availability",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Lookup"
                }
              }
            }
          },
          "400": {
            "description": "Invalid ID or unsupported query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "TMDB title not in dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Burst, minute or daily allowance exceeded",
            "headers": {
              "Retry-After": {
                "description": "Seconds before retry",
                "schema": {
                  "type": "integer"
                }
              },
              "X-DailyLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Database or abuse protection unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tv/{id}/season/{season}/episode/{episode}": {
      "get": {
        "summary": "Get a specific stored TV episode",
        "description": "Returns stored metadata and codec samples. A known title with unavailable samples returns 200 with status not_collected or no_matched_samples. No live scraping occurs.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2147483647
            }
          },
          {
            "name": "season",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            }
          },
          {
            "name": "episode",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Stored title and sample availability",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Lookup"
                }
              }
            }
          },
          "400": {
            "description": "Invalid ID or unsupported query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "TMDB title not in dataset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Burst, minute or daily allowance exceeded",
            "headers": {
              "Retry-After": {
                "description": "Seconds before retry",
                "schema": {
                  "type": "integer"
                }
              },
              "X-DailyLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Database or abuse protection unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "summary": "Worker health (does not probe D1)",
        "responses": {
          "200": {
            "description": "Worker is responding"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "Features": {
        "type": "object",
        "properties": {
          "video_codecs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "resolutions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "hdr_formats": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "audio_codecs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "audio_channels": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "audio_tracks": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "codec": {
                  "type": "string"
                },
                "channels": {
                  "type": "string"
                },
                "atmos": {
                  "const": true
                },
                "label": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Lookup": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "tmdb_id",
              "type",
              "title",
              "status",
              "sample_count",
              "features",
              "samples"
            ],
            "properties": {
              "tmdb_id": {
                "type": "integer"
              },
              "type": {
                "enum": [
                  "movie",
                  "tv"
                ]
              },
              "title": {
                "type": "string"
              },
              "imdb_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "episode": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "season": {
                    "type": "integer"
                  },
                  "number": {
                    "type": "integer"
                  },
                  "tmdb_id": {
                    "type": [
                      "integer",
                      "null"
                    ]
                  },
                  "title": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              },
              "status": {
                "enum": [
                  "available",
                  "no_matched_samples",
                  "not_collected"
                ]
              },
              "sample_count": {
                "type": "integer",
                "minimum": 0
              },
              "features": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/Features"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "samples": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Features"
                }
              }
            }
          }
        }
      }
    }
  }
}