Search Endpoint

Overview

The Search endpoint allows filtering media items based on different properties.

HTTP Method

POST

Endpoint URL

Pagination Notes

The /search endpoint uses Spring’s Pageable mechanism, allowing clients to control pagination with page and size query parameters.
Default: If size is not specified, each page returns 20 items by default.
If size is specified, that value will be used, and there is currently no enforced upper limit at the controller level. However, it is recommended to keep the size ≤ 100 to avoid potential performance issues.
If a negative page number is provided (e.g., page=-1), a 400 Bad Request with a clear message.

Request Parameters

Query Parameters

Headers

Header

Description

Content-Type

application/json

Authorization

Bearer {{YOUR-ACCESS-TOKEN}}

Request Body

Parameter

Description

Type

ids

Array of media IDs to filter

Array (optional)

title

Title

String

type

Type of media

VIDEO, IMAGE, AUDIO, DOCUMENT (optional)

tags

Map of tags (key-value pairs)

JSON Object (optional)

isLibrary

Whether to filter media from the library

Boolean (optional)

isActive

Active/inactive media filter

Boolean (optional)

Request Body Example

Full Example:

{
    "ids": ["0e86da5d-9efe-4be5-a7d7-61b4796cb8dd"],
    "type": "VIDEO",
    "title": {{TITLE}},
    "tags": {
        "tag1": "value1"
    },
    "isLibrary": true,
    "active" : true
}

Example With Missing Values:

{
    "ids": null,
    "title": {{TITLE}},
    "type": null,
    "tags": null,
    "isLibrary": false,
    "active" : false,
}

cURL Request Example

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

Response

Response Example

{
    "content": [
        {
            "id": "53f7e0b1-c276-49d8-b6aa-75520ed385ce",
            "url": "https://sdkmobileapi-81a035d7-b51c-43a6-991a-71a9a29dee7d.s3.us-west-2.amazonaws.com/media/00066767-4e16-4878-a99a-4594dedffa14.mp4",
            "transcriptionUrl": "https://sdkmobileapi-81a035d7-b51c-43a6-991a-71a9a29dee7d.s3.us-west-2.amazonaws.com/transcriptions/00066767-4e16-4878-a99a-4594dedffa14.vtt",
            "transcriptionLength": "0",
            "type": "VIDEO",
            "createdDate": "2025-02-04T21:18:07Z",
            "title": "00066767-4e16-4878-a99a-4594dedffa14.mp4",
            "subAccountId": "b4468974-32f5-11ef-b234-0660c3706637",
            "duration": 120,
            "includeInReport": true,
            "isLibrary": true,
            "tags": {
              "tag1": "value1",
              "tag2": "value2"
            },
            "metadata": {
              "data1": "my value",
              "data2": false
            },
            "thumbnailUrl": "https://sdkmobileapi-81a035d7-b51c-43a6-991a-71a9a29dee7d.s3.us-west-2.amazonaws.com/media/thumbnail/53f7e0b1-c276-49d8-b6aa-75520ed385ce.jpg",
            "previewUrl": "https://sdkmobileapi-81a035d7-b51c-43a6-991a-71a9a29dee7d.s3.us-west-2.amazonaws.com/media/preview/53f7e0b1-c276-49d8-b6aa-75520ed385ce.gif"
        },
        {
            "id": "a9c7bf94-c78e-42e4-b22d-95a37712cf23",
            "url": "https://sdkmobileapi-81a035d7-b51c-43a6-991a-71a9a29dee7d.s3.us-west-2.amazonaws.com/media/7db66c4d-0f14-49ed-9d7b-ed49e81bf800.mp4",
            "transcriptionUrl": "https://sdkmobileapi-81a035d7-b51c-43a6-991a-71a9a29dee7d.s3.us-west-2.amazonaws.com/transcriptions/7db66c4d-0f14-49ed-9d7b-ed49e81bf800.vtt",
            "transcriptionLength": "0",
            "type": "VIDEO",
            "createdDate": "2025-02-04T21:09:54Z",
            "title": "7db66c4d-0f14-49ed-9d7b-ed49e81bf800.mp4",
            "subAccountId": "b4468974-32f5-11ef-b234-0660c3706637",
            "duration": 60,
            "includeInReport": true,
            "isLibrary": true,
            "tags": {
              "tag1": "value1",
              "tag2": "value2"
            },
            "metadata": {
              "data1": "my value",
              "data2": false
            },
            "thumbnailUrl": "https://sdkmobileapi-81a035d7-b51c-43a6-991a-71a9a29dee7d.s3.us-west-2.amazonaws.com/media/thumbnail/a9c7bf94-c78e-42e4-b22d-95a37712cf23.jpg",
            "previewUrl": "https://sdkmobileapi-81a035d7-b51c-43a6-991a-71a9a29dee7d.s3.us-west-2.amazonaws.com/media/preview/a9c7bf94-c78e-42e4-b22d-95a37712cf23.gif"
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 20,
        "sort": {
            "sorted": false,
            "unsorted": true,
            "empty": true
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "totalElements": 2,
    "totalPages": 1,
    "last": true,
    "numberOfElements": 2,
    "size": 20,
    "number": 0,
    "sort": {
        "sorted": false,
        "unsorted": true,
        "empty": true
    },
    "first": true,
    "empty": false
}

Variable detail

Params:

BASE-URL:

Release Candidate (RC): https://sdk-mobile-api-rc.truvideo.com
Production: https://sdk-mobile-api.truvideo.com

PAGE_SIZE:

Number of items per page (page size). Note: must be provided as the size query parameter, not in the body. Defaults to 20 when omitted. Recommended maximum: ≤ 100. Negative values cause a 400 Bad Request with a clear message.

YOUR-ACCESS-TOKEN:

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

DIRECTION:

Values:

desc
asc

PAGE_NUMBER:

Note: must be provided as the pagequery parameter Note: Negative values cause a 400 Bad Request with a clear message.

PROPERTY:

The attribute that you want to order by (E.G., createdDate)

IDS:

Array of media ids

TITLE:

This attribute looks for matches and similarities with the title attribute.

How does it work?

Case-insensitive: Laptop, laptop, and LAPTOP are the same.
Punctuation mostly ignored: commas, dashes, periods, colons, semicolons, and underscores are treated as spaces.
- Typing pre-owned_cars is like typing pre owned cars.
Partial word matches from 3+ characters: you don’t need the full word—any substring of length 3 to 10 inside a word can match.
- Typing elec will match titles containing electric, electronics, electrico, etc.
- Typing pho will match phone, photos, photography, etc.
Word parts and numbers are split: ThingsLikeThis and A12B-500 are split into meaningful pieces (e.g., things, like, this, a, 12, b, 500), so you can find them with their parts.
Stemming in English and Spanish: common endings are normalized so close variants match.
- English examples: run, running, runner match each other.
- Spanish examples: hablar, hablando, habló match each other.
Accents matter: there’s no accent/diacritic folding here. café is not the same as cafe. Type the accent if you expect it in the title.

For the most accurate results, it's recommended to use at least 3 or 4 characters.

Practical Tips:

Use at least 3 characters for each term to get matches (shorter than 3 won’t match).
You can search inside long words: any 3–10 character chunk inside a word can hit.
- Example: transmis will match transmisión, transmission.
No need to add wildcards (*)—partial matching is built in.
Multiple words are ANDed by default in most simple searches: entering smart tv 55 typically finds titles containing all three concepts somewhere.
Hyphenated or snake_case titles are easy to find:
- next-gen → search next gen
- the_best_title → search best title

TYPE:

Values:

VIDEO
IMAGE
AUDIO
DOCUMENT

TAGS:

Map of tags like:

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

It should be an object with Keys and Values.

Since our 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.

LIBRARY:

true
false

ACTIVE:Filter indicating whether the media to be searched should be in active or inactive status. This field is optional; if it is not provided, the search will return all values, both active and inactive

true
false

Request Body Example:

{ "ids": ["0e86da5d-9efe-4be5-a7d7-61b4796cb8dd"], "title": "summer highlights", "type": "VIDEO", "tags": { "tag1": "value1" }, "isLibrary": true }

Request Body Example Without some Values:

{ "ids": null, "type": null, "tags": null, "isLibrary": false }

Pagination Notes

The /search endpoint uses Spring’s Pageable mechanism, allowing clients to control pagination with page and size query parameters.
Default: If size is not specified, each page returns 20 items by default.
If size is specified, that value will be used, and there is currently no enforced upper limit at the controller level. However, it is recommended to keep the size ≤ 100 to avoid potential performance issues.
If a negative page number is provided (e.g., page=-1), a 400 Bad Request with a clear message.

PreviousGenerate Admin Api Token NextSDK data privacy

Last updated 16 days ago