# Categories endpoints

Categories are system-wide "buckets" of videos that provide the basic structure to navigate all videos in the system.

Categories are updated periodically as new videos are added and tagged by our team.

# List categories

This endpoint will return a paginated list of all categories in the system. This is useful to explore the library (as opposed to searching).

GET /categories

# Parameters

Param Description
page Page number. Number. Default: 0
page_size Number of videos per page. Number. Default: 20

# Response

{
  "page": 0,
  "pages": 2,
  "page_size": 20,
  "total": 25,
  "hits": [
    {
      "id": "8XEAeHkazU",
      "cover_video": "bJ7KveC5oR",
      "description": "Business and work videos are all about showing different work environments, from working at cafés to open-plan offices, working from home, developing, drawing, creating and more",
      "meta_description": "Business and work videos are all about showing different work environments, from working at cafés to open-plan offices, working from home, developing, drawing, creating and more | Coverr",
      "meta_title": "Free business and work stock video footage | Coverr",
      "name": "Business & Work",
      "slug": "business-work",
      "tags": [
        "business",
        "work",
        "office"
      ],
      "title": "Free business and work stock video footage",
      "cover_image": "https://storage.coverr.co/t/MrPvERg9QfKGZfck9kMpQKDia00j7DP8d",
      "order": 1
    }
  ]
}

# Get a category

Once you have a category you're interested in, you can fetch its details by accessing this endpoint using the collection slug or id as key:

GET /categories/:id

# Parameters

Param Description
id Category's id

# Response

{
  "id": "8XEAeHkazU",
  "cover_video": "bJ7KveC5oR",
  "description": "Business and work videos are all about showing different work environments, from working at cafés to open-plan offices, working from home, developing, drawing, creating and more",
  "meta_description": "Business and work videos are all about showing different work environments, from working at cafés to open-plan offices, working from home, developing, drawing, creating and more | Coverr",
  "meta_title": "Free business and work stock video footage | Coverr",
  "name": "Business & Work",
  "slug": "business-work",
  "tags": [
    "business",
    "work",
    "office"
  ],
  "title": "Free business and work stock video footage",
  "cover_image": "https://storage.coverr.co/t/MrPvERg9QfKGZfck9kMpQKDia00j7DP8d",
  "order": 1
}

# Get videos in a category

In order to list all videos in a specific category, just query this endpoint:

GET /categories/:id/videos

# Parameters

Param Description
page Page number. Number. Default: 1
page_size Number of videos per page. Number. Default: 20
query Search videos by query. String. Default: '', see a note below
sort_by How to sort videos. String. Valid values: date, popularity. Default: popularity
urls Add urls property in the response. Boolean. Default: false

# Response

{
  "page": 0,
  "pages": 50,
  "page_size": 20,
  "total": 3602,
  "hits": [
    {
      "id": "S1YbPl1NfI",
      "created_at": "2020-11-12T08:55:42.710Z",
      "updated_at": "2020-11-12T08:55:42.710Z",
      "title": "Cutting Wood Building Material With a Circular Electric Saw",
      "poster": "https://storage.coverr.co/p/QatsCWWAorI71sZ33DkHZREGWruZCHsg",
      "thumbnail": "https://storage.coverr.co/t/QatsCWWAorI71sZ33DkHZREGWruZCHsg",
      "description": "A close-up of the circular miter saw lowers and cuts off material",
      "is_vertical": false,
      "tags": [
        "circular saw",
        "miter saw",
        "saw"
      ],
      "downloads": 4,
      "views": 1,
      "published_at": "2020-11-15T09:27:18.578Z",
      "aspect_ratio": "16:9",
      "duration": 11.625,
      "max_height": 1152,
      "max_width": 2048,
      "urls": {
        "mp4": "https://storage.coverr.co/videos/QatsCWWAorI71sZ33DkHZREGWruZCHsg?token={token}",
        "mp4_preview": "https://storage.coverr.co/videos/QatsCWWAorI71sZ33DkHZREGWruZCHsg/preview?token={token}",
        "mp4_download": "https://storage.coverr.co/videos/QatsCWWAorI71sZ33DkHZREGWruZCHsg/download?token={token}&filename=Cutting Wood Building Material With a Circular Electric Saw"
      }
    }
  ]
}