openapi: 3.0.3
info:
  title: TorrentControl API
  description: |
    Public API for accessing movie and series content with their associated torrents.

    ## Rate Limiting
    This API is rate limited to **60 requests per minute per IP address**.

    ## Usage Policy
    This API is provided for public use. Please use it responsibly and avoid abusive behavior.
    Excessive usage may result in your IP being temporarily blocked.

  version: 1.0.0
  contact:
    name: API Support
    url: https://torrentcontrol.example.com
servers:
  - url: /api/v1
    description: API v1

paths:
  /contents:
    get:
      summary: List all contents
      description: Get a paginated list of movies and series
      operationId: getContents
      tags:
        - Contents
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: per_page
          in: query
          description: Number of items per page (max 100)
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: type
          in: query
          description: Filter by content type
          required: false
          schema:
            type: string
            enum: [movie, series]
        - name: search
          in: query
          description: Search term for content title
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContentSummary'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
        '429':
          description: Too many requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /contents/{id}:
    get:
      summary: Get content details
      description: Get detailed information about a specific content including all torrents
      operationId: getContentById
      tags:
        - Contents
      parameters:
        - name: id
          in: path
          description: Content ID
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/ContentDetailed'
              examples:
                movie:
                  summary: Movie example
                  value:
                    success: true
                    data:
                      id: 1
                      title: "Inception"
                      slug: "inception"
                      description: "A thief who steals corporate secrets through the use of dream-sharing technology..."
                      year: 2010
                      poster_url: "https://image.tmdb.org/t/p/w500/poster.jpg"
                      imdb_id: "tt1375666"
                      tmdb_id: "27205"
                      type: "movie"
                      rating: 8.8
                      created_at: "2024-01-15T10:30:00.000000Z"
                      updated_at: "2024-01-15T10:30:00.000000Z"
                      torrents:
                        - id: 1
                          provider: "MejorTorrent"
                          magnet_uri: "magnet:?xt=urn:btih:1234567890abcdef..."
                          file_name: "Inception.2010.1080p.BluRay.x264.mkv"
                          quality: "1080p"
                          language: "es"
                          size_in_mb: 2048
                          seeders: 150
                          leechers: 20
                          created_at: "2024-01-15T10:30:00.000000Z"
                          updated_at: "2024-01-15T10:30:00.000000Z"
                        - id: 2
                          provider: "EliteTorrent"
                          magnet_uri: "magnet:?xt=urn:btih:abcdef1234567890..."
                          file_name: "Inception.2010.720p.BluRay.x264.mkv"
                          quality: "720p"
                          language: "en"
                          size_in_mb: 1024
                          seeders: 80
                          leechers: 10
                          created_at: "2024-01-15T11:00:00.000000Z"
                          updated_at: "2024-01-15T11:00:00.000000Z"
                series:
                  summary: Series example
                  value:
                    success: true
                    data:
                      id: 42
                      title: "Breaking Bad"
                      slug: "breaking-bad"
                      description: "A high school chemistry teacher turned methamphetamine producer..."
                      year: 2008
                      poster_url: "https://image.tmdb.org/t/p/w500/series_poster.jpg"
                      imdb_id: "tt0903747"
                      tmdb_id: "1396"
                      type: "series"
                      rating: 9.5
                      created_at: "2024-01-10T08:00:00.000000Z"
                      updated_at: "2024-01-10T08:00:00.000000Z"
                      seasons:
                        - id: 1
                          season_number: 1
                          episodes:
                            - id: 1
                              episode_number: 1
                              title: "Pilot"
                              torrents:
                                - id: 101
                                  provider: "MejorTorrent"
                                  magnet_uri: "magnet:?xt=urn:btih:series123456..."
                                  file_name: "Breaking.Bad.S01E01.1080p.WEB-DL.mkv"
                                  quality: "1080p"
                                  language: "es"
                                  size_in_mb: 1500
                                  seeders: 200
                                  leechers: 15
                                  created_at: "2024-01-10T08:30:00.000000Z"
                                  updated_at: "2024-01-10T08:30:00.000000Z"
                                - id: 102
                                  provider: "EliteTorrent"
                                  magnet_uri: "magnet:?xt=urn:btih:series654321..."
                                  file_name: "Breaking.Bad.S01E01.720p.WEB-DL.mkv"
                                  quality: "720p"
                                  language: "en"
                                  size_in_mb: 800
                                  seeders: 120
                                  leechers: 8
                                  created_at: "2024-01-10T09:00:00.000000Z"
                                  updated_at: "2024-01-10T09:00:00.000000Z"
                            - id: 2
                              episode_number: 2
                              title: "Cat's in the Bag..."
                              torrents:
                                - id: 103
                                  provider: "MejorTorrent"
                                  magnet_uri: "magnet:?xt=urn:btih:episode2abc..."
                                  file_name: "Breaking.Bad.S01E02.1080p.WEB-DL.mkv"
                                  quality: "1080p"
                                  language: "es"
                                  size_in_mb: 1450
                                  seeders: 180
                                  leechers: 12
                                  created_at: "2024-01-10T10:00:00.000000Z"
                                  updated_at: "2024-01-10T10:00:00.000000Z"
                        - id: 2
                          season_number: 2
                          episodes:
                            - id: 8
                              episode_number: 1
                              title: "Seven Thirty-Seven"
                              torrents:
                                - id: 201
                                  provider: "MejorTorrent"
                                  magnet_uri: "magnet:?xt=urn:btih:season2ep1..."
                                  file_name: "Breaking.Bad.S02E01.1080p.WEB-DL.mkv"
                                  quality: "1080p"
                                  language: "es"
                                  size_in_mb: 1480
                                  seeders: 190
                                  leechers: 14
                                  created_at: "2024-01-11T08:00:00.000000Z"
                                  updated_at: "2024-01-11T08:00:00.000000Z"
        '404':
          description: Content not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /torrents:
    get:
      summary: List all torrents in flat structure
      description: |
        Get a paginated list of all torrents with embedded content information in a flat structure.
        This endpoint returns torrents for both movies and TV series episodes, with all relevant
        information at the root level (no nested arrays). This makes it easier to process with
        tools like Cardigann YAML parsers.
      operationId: getTorrentsFlat
      tags:
        - Torrents
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: per_page
          in: query
          description: Number of items per page (max 100)
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
        - name: type
          in: query
          description: Filter by content type
          required: false
          schema:
            type: string
            enum: [movie, series]
        - name: search
          in: query
          description: Search term for content title
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      oneOf:
                        - $ref: '#/components/schemas/FlatMovieTorrent'
                        - $ref: '#/components/schemas/FlatSeriesTorrent'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
              examples:
                movie:
                  summary: Movie torrent example
                  value:
                    success: true
                    data:
                      - id: 1
                        provider: "MejorTorrent"
                        magnet_uri: "magnet:?xt=urn:btih:1234567890abcdef..."
                        file_name: "Inception.2010.1080p.BluRay.x264.mkv"
                        quality: "1080p"
                        language: "es"
                        size_in_mb: 2048
                        seeders: 150
                        leechers: 20
                        created_at: "2024-01-15T10:30:00.000000Z"
                        updated_at: "2024-01-15T10:30:00.000000Z"
                        title: "Inception"
                        slug: "inception"
                        description: "A thief who steals corporate secrets..."
                        year: 2010
                        poster_url: "https://image.tmdb.org/t/p/w500/poster.jpg"
                        imdb_id: "tt1375666"
                        tmdb_id: "27205"
                        type: "movie"
                        rating: 8.8
                        content_id: 1
                      - id: 2
                        provider: "EliteTorrent"
                        magnet_uri: "magnet:?xt=urn:btih:abcdef1234567890..."
                        file_name: "Inception.2010.720p.BluRay.x264.mkv"
                        quality: "720p"
                        language: "en"
                        size_in_mb: 1024
                        seeders: 80
                        leechers: 10
                        created_at: "2024-01-15T11:00:00.000000Z"
                        updated_at: "2024-01-15T11:00:00.000000Z"
                        title: "Inception"
                        slug: "inception"
                        description: "A thief who steals corporate secrets..."
                        year: 2010
                        poster_url: "https://image.tmdb.org/t/p/w500/poster.jpg"
                        imdb_id: "tt1375666"
                        tmdb_id: "27205"
                        type: "movie"
                        rating: 8.8
                        content_id: 1
                    meta:
                      current_page: 1
                      last_page: 25
                      per_page: 50
                      total: 1250
                    links:
                      first: "/api/v1/torrents?page=1"
                      last: "/api/v1/torrents?page=25"
                      prev: null
                      next: "/api/v1/torrents?page=2"
                series:
                  summary: Series episode torrent example
                  value:
                    success: true
                    data:
                      - id: 101
                        provider: "MejorTorrent"
                        magnet_uri: "magnet:?xt=urn:btih:series123456..."
                        file_name: "Breaking.Bad.S01E01.1080p.WEB-DL.mkv"
                        quality: "1080p"
                        language: "es"
                        size_in_mb: 1500
                        seeders: 200
                        leechers: 15
                        created_at: "2024-01-10T08:30:00.000000Z"
                        updated_at: "2024-01-10T08:30:00.000000Z"
                        title: "Breaking Bad"
                        slug: "breaking-bad"
                        description: "A high school chemistry teacher..."
                        year: 2008
                        poster_url: "https://image.tmdb.org/t/p/w500/series_poster.jpg"
                        imdb_id: "tt0903747"
                        tmdb_id: "1396"
                        type: "series"
                        rating: 9.5
                        content_id: 42
                        season_number: 1
                        episode_number: 1
                        episode_title: "Pilot"
                        episode_id: 1
                        season_id: 1
                      - id: 102
                        provider: "EliteTorrent"
                        magnet_uri: "magnet:?xt=urn:btih:series654321..."
                        file_name: "Breaking.Bad.S01E01.720p.WEB-DL.mkv"
                        quality: "720p"
                        language: "en"
                        size_in_mb: 800
                        seeders: 120
                        leechers: 8
                        created_at: "2024-01-10T09:00:00.000000Z"
                        updated_at: "2024-01-10T09:00:00.000000Z"
                        title: "Breaking Bad"
                        slug: "breaking-bad"
                        description: "A high school chemistry teacher..."
                        year: 2008
                        poster_url: "https://image.tmdb.org/t/p/w500/series_poster.jpg"
                        imdb_id: "tt0903747"
                        tmdb_id: "1396"
                        type: "series"
                        rating: 9.5
                        content_id: 42
                        season_number: 1
                        episode_number: 1
                        episode_title: "Pilot"
                        episode_id: 1
                        season_id: 1
                    meta:
                      current_page: 1
                      last_page: 18
                      per_page: 50
                      total: 900
                    links:
                      first: "/api/v1/torrents?page=1"
                      last: "/api/v1/torrents?page=18"
                      prev: null
                      next: "/api/v1/torrents?page=2"
        '429':
          description: Too many requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    ContentSummary:
      type: object
      properties:
        id:
          type: integer
          example: 1
        title:
          type: string
          example: "Inception"
        slug:
          type: string
          example: "inception"
        description:
          type: string
          nullable: true
          example: "A thief who steals corporate secrets..."
        year:
          type: integer
          nullable: true
          example: 2010
        poster_url:
          type: string
          nullable: true
          example: "https://image.tmdb.org/t/p/w500/poster.jpg"
        imdb_id:
          type: string
          nullable: true
          example: "tt1375666"
        tmdb_id:
          type: string
          nullable: true
          example: "27205"
        type:
          type: string
          enum: [movie, series]
          example: "movie"
        rating:
          type: number
          format: float
          nullable: true
          example: 8.8
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    ContentDetailed:
      allOf:
        - $ref: '#/components/schemas/ContentSummary'
        - type: object
          properties:
            torrents:
              type: array
              description: Available for movies only
              items:
                $ref: '#/components/schemas/Torrent'
            seasons:
              type: array
              description: Available for series only
              items:
                $ref: '#/components/schemas/Season'

    Season:
      type: object
      properties:
        id:
          type: integer
          example: 1
        season_number:
          type: integer
          example: 1
        episodes:
          type: array
          items:
            $ref: '#/components/schemas/Episode'

    Episode:
      type: object
      properties:
        id:
          type: integer
          example: 1
        episode_number:
          type: integer
          example: 1
        title:
          type: string
          nullable: true
          example: "Pilot"
        torrents:
          type: array
          items:
            $ref: '#/components/schemas/Torrent'

    Torrent:
      type: object
      properties:
        id:
          type: integer
          example: 1
        provider:
          type: string
          example: "MejorTorrent"
        magnet_uri:
          type: string
          example: "magnet:?xt=urn:btih:..."
        file_name:
          type: string
          nullable: true
          example: "Inception.2010.1080p.BluRay.x264.mkv"
        quality:
          type: string
          example: "1080p"
        language:
          type: string
          example: "es"
        size_in_mb:
          type: integer
          nullable: true
          example: 2048
        seeders:
          type: integer
          example: 150
        leechers:
          type: integer
          example: 20
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
          example: 1
        last_page:
          type: integer
          example: 10
        per_page:
          type: integer
          example: 20
        total:
          type: integer
          example: 200

    PaginationLinks:
      type: object
      properties:
        first:
          type: string
          example: "/api/v1/contents?page=1"
        last:
          type: string
          example: "/api/v1/contents?page=10"
        prev:
          type: string
          nullable: true
          example: null
        next:
          type: string
          nullable: true
          example: "/api/v1/contents?page=2"

    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Content not found"

    FlatMovieTorrent:
      type: object
      description: Flat torrent structure for movies with embedded content information
      properties:
        id:
          type: integer
          description: Torrent ID
          example: 1
        provider:
          type: string
          description: Torrent provider name
          example: "MejorTorrent"
        magnet_uri:
          type: string
          description: Magnet link URI
          example: "magnet:?xt=urn:btih:1234567890abcdef..."
        file_name:
          type: string
          nullable: true
          description: Torrent file name
          example: "Inception.2010.1080p.BluRay.x264.mkv"
        quality:
          type: string
          description: Video quality
          example: "1080p"
        language:
          type: string
          description: Audio language code
          example: "es"
        size_in_mb:
          type: integer
          nullable: true
          description: File size in megabytes
          example: 2048
        seeders:
          type: integer
          description: Number of seeders
          example: 150
        leechers:
          type: integer
          description: Number of leechers
          example: 20
        created_at:
          type: string
          format: date-time
          description: Torrent creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Torrent last update timestamp
        title:
          type: string
          description: Movie title
          example: "Inception"
        slug:
          type: string
          description: URL-friendly movie slug
          example: "inception"
        description:
          type: string
          nullable: true
          description: Movie description
          example: "A thief who steals corporate secrets through the use of dream-sharing technology..."
        year:
          type: integer
          nullable: true
          description: Release year
          example: 2010
        poster_url:
          type: string
          nullable: true
          description: Movie poster image URL
          example: "https://image.tmdb.org/t/p/w500/poster.jpg"
        imdb_id:
          type: string
          nullable: true
          description: IMDb identifier
          example: "tt1375666"
        tmdb_id:
          type: string
          nullable: true
          description: TMDB identifier
          example: "27205"
        type:
          type: string
          description: Content type (always "movie" for this schema)
          enum: [movie]
          example: "movie"
        rating:
          type: number
          format: float
          nullable: true
          description: Movie rating
          example: 8.8
        content_id:
          type: integer
          description: Content ID reference
          example: 1

    FlatSeriesTorrent:
      type: object
      description: Flat torrent structure for TV series episodes with embedded content and episode information
      properties:
        id:
          type: integer
          description: Torrent ID
          example: 101
        provider:
          type: string
          description: Torrent provider name
          example: "MejorTorrent"
        magnet_uri:
          type: string
          description: Magnet link URI
          example: "magnet:?xt=urn:btih:series123456..."
        file_name:
          type: string
          nullable: true
          description: Torrent file name
          example: "Breaking.Bad.S01E01.1080p.WEB-DL.mkv"
        quality:
          type: string
          description: Video quality
          example: "1080p"
        language:
          type: string
          description: Audio language code
          example: "es"
        size_in_mb:
          type: integer
          nullable: true
          description: File size in megabytes
          example: 1500
        seeders:
          type: integer
          description: Number of seeders
          example: 200
        leechers:
          type: integer
          description: Number of leechers
          example: 15
        created_at:
          type: string
          format: date-time
          description: Torrent creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Torrent last update timestamp
        title:
          type: string
          description: Series title
          example: "Breaking Bad"
        slug:
          type: string
          description: URL-friendly series slug
          example: "breaking-bad"
        description:
          type: string
          nullable: true
          description: Series description
          example: "A high school chemistry teacher turned methamphetamine producer..."
        year:
          type: integer
          nullable: true
          description: Series premiere year
          example: 2008
        poster_url:
          type: string
          nullable: true
          description: Series poster image URL
          example: "https://image.tmdb.org/t/p/w500/series_poster.jpg"
        imdb_id:
          type: string
          nullable: true
          description: IMDb identifier
          example: "tt0903747"
        tmdb_id:
          type: string
          nullable: true
          description: TMDB identifier
          example: "1396"
        type:
          type: string
          description: Content type (always "series" for this schema)
          enum: [series]
          example: "series"
        rating:
          type: number
          format: float
          nullable: true
          description: Series rating
          example: 9.5
        content_id:
          type: integer
          description: Content ID reference
          example: 42
        season_number:
          type: integer
          description: Season number
          example: 1
        episode_number:
          type: integer
          description: Episode number within the season
          example: 1
        episode_title:
          type: string
          nullable: true
          description: Episode title
          example: "Pilot"
        episode_id:
          type: integer
          description: Episode ID reference
          example: 1
        season_id:
          type: integer
          description: Season ID reference
          example: 1

tags:
  - name: Contents
    description: Operations related to movies and series content
  - name: Torrents
    description: Operations for accessing torrents in flat structure without nesting
