Videos API

The Videos API is the primary endpoint for retrieving video content. It supports powerful filtering, sorting, and tagging capabilities.

Retrieves a paginated list of videos. This endpoint is highly flexible and accepts several query parameters to refine the results. The response contains an array of VideoSummary Objects.

GET /videos

Query Parameters

Name	Type	Description
`path`	`string`	Optional. Filters videos to a specific collection path, e.g., `root/movies`.
`filters`	`object`	Optional. Filters by metadata. See Filtering Examples below for syntax.
`tags`	`string`	Optional. A comma-separated list of tags to filter by (e.g., `laravel,api`). Finds videos with ALL specified tags.
`sort`	`string`	Optional. Sorts the results. Use a `-` prefix for descending order. Allowed fields: `created_at`, `title`, `duration_in_seconds`. Default: `-created_at`.
`per_page`	`integer`	Optional. Number of results per page. Default: `15`, Max: `100`.

Filtering Examples

The filters parameter is the most powerful feature. The syntax is filters[field_name][operator]=value.

Filter by Collection Path

This finds all videos inside the education/php folder.


GET /api/client/v1/videos?path=root/education/php

Filter by a Single Metadata Field (Equals)

This finds all videos where the genre is ‘Action’, case-insensitively. Using a direct value is a shortcut for the eq (equals) operator.


GET /api/client/v1/videos?filters[genre]=Action

Filter by Path and Metadata

This finds all ‘beginner’ videos specifically within the ‘fitness/yoga’ collection.


GET /api/client/v1/videos?path=root/fitness/yoga&filters[difficulty]=beginner

Filter by “Greater Than” (`gt`)

This finds all videos longer than 10 minutes (600 seconds).


GET /api/client/v1/videos?filters[duration_in_seconds][gt]=600

Filter by “Less Than or Equal To” (`lte`)

This finds all videos with a rating of 3 or less.


GET /api/client/v1/videos?filters[rating][lte]=3

Filter by “In a List” (`in`)

This finds all videos where the difficulty is either ‘beginner’ OR ‘intermediate’. It works for both single-select and multi-select fields.


GET /api/client/v1/videos?filters[difficulty][in]=beginner,intermediate

Filter by “Not Equal To” (`neq`)

This finds all videos where the presenter is not ‘Jane Doe’.


GET /api/client/v1/videos?filters[presenter][neq]=Jane Doe

Sorting and Tagging Examples

Filter by Tags

This finds all videos tagged with BOTH ‘yoga’ AND ‘beginner’.


GET /api/client/v1/videos?tags=yoga,beginner

Sort by Title (Ascending)

This lists all videos sorted alphabetically by title.


GET /api/client/v1/videos?sort=title

Sort by Date (Descending)

This lists all videos with the newest ones first. This is the default behavior and is equivalent to not providing a sort parameter.


GET /api/client/v1/videos?sort=-created_at

Full Response: `GET /videos`

This is a complete, un-truncated example of a paginated response.

Response: 200 OK


{
  "data": [
    {
      "id": "9c1a9e3e-6c9b-4f8a-8e2d-9b3c1d4e0f6a",
      "title": "Advanced API Design in Laravel",
      "description": "A deep dive into building robust APIs.",
      "duration_in_seconds": 3620,
      "thumbnail_url": "https://your-cdn.com/path/to/thumb1.jpg",
      "created_at": "2024-08-10T12:00:00Z",
      "metadata": {
        "difficulty": "advanced",
        "presenter": "Jane Doe"
      }
    },
    {
      "id": "9c1a9e3e-7d8c-5g9b-9f1c-8a2b0c3d9e8f",
      "title": "Introduction to Yoga",
      "description": "A beginner's guide to basic yoga poses.",
      "duration_in_seconds": 1800,
      "thumbnail_url": "https://your-cdn.com/path/to/thumb2.jpg",
      "created_at": "2024-08-09T10:00:00Z",
      "metadata": {
        "difficulty": "beginner",
        "presenter": "John Smith"
      }
    }
  ],
  "links": {
    "first": "https://your-app.com/api/client/v1/videos?page=1",
    "last": "https://your-app.com/api/client/v1/videos?page=5",
    "prev": null,
    "next": "https://your-app.com/api/client/v1/videos?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://your-app.com/api/client/v1/videos?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://your-app.com/api/client/v1/videos?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "https://your-app.com/api/client/v1/videos?page=3",
        "label": "3",
        "active": false
      },
      {
        "url": "https://your-app.com/api/client/v1/videos?page=4",
        "label": "4",
        "active": false
      },
      {
        "url": "https://your-app.com/api/client/v1/videos?page=5",
        "label": "5",
        "active": false
      },
      {
        "url": "https://your-app.com/api/client/v1/videos?page=2",
        "label": "Next &raquo;",
        "active": true
      }
    ],
    "path": "https://your-app.com/api/client/v1/videos",
    "per_page": 2,
    "to": 2,
    "total": 10
  }
}

Get a Single Video

Retrieves the full, detailed data for a single video, suitable for a player. The response is a single Video Object.

GET /videos/{videoId}

Path Parameters

Name	Type	Description
`videoId`	`uuid`	Required. The unique identifier of the video.

Example Request


GET /api/client/v1/videos/9c1a9e3e-6c9b-4f8a-8e2d-9b3c1d4e0f6a

Full Response: `GET /videos/{videoId}`