Home

Search Endpoint

Overview

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

HTTP Method

POST

Endpoint URL

{{BASE-URL}}/api/media/search

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

Parameter
Type
Description

page

Positive integer (optional)

Page to retreive,0-indexed (Default - 0)

size

Integer 0-1000 (optional)

Number of items per page. (Default - 20)

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

Headers

Header

Description

Content-Type

application/json

Authorization

Bearer {{YOUR-ACCESS-TOKEN}}

The access token is provided by the endpoint described here: Generate an API token

Request Body

Parameter

Description

Type

ids

Array of media IDs to filter

Array (optional)

searchTerm

Title (Optional), Flexible word matching

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:

Example With Missing Values:

cURL Request Example

Response

Valid Response Example

Error Response

  • Invalid page (<0)

Return 400 Bad Request

  • Invalid size (<0)

Return 400 Bad Request

  • Request body parameters

Array of strings (mediaIds).

  • ids itself may be null.

  • Individual mediaId values cannot be null.

    • If a null element is included, you will receive:

Variable detail

Params:

BASE-URL:

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

TEAMPORALLY DISABLE

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 TokenNextSDK data privacy

Last updated