Start Search (Use Case Search)

Start Use-Case Search

POST https://search.pex.com/api/v1/search/start-search-use-case

Starts a Search lookup based on a predefined use case.

This is the recommended endpoint for most client integrations. Clients using this endpoint only need to choose a desired use case and the API will automatically determine the underlying fingerprint types, search types, and catalog configuration required for that workflow.

Request

Field	Type	Required	Description
use_case	string	Yes	Predefined Search use case.
media_file	file	Yes	Media file to process.

Supported use_case Values

Value	Description
identify_music	Identify commercially distributed sound recordings within media to support detection and rights management workflows.
classify_content	Segment content into music, speech, and silence, with additional acoustic categories to enable structured tagging and content management.
find_song_usage	Track where your sound recordings appear across commercial releases and music platforms to support rights monitoring and catalog protection.
find_composition_usage	Identify where your compositions are used across covers, live performances and derivative works to support publishing oversight.

media_file Info

Each search request requires a media file to be provided using the media_file field.

Endpoints that accept media files use multipart/form-data.

Supported formats generally include any media format supported by FFmpeg.

Please try to keep uploaded files under 100 MB.

Examples

Python

import requests

ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"
MEDIA_FILE_PATH = "./example.mp3"

headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
}

with open(MEDIA_FILE_PATH, "rb") as media_file:
    response = requests.post(
        "https://search.pex.com/api/v1/search/start-search-use-case",
        headers=headers,
        files={
            "media_file": media_file,
        },
        data={
            "use_case": "identify_music",
        },
    )

response.raise_for_status()

print(response.json())

Bash

Response

A successful request returns one lookup_id.

JSON

{
  "lookup_id": "123456789012345678"
}