search
Home

Search Endpoint

hashtag
Overview

The Search Media endpoint provides flexible media retrieval capabilities across the SDK Mobile API. It supports searching by title with intelligent text matching, filtering by media type (video, image, audio, document), and organizing results through customizable pagination and sorting options.

The endpoint accepts optional search parameters that can be combined to refine results, including media IDs, custom tags, and library status filters. All searches use AND logic when multiple criteria are specified, ensuring precise results while maintaining simplicity for basic queries.

hashtag
POST:

cURL:

curl --location '{{BASE-URL}}/api/v2/media/search?page={{PAGE_NUMBER}}&size={{PAGE_SIZE}}&sort={{PROPERTY}},{{DIRECTION}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{YOUR-ACCESS-TOKEN}}' \
--data '{
    "ids": [{{IDS}}],
    "searchTerm": {{TITLE}},
    "type": {{TYPE}},
    "tags": {{TAGS}},
    "isLibrary": {{LIBRARY}},
    "active" : {{ACTIVE}}

}'

hashtag
Base URLs

hashtag
Query Parameters

hashtag
Headers

Header
Value

Content-Type

application/json

Authorization

Bearer {{YOUR-ACCESS-TOKEN}}

Access token provided by the endpoint mentioned in this documentation: [SDK Mobile] - Generate an API Token

hashtag
Request Parameters

Parameter
Type
Description

page

Positive number (optional)

Page you want to retrieve. 0-indexed and defaults to 0.

e.g.: ?page=1

size

Number from 0 to 1000

(optional)

Size of the page you want to retrieve. Defaults to 20.

e.g.: ?page=1&size=30

sort

String (optional)

Parameter that should be sorted by in the format property,property(,ASC|DESC)(,IgnoreCase). The default sort direction is case-sensitive ascending. Use multiple sort parameters if you want to switch direction or case sensitivity.

e.g.: ?sort=duration,des

hashtag
Sort Options

Property
Ascending
Descending

accountId

sort=accountId

sort=accountId,desc

subAccountId

sort=subAccountId

sort=subAccountId,desc

active

sort=active

sort=active,desc

createdDate

sort=createdDate

sort=createdDate,desc

duration

sort=duration

sort=duration,desc

isLibrary

sort=isLibrary

sort=isLibrary,desc

type

sort=type

sort=type,desc

title - case-sensitive

sort=title

sort=title,desc

title - case-insensitive

sort=title,ignorecase

sort=title,desc,ignorecase

Case-Sensitive Sorting

When sorting is case-sensitive, the system treats capital letters and lowercase letters as different. Capital letters always come first. Example: "Banana", "apple", "Cherry" sorts as "Banana", "Cherry", "apple" (capitals first, then lowercase).

Case-Insensitive Sorting

When sorting is case-insensitive (add ignorecase), the system ignores capitals vs lowercase and sorts everything alphabetically like a dictionary. Example: "Banana", "apple", "Cherry" sorts as "apple", "Banana", "Cherry" (pure A-Z order). Use this for titles so results look natural to users.

circle-info

Default sort behavior:

  • If the user defines a sort, that sort will be used.

  • If no sort is defined, and the searchTerm is used, the results will be sorted by descending relevance.

  • If the searchTerm is not used, the results will be sorted by createdDate in descending order.

hashtag
Full example

In this example, the requested media items will be retrieved in groups of 30 items per page.

  • Note: Pages start from zero (0).

  • The result will therefore contain the second group of 30 media items (i.e., items 31 through 60), based on the established sort order.

The order of this search is as follows: We have 3 sorts and they will be executed in that order.

  1. First, they will be sorted by subAccountId in case-sensitive ascending order.

  2. The second sort will be sorted by creator in case-sensitive descending order.

  3. And finally, they will be sorted by title in case-ignore ascending order.

hashtag
Errors

triangle-exclamation

Error Response

  • If page parameter is negative (<0) you will receive this error 400 Bad Request

triangle-exclamation

Error Response

  • If size parameter is negative (<0) you will receive this error 400 Bad Request

hashtag
Body Parameters

ids Array of Strings • Optional

It’s an array of strings (mediaIds).

Example: "ids": ["6f0af006-6ded-43f0-8126-291c89f934b1", "c6d96d88-8e7c-46a5-9b74-f947f5a2228e"]

triangle-exclamation

MediaId can not be null

  • ids parameter can be null, but mediaId not. If you send a mediaId as null you will get this error: 400 Bad Request

searchTerm String • Optional

The searchTerm parameter allows clients to perform a textual search over the title field of media items stored in the database.

The searchTerm parameter is optional; when provided, the system returns media whose titles match the processed search expression.

hashtag
Search Behavior

✔ Flexible Word Matching

Searching for "beach" also finds:

  • "beaches"

  • "beachside"

  • "beach party"

  • "summer beach festival"

✔ Case-insensitive

Laptop, laptop, and LAPTOP are the same.

✔ Multi-word Search

searchTerm = summer beach returns titles containing both words, in any order.

✔ Accent-Insensitive

searchTerm = canción matches "cancion" and "canciones".

✔ Punctuation-Insensitive

searchTerm = batch 91234 will match "Batch 91234 Processing".

hashtag
Search Limitations

✘ Search is only performed on the title field

It does not search in:

  • mediaId

  • type

  • accountId

  • body/content of the media

✘ Not a prefix-based autocomplete

Users cannot type "bea" to match "beach".

✘ No wildcard or regex support

searchTerm="*beach*" is treated as plain text.

✘ Numbers are not broken into sub-parts

"123" will not match "A1234".

type String • Optional

It’s a string that can be one of the next values:

  • VIDEO

  • IMAGE

  • AUDIO

  • DOCUMENT

Example: “type”: “VIDEO”

tags Map of tags • Optional

It should be an object with Keys and Values.

In The VideoPlatform API the tags are used to classify and group media by intrinsic attributes — for example, category, type, or any characteristic that naturally describes the media itself. They are designed to enhance searchability and organization and are therefore part of the media object.

As the tags are key-values, the search is performed for all media that match all the filter tags with their corresponding key and value. If there is more than one tag, an AND condition will be applied:

Example: "tags": { "tag1": "value1", "tag2": "value2" }

isLibrary Boolean • Optional

The isLibrary flag determines whether media should be included in a subAccount's media library. When set to true, it includes the media in the library but does not allow sharing between subAccounts. Values can be true or false.

Example: “isLibrary”: true

active Boolean • Optional Filter indicating whether the media to be searched should be in active or inactive status. If you need to search by tags, set the value true. Values can be true or false.

Example: “active”: true

hashtag
Recommendations for performing searches

  • All parameters are optional and independent; that is, they can be used independently, or none can be used at all.

  • If a field is submitted with empty text ("") or null, it's considered as if that attribute was NOT submitted. The attribute is ignored in the search.

  • In the search body, the searchTerm attribute it's only used to search by the title of the media, the possibility of searching by more than one attribute using searchTerm in the future is being explored. The current capabilities only searches by the title attribute.

  • ALL search body parameters use the AND condition. That is, if you search by searchTerm, ids, and type, the results will be matches that match the searchTerm, have the specified IDs, and are of the type submitted.

hashtag
Request body example

hashtag
Request Body Example Without some Values:

hashtag
Response Example:

PreviousGenerate Admin Api TokenNextSDK data privacy

Last updated