Skip to content

Start Search (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

FieldTypeRequiredDescription
use_casestringYesPredefined Search use case.
media_filefileYesMedia 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

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())

CLIENT_ID="YOUR_CLIENT_ID"
CLIENT_SECRET="YOUR_CLIENT_SECRET"
ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
MEDIA_FILE_PATH="./example.mp3"

curl -X POST "https://search.pex.com/api/v1/search/start-search-use-case"  -H "Authorization: Bearer ${ACCESS_TOKEN}"  -F "use_case=identify_music"  -F "media_file=@${MEDIA_FILE_PATH}"

Response

A successful request returns one lookup_id.

{
  "lookup_id": "123456789012345678"
}