API Documentation¶
Info
Note: The Search APIs are currently in private testing and are not yet publicly available. If you are interested in additional information, please contact your Vobile representative via our support email.
Overview¶
These REST endpoints provide HTTP access to Vobile Search workflows without requiring integration with the native C/C++ SDK library.
The API supports both the Vobile Music Registry and your private Custom Database:
1. Search: Vobile Music Registry¶
Query commercial music across major and independent rightsholders:
- Use Case Search (
POST /api/v1/search/start-search-use-case): Provide a predefined use case (e.g. "identify music" or "find song usage") and the API handles underlying configuration. - Advanced Search (
POST /api/v1/search/start-search): Explicitly provide fingerprint types and search types with granular control. Supports queries using media files, pre-generated fingerprints, or ISRCs. - Check Search (
GET /api/v1/search/check-search/{lookup_id}): Poll or wait for the completed search result. - Search Response: Format and interpretation of Vobile Music Registry search responses.
2. Search: Custom Database¶
Manage and search against your own private catalog:
- Start Search (
POST /api/v1/private/start-search): Initiate an asynchronous search against your private catalog using media files or pre-generated fingerprints. - Check Search (
GET /api/v1/private/check-search/{lookup_id}): Retrieve completed private search results. - Search Response: Format and interpretation of private search responses.
- Ingest Asset (
POST /api/v1/private/ingest): Ingest assets into your private catalog using media files or pre-generated fingerprints. - Archive Asset (
POST /api/v1/private/archive): Archive an asset or specific fingerprint types from your catalog. - Get Catalog Entry (
GET /api/v1/private/get): Retrieve metadata and status of an ingested catalog entry. - List Catalog Entries (
GET /api/v1/private/list): List ingested catalog entries with cursor-based pagination.
Fingerprint Generation¶
Endpoints accepting fingerprints (/api/v1/search/start-search, /api/v1/private/start-search, and /api/v1/private/ingest) allow clients to submit lightweight raw binary fingerprints instead of uploading full media files.
SDK CLI (pexsearch)
In order to generate fingerprints, clients need to use the pexsearch CLI tool. Generating fingerprints locally reduces network bandwidth and accelerates processing. See the SDK CLI (pexsearch) documentation for installation and usage instructions.
Workflow Lifecycle¶
Search operations are asynchronous:
- The client initiates a search (e.g., via
/start-searchor/private/start-search). - The API returns a
lookup_id. - The client calls the corresponding check endpoint (
/check-search/{lookup_id}). - The check endpoint waits until the completed search response is available and returns the result.