Drop TV API

Appearance

SECTION 5 — SHOWS ​

21. GET /shows ​

Get all shows with filtering and sorting.

Query Parameters ​

ParameterTypeRequiredDefaultDescription
categorystringNoallcomedy, music, lifestyle, sports, film_tv, art_design, gaming, education
sortstringNomost_popularmost_popular, newest, trending
sectionstringNoallnew_releases, featured, all
is_newbooleanNo—Filter new releases only
is_featuredbooleanNo—Filter featured only
ratingstringNo—TV-G, TV-PG, TV-14, TV-MA
pageintNo1Page number
limitintNo20Results per page

Request ​

http
GET /shows?category=comedy&sort=most_popular&section=all&page=1&limit=20

Response 200 OK ​

json
{
  "status": "success",
  "data": {
    "total": 18,
    "page": 1,
    "limit": 20,
    "total_pages": 1,
    "filters_applied": {
      "category": "comedy",
      "sort": "most_popular",
      "section": "all",
      "rating": null,
      "is_new": null,
      "is_featured": null
    },
    "shows": [
      {
        "show_id": "show_001",
        "title": "The DL Hughley Show",
        "thumbnail_url": "https://cdn.droptv.com/shows/show_001/thumb.jpg",
        "thumbnail_color": "#6B4FBB",
        "category": "comedy",
        "creator": {
          "id": "creator_002",
          "name": "DL Hughley",
          "is_verified": true
        },
        "seasons": 5,
        "rating": "TV-14",
        "tags": ["new", "featured"],
        "is_new": true,
        "is_featured": true,
        "total_views": 2000000,
        "total_views_formatted": "2M",
        "channel_url": "/shows/the-dl-hughley-show"
      }
    ]
  }
}

22. GET /shows/new-releases ​

Get freshly added shows.

Query Parameters ​

ParameterTypeRequiredDefaultDescription
categorystringNoallFilter by category
limitintNo10Results per page
pageintNo1Page number

Request ​

http
GET /shows/new-releases?category=all&limit=10&page=1

Response 200 OK ​

json
{
  "status": "success",
  "data": {
    "section_title": "New Releases",
    "section_subtitle": "Fresh content just added",
    "total": 7,
    "page": 1,
    "limit": 10,
    "shows": [
      {
        "show_id": "show_001",
        "title": "Chris Spencer Presents",
        "thumbnail_url": "https://cdn.droptv.com/shows/show_001/thumb.jpg",
        "thumbnail_color": "#E8A838",
        "category": "comedy",
        "creator": { "id": "creator_001", "name": "Chris Spencer", "is_verified": true },
        "seasons": 3,
        "rating": "TV-14",
        "tags": ["new", "featured"],
        "is_new": true,
        "is_featured": true,
        "channel_url": "/shows/chris-spencer-presents"
      }
    ]
  }
}

23. GET /shows/featured ​

Get editor's pick featured shows.

Query Parameters ​

ParameterTypeRequiredDefaultDescription
categorystringNoallFilter by category
limitintNo10Results to return
pageintNo1Page number

Request ​

http
GET /shows/featured?category=all&limit=10&page=1

Response 200 OK ​

json
{
  "status": "success",
  "data": {
    "section_title": "Featured Shows",
    "section_subtitle": "Editor's picks",
    "total": 10,
    "shows": [
      {
        "show_id": "show_008",
        "title": "Go Big or Go Home",
        "thumbnail_url": "https://cdn.droptv.com/shows/show_008/thumb.jpg",
        "thumbnail_color": "#E84343",
        "category": "comedy",
        "creator": { "id": "creator_001", "name": "Chris Spencer", "is_verified": true },
        "seasons": 2,
        "rating": "TV-PG",
        "tags": ["featured"],
        "is_new": false,
        "is_featured": true,
        "channel_url": "/shows/go-big-or-go-home"
      }
    ]
  }
}

24. GET /shows/search ​

Search shows by title or keyword.

Query Parameters ​

ParameterTypeRequiredDefaultDescription
qstringYes—Search query
categorystringNoallFilter by category
sortstringNomost_popularmost_popular, newest, trending
ratingstringNo—TV-G, TV-PG, TV-14, TV-MA
is_newbooleanNo—Filter new only
is_featuredbooleanNo—Filter featured only
pageintNo1Page number
limitintNo20Results per page

Request ​

http
GET /shows/search?q=comedy&category=comedy&sort=newest&rating=TV-14&is_new=true&page=1&limit=20

Response 200 OK ​

json
{
  "status": "success",
  "data": {
    "query": "comedy",
    "total": 5,
    "page": 1,
    "limit": 20,
    "total_pages": 1,
    "shows": [
      {
        "show_id": "show_001",
        "title": "Chris Spencer Presents",
        "thumbnail_url": "https://cdn.droptv.com/shows/show_001/thumb.jpg",
        "category": "comedy",
        "creator": { "id": "creator_001", "name": "Chris Spencer", "is_verified": true },
        "seasons": 3,
        "rating": "TV-14",
        "tags": ["new", "featured"],
        "is_new": true,
        "is_featured": true,
        "channel_url": "/shows/chris-spencer-presents"
      }
    ]
  }
}

Errors ​

json
{
  "status": "error",
  "code": 400,
  "message": "Search query 'q' is required"
}

25. GET /shows/categories ​

Get all show categories with counts.

Request ​

http
GET /shows/categories

Response 200 OK ​

json
{
  "status": "success",
  "data": {
    "categories": [
      { "id": "comedy", "label": "Comedy", "icon": "comedy-icon", "show_count": 8 },
      { "id": "music", "label": "Music", "icon": "music-icon", "show_count": 3 },
      { "id": "lifestyle", "label": "Lifestyle", "icon": "lifestyle-icon", "show_count": 2 },
      { "id": "sports", "label": "Sports", "icon": "sports-icon", "show_count": 2 },
      { "id": "film_tv", "label": "Film & TV", "icon": "film-icon", "show_count": 1 },
      { "id": "art_design", "label": "Art & Design", "icon": "art-icon", "show_count": 1 },
      { "id": "gaming", "label": "Gaming", "icon": "gaming-icon", "show_count": 1 },
      { "id": "education", "label": "Education", "icon": "education-icon", "show_count": 0 }
    ]
  }
}

26. GET /shows/ratings ​

Get all valid content rating options.

Request ​

http
GET /shows/ratings

Response 200 OK ​

json
{
  "status": "success",
  "data": {
    "ratings": [
      { "id": "TV-G", "label": "TV-G", "description": "General Audience" },
      { "id": "TV-PG", "label": "TV-PG", "description": "Parental Guidance Suggested" },
      { "id": "TV-14", "label": "TV-14", "description": "Parents Strongly Cautioned" },
      { "id": "TV-MA", "label": "TV-MA", "description": "Mature Audience Only" }
    ]
  }
}

27. GET /shows/:id ​

Get single show full detail including episodes.

Path Parameters ​

ParameterTypeRequiredDescription
idstringYesShow ID

Request ​

http
GET /shows/show_001

Response 200 OK ​

json
{
  "status": "success",
  "data": {
    "show_id": "show_001",
    "title": "Chris Spencer Presents",
    "description": "Stand-up specials and comedy showcases hosted by Chris Spencer.",
    "thumbnail_url": "https://cdn.droptv.com/shows/show_001/thumb.jpg",
    "thumbnail_color": "#E8A838",
    "category": "comedy",
    "creator": {
      "id": "creator_001",
      "name": "Chris Spencer",
      "avatar_url": null,
      "is_verified": true,
      "channel_url": "/creators/chris-spencer"
    },
    "seasons": 3,
    "rating": "TV-14",
    "tags": ["new", "featured"],
    "is_new": true,
    "is_featured": true,
    "total_views": 1500000,
    "total_views_formatted": "1.5M",
    "episodes": [
      {
        "episode_id": "ep_001",
        "season": 1,
        "episode_number": 1,
        "title": "Pilot",
        "duration_seconds": 1800,
        "duration_formatted": "30m",
        "thumbnail_url": "https://cdn.droptv.com/episodes/ep_001/thumb.jpg",
        "air_date": "2023-01-15T00:00:00Z",
        "stream_url": "https://cdn.droptv.com/episodes/ep_001/stream.m3u8"
      }
    ],
    "channel_url": "/shows/chris-spencer-presents",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2024-10-01T00:00:00Z"
  }
}

Errors ​

json
{
  "status": "error",
  "code": 404,
  "message": "Show not found"
}