This is the documentation for integrating Harmix music search into your application. We provide an easy-to-use API for different kinds of searches: Prompt Search, Video Search, Similarity Search, Story Search, and Lyrics Full-Text Search. All we require from you is a search input. Let Harmix handle the rest.
\nHarmix provides a variety of searches to satisfy your needs:
\nPrompt Search: Search music in your catalog using free text. For example: Lush and uplifting instrumental featuring guitar and piano for a reflective mood.
\nVideo Search: Upload your video to get the ideal music match that fits the mood.
\nSimilarity Search: Provide reference track(s) to find similar ones in your catalog.
\nStory Search: Specify the keywords or describe the story of the song to be suggested. For example: Help me find a song about a guy crushing on a girl who might not feel the same.
\nHarmix provides its functionality based on your music catalogs. Thus, keeping your newest music additions in sync with Harmix API is your priority. We deliver a set of endpoints for you to be able to upload your music catalog to Harmix's environment to be processed there and become available for search asynchronously.
\nAll you need to do is upload an audio file and specify its metadata with the source_id value for you to match the results from Harmix API with your database(s). As a response, you will receive a system_id, the ID of your catalog track in the Harmix database. The endpoint provides a webhook functionality, so if you pass a webhook URL within the request, we will let you know once the track is processed. However, if using a webhook is not an option, you can verify your track's processing status by using /status endpoint.
Once the track is uploaded and processed, you can make it available for search on your platform or application.
\nDepending on your publishing process, you might also stumble across a situation when you need to update a track's metadata or even remove that track from your searchable catalog.
\nNote here that if you decide to remove a track from your system, it's also necessary to remove it from Harmix. Otherwise, Harmix can still return it within the results to search your queries.
\nTherefore, we provide primary API endpoints to support your CRUD operations within your catalogs on our side.
\nOnce your catalog is processed from our side, you can perform a variety of search queries for different kinds of searches. Such functionality is provided by /search endpoint.
\nHarmix supports a predefined schema for track metadata, which ensures data accuracy and consistency at various stages of track processing. This schema serves as a standardized blueprint that defines the expected structure and metadata attributes associated with audio tracks.
\n\n\nDon't hesitate to contact us if you want to upload more metadata not present in the predefined schema.
\n
The Primary Key Component column denotes whether a specific metadata field can be used for composing a (Composite) Primary Key that uniquely identifies a track in your Harmix catalog. This Primary Key is further used to perform any Catalog or Search operations on your catalog tracks.
\nWith the extra_parameters metadata field, you can store additional metadata that doesn't conform to the original Metadata Schema. Ensure your metadata is consistent and serialized properly. The extra_parameters field accepts a dictionary, where both keys and values must be of type String. If you need to include an array, remember to serialize it by wrapping it in a string, as shown in the example below.
{\n \"custom_attribute_1\": \"value1\",\n \"custom_attribute_2\": \"value2\",\n \"tags\": \"[\\\"tag1\\\", \\\"tag2\\\", \\\"tag3\\\"]\",\n \"related_ids\": \"[\\\"123\\\", \\\"456\\\", \\\"789\\\"]\"\n}\n\nTo access our APIs, each client is provided with a unique API key. This API key serves as your authentication credential and is essential for authorizing requests to our services. We take the security of your API key seriously, and it should be kept confidential to prevent unauthorized access to your data.
\nIn your API requests, include your API key in the api_key header, as shown in the example:
![https://harmix.ai/storage/hrmx-albm-rck3-cover.jpg](\"https://harmix.ai/storage/hrmx-albm-rck3-cover.jpg\"){kind=link}
api_key: <YOUR-API-KEY>\n\nWhen using our API, it's important to be prepared for exceptional situations that may occur during the course of your interactions. This section of the documentation provides an overview of how exceptions are handled within the API.
\nOur API is designed to return exceptions in a standardized JSON structure. This structure includes the following key components:
\nError Code: Each exception is associated with a unique error code. This code serves as a specific identifier for the type of exception encountered.
\nShort Textual Message: A concise, human-readable error message is provided to give you insight into the nature of the exception. This message is designed to quickly convey what went wrong.
\nDetails: In some cases, additional information about the exception may be included in the details, providing more context and details about the exceptional situation, aiding in troubleshooting and resolution.
\n{\n \"detail\": {\n \"code\": 1001,\n \"status\": \"failure\",\n \"message\": \"The track record with the provided Primary Key metadata already exists in your Harmix catalog. System ID: 3c41f3c8-476e-41ae-b04d-9620cc7be700.\",\n \"details\": \"Please use a different track identifier or refer to the Metadata Schema regarding Metadata Overlapping in the Harmix Documentation: https://docs.harmix.ai/#metadata-schema\"\n }\n}\n\nOur documentation includes a readily accessible table containing our internal error codes, each accompanied by descriptive explanations.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"📄 Overview","slug":"overview"},{"content":"🚀 How to Integrate","slug":"how-to-integrate"},{"content":"📒 Metadata Schema","slug":"metadata-schema"},{"content":"✔️ Authentication","slug":"authentication"},{"content":"🔴 Exceptions","slug":"exceptions"}],"owner":"31751929","collectionId":"c3127063-b6d8-4572-afcc-52e337608da0","publishedId":"2s9Ykj9iJU","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"2E303E","highlight":"7424FF"},"publishDate":"2023-12-12T17:33:10.000Z"},"item":[{"name":"Catalog Endpoints","item":[{"name":"Upload Track","id":"f8f83773-7659-48f3-a723-3401f0bf2680","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"multipart/form-data","type":"text"}],"body":{"mode":"formdata","formdata":[{"key":"track","contentType":"","type":"file","fileNotInWorkingDirectoryWarning":"This file isn't in your working directory. Teammates you share this request with won't be able to use this file. To make collaboration easier you can setup your working directory in Settings.","filesNotInWorkingDirectory":["/Users/Shared/audio.mp3"],"src":"/Users/Shared/audio.mp3"},{"key":"webhook","value":"https:/mywebhook","type":"text"},{"key":"metadata","value":"{\n \"source_id\": \"14393369\",\n \"isrc\": \"AB1234567890\",\n \"track_title\": \"Sunflower\",\n \"track_number\": \"12\",\n \"track_code\": \"HRMX9#12\",\n \"track_description\": \"A track that conveys a sense of hope, loyalty, and love for someone or something that is unique and special.\",\n \"release_year\": 2017,\n \"release_date\": \"2017-12-05\",\n \"version\": false,\n \"version_tag\": \"Main\",\n \"version_name\": \"Sunflower (Main)\",\n \"versions_number\": 5,\n \"master_id\": \"143933\",\n \"label_name\": \"Harmix Records\",\n \"label_code\": \"HRMX\",\n \"album_id\": \"hrmx-albm-rck3\",\n \"album_number\": \"3\",\n \"album_code\": \"HRMX3\",\n \"album_name\": \"Happy evenings\",\n \"album_description\": \"Music for happy evenings\",\n \"album_cover_url\": \"https://harmix.ai/storage/hrmx-albm-rck3-cover.jpg\",\n \"album_keywords\": [\"Happy\", \"Enticing\"],\n \"duration\": 224,\n \"tempo\": \"slow\",\n \"bpm\": 80,\n \"key\": \"D#m\",\n \"time_signature\": \"3/4\",\n \"is_instrumental\": null,\n \"is_vocal\": null,\n \"lyrics\": \"You’re the sunflower, ...\",\n \"lyrics_language\": \"EN\",\n \"explicit_lyrics\": null,\n \"artists\": [\"John Doe\", \"Jane Doe\"],\n \"composers\": [\"Alice Hellmann\", \"Bob Diffie\"],\n \"genres\": [\"Pop\", \"Rap\"],\n \"moods\": [\"Happy\", \"Enticing\"],\n \"instruments\": [\"Piano\", \"Acoustic guitar\"],\n \"music_keywords\": [\"Commercial\", \"Cafe\", \"Games\"],\n \"decades\": [\"2010s\"],\n \"vocals\": [\"vocal\", \"male vocal\"],\n \"available_countries\": [\"US\", \"UK\", \"DE\", \"FR\"],\n \"active\": null,\n \"licensable\": null,\n \"restricted\": null,\n \"commercial\": null,\n \"recognisable\": null,\n \"sync_history\": null,\n \"jam_sync\": null,\n \"hit\": null,\n \"top\": null,\n \"publishers\": [\"Harmix Studio\"],\n \"owner\": [\"Owner\"],\n \"share\": 0.5,\n \"external_id\": \"1234-5678\",\n \"audio_url\": \"https://harmix.ai/storage/myaudio.mp3\",\n \"waveform_url\": \"https://harmix.ai/storage/myaudio-waveform.json\",\n \"extra_parameters\": {\"custom_attribute_1\": \"value_1\"}\n}","contentType":"application/json","type":"text"}]},"url":"https://api.harmix.ai/tracks","description":"Upload your catalog track to Harmix's internal storage along with its metadata, which will be processed and stored separately. On success, as a response, you will receive HTTP status 201 Created that contains system_id, a unique identifier of your catalog track in the Harmix database, a Primary Key. The track will be processed asynchronously.
The required metadata fields can be adjusted based on your metadata template. If the default Metadata Schema does not work for you, don't hesitate to contact us at support@harmix.ai.
\nEach track must have unique source_id which will be assigned a unique system_id. You can later access the track by either one of these.
A set of metadata fields can also uniquely identify a track if you prefer to execute our search using your internal (Composite) Primary Key. The Composite Primary Key is represented as one or multiple fields from the Metadata Schema. The combination of metadata fields, such as source_id, version_tag, etc, can also uniquely identify a track in Harmix's system.
For missing values, provide a NULL value instead of 0, empty string, 999 or other specific values to ensure consistency. The BPM metadata has a a validation check for a positive value (>0). For any mismatches, you will receive HTTP status 422 Unprocessable Entity with detailed error description.
You can upload only MP3, WAV, and M4A audio formats with a file size limit of 120 MB.
\nAudio upload options:
\nAÂ direct HTTPS URLÂ to a raw audio file (without requiring any authorization or user interaction). Preferred option.
\nA local file path with an audio extension.
\nThe request must contain either track_url or track attribute. We recommend using track_url when possible.
track_url (OPTIONAL): This parameter is used to upload an audio track to the server for processing via an HTTPS URL. Ensure that the audio file format is supported by the API (e.g., MP3, WAV, M4A).
track (OPTIONAL): This parameter is used to upload an audio track file to the server for processing. The audio file should be provided as a file attachment, and its path on the local system should be specified. Ensure that the audio file format is supported by the API (e.g., MP3, WAV, M4A).
metadata (REQUIRED): This parameter is a critical component of the request as it provides detailed information about the uploaded audio track that can further be used for track processing, searching, or filtering. It should be provided as a serialized JSON object, as shown in the example. For more details on this parameter, check out our Metadata Schema.
webhook (OPTIONAL): This parameter allows you to specify a URL to which the API will send a response once the track processing is complete. This can be useful for receiving notifications or updates about the processing status or results. While not mandatory, providing a webhook URL can be beneficial for tracking and managing the processing workflow.
Get track processing status by its Primary Key.
\nThis operation type is executed on only one track at a time by its Primary Key or Composite Primary Key by composing the primary_key body:
system_id that you receive after uploading your track to Harmix's end. It uniquely identifies a track in Harmix's system.source_id, version_tag, etc, can uniquely identify a track in Harmix's system.At each stage of processing, each track is assigned a processing_status code that denotes whether the track is ready for a particular type of search.
Delete track from Harmix searchable catalog by its Primary Key and return its metadata.
\n\n\nDeleting a track from the Harmix searchable catalog results in complete track deletion from our storage and database. If you want to remove a particular track from searchable results, consider using one of our predefined parameters in our metadata schema, e.g.,
\nactive=False. Afterwards, apply that filter to your search query.
force (OPTIONAL): Ensures the deletion of all matching tracks, even if multiple are found by the provided Primary Key, guaranteeing a complete removal.This operation type is executed by the track's Primary Key or Composite Primary Key by composing the primary_key body:
system_id that you receive after uploading your track to Harmix's end. It uniquely identifies a track in Harmix's system.source_id, version_tag, etc, can uniquely identify a track in Harmix's system.Ensures the deletion of all matching tracks.
\n","type":"text/plain"},"key":"force","value":"False"}],"variable":[]}},"response":[{"id":"9defe40f-eb41-4bc0-addc-d395301580dc","name":"200 OK","originalRequest":{"method":"DELETE","header":[{"key":"api_key","value":"Update track metadata by its Primary Key. Updating track metadata will not require any track reprocessing. This operation type is executed on only one track at a time.
\n\n\nYou can update any metadata parameter except for
\nsource_idfrom our metadata schema.
primary_key (REQUIRED): Unique track identifier that is either a Primary Key or a Composite Primary Key:system_id that you receive after uploading your track to Harmix's end. It uniquely identifies a track in Harmix's system.source_id, version_tag, etc, can uniquely identify a track in Harmix's system.update_metadata (REQUIRED): A JSON object of track metadata to update that corresponds to the Metadata Schema.Perform a bulk update of track metadata for up to 1,000 tracks in a single request using their Primary Keys. This endpoint is significantly faster and more efficient than sending 1,000 individual update requests, as it avoids unnecessary overhead. Updating track metadata will not require any track reprocessing.
\n\n\nYou can update any metadata parameter except for
\nsource_idfrom our metadata schema.
A list of 1-1000 JSON objects containg:
\nprimary_key (REQUIRED): Unique track identifier that is represented as system_id or source_id.
update_metadata (REQUIRED): A JSON object of track metadata to update that corresponds to the Metadata Schema. Please, provide only the fields that you want to update.
The output returns a summary of the operation, including the errors flag indicating if any errors occurred, and a list of results for each track.
200 for success, 404 if the track was not found).This per-track feedback makes it easy to detect and handle partial failures within a bulk update request.
\n","auth":{"type":"apikey","apikey":{"value":"Get tracks' metadata by one of the input parameters:
\nsystem_id (query param): Track identifier in Harmix system.
source_id (query param): Track identifier in your system.
primary_key (body): Track identifier combining multiple metadata fields.
Only one of input parameters should be provided.
\nprimary_key (OPTIONAL): Unique track identifier that is either a Primary Key or a Composite Primary Key:
The Primary Key is represented as the system_id that you receive after uploading your track to Harmix's end. It uniquely identifies a track in Harmix's system.
The Composite Primary Key is represented as one or multiple fields from the Metadata Schema. The combination of metadata fields, such as source_id, version_tag, etc, can uniquely identify a track in Harmix's system.
Unique identifier in Harmix system.
\n","type":"text/plain"},"key":"system_id","value":"Unique source identifier.
\n","type":"text/plain"},"key":"source_id","value":"Our collection of CRUD (Create, Read, Update, Delete) endpoints forms the backbone of our API, offering our clients the tools to efficiently manage their music catalogs stored within Harmix's internal storage system. These endpoints empower users to perform essential operations on their music assets, allowing for the seamless addition, retrieval, modification, and removal of tracks and associated metadata.
\n","auth":{"type":"apikey","apikey":{"value":"Upload type.
\n","type":"text"},{"key":"source","description":"Audio/video binary file.
\n","type":"file","src":"/Users/Shared/audio.mp3"},{"key":"reference","value":"https://www.youtube.com/watch?v=QYh6mYIJG2Y","description":"Spotify or YouTube URL.
\n","type":"text"}]},"url":"https://api.harmix.ai/upload?session_id=Utilizing our /search endpoint for the Similarity Search on a particular external audio track or Video Search on the desired video requires uploading a respective binary file to the Harmix's side.
\n\nWe support either uploading your audio/video or referencing the desired audio from Spotify or YouTube via the source URL. Note here that you can specify only one external reference at a time.
\n
Once a specific file is uploaded, you will receive the upload_id - Harmix's internal ID for the externally uploaded files that allows you to apply the Similarity Search or Video Search on.
When sending the request, you have to specify a correct reference type. Currently, we support the following reference types:
\nsession_id (OPTIONAL): A unique identifier associated with a user session or a user's client-side web account. It is utilized to track and report user interactions with Harmix based on their requests. After, the Harmix team subsequently analyzes this data to gain insights and improve the product's performance and user experience. This parameter can represent a session, user ID, or any other ID uniquely identifying the user's interaction with Harmix. We highly recommend always to use this parameter in your requests.
priority (OPTIONAL): Determines which download strategy to use when fetching reference tracks from streaming services (YouTube, Spotify, etc.). Supported values:
original:
Downloads the full audio track from its original source (YouTube, SoundCloud, etc.). The system attempts the original source first and falls back to secondary sources only if the primary source is unavailable.
fast:
Downloads a 30-second preview from a secondary source (for example, for YouTube references, the secondary source may be Spotify). This option provides faster processing but returns a short preview. If the preview is unavailable, the system falls back to downloading from the original source.
Notes:
\nUpload references support caching. If a fast-priority request is made and the full original track already exists in the cache, the cached version will be returned instead of the 30-second preview.
The fast priority currently affects YouTube references only; for other services, it behaves the same as original.
type (REQUIRED): Specifies the reference type of upload.
source (OPTIONAL): Audio file that needs to be uploaded. In the case of video uploading, contact support@harmix.ai or follow the instructions we provide you personally.
reference (OPTIONAL): A reference track URL from Spotify or YouTube.
upload_id: Unique identifier for the uploaded reference to be used in search request.
uploaded_at: Timestamp when the reference was uploaded.
status: Status of the upload.
audio_url: Temporary URL valid for 12 hours to access the uploaded reference. Available only for audio references.
waveform_url: Temporary URL valid for 12 hours to access waveform of the uploaded audio reference. Available only for audio references.
metadata: Track metadata extracted from the source service (Spotify, YouTube, etc.). Returns null for manually uploaded files.
is_variant: Denotes if the uploaded track is variant (e.g., 30-second Spotify preview) of its original version.
A unique identifier associated with a user session or a user's client-side web account.
\n","type":"text/plain"},"key":"session_id","value":"Controls the download source strategy when fetching reference tracks from streaming services (YouTube, Spotify, etc.).
\n","type":"text/plain"},"key":"priority","value":"The Search endpoint is a versatile and comprehensive feature that allows users to perform various types of searches on audio and video content within our system. We support Prompt Search, Video Search, Similarity Search, Story Search, and Lyrics Full-Text Search in one query. All the parameters you input affect the resulting response. Regardless of your input, Harmix will handle it and provide a valid response. As a result, you will receive a list of tracks that best match your input query. You can use the unique track identifier to match the results to your internal catalog.
\n\n\nResults are sorted by relevance, from highest to lowest.
\n
session_id (OPTIONAL): A unique identifier associated with a user session or a user's client-side web account. It is utilized to track and report user interactions with Harmix based on their requests. After, the Harmix team subsequently analyzes this data to gain insights and improve the product's performance and user experience. This parameter can represent a session, user ID, or any other ID uniquely identifying the user's interaction with Harmix. We highly recommend always to use this parameter in your requests.audio_reference (OPTIONAL): An audio reference for the Similarity Search or other kinds of search.
Note: Only one reference audio track can be used at a time, either internal or external.
\ninternal (OPTIONAL): To use your internal catalog references, you need to pass a primary_key, which is either Harmix's internal Primary Key for your catalog track (system_id) or could be your catalog's Primary Key or a Composite Primary Key involving source_id and other metadata parameters that uniquely identify the track you want to reference.
external (OPTIONAL): You can also reference an external audio track loaded to Harmix's side via the /upload endpoint. That track can be referenced using the received upload_id.
segment (OPTIONAL): For each type of audio (external/internal), you can choose a specific timeframe that you want to use for the Similarity Search. This way, only the audio segment starting from segment.start to segment.end will be utilized in the search.
ignore_vocals (OPTIONAL): Excludes the vocals from the input audio to emphasize the original track's sound and instruments if set to True.
prioritize_bpm (OPTIONAL): Searches for music tracks that align with the BPM of the input audio if set to True. Note: prioritize_bpm disregards any bpm filter set in the filters body.
highlights (OPTIONAL): When a user initiates a Similarity Search, the system analyzes the audio and identifies segments that closely match the provided sample. These matching segments can then be highlighted or visually indicated in some way, making it easy for users to locate and access the relevant parts of the audio. Note here that this feature requires a higher-tier subscription. To activate it, refer to Harmix Support at support@harmix.ai.
video_reference (OPTIONAL): A video reference for the Video Search previously loaded to Harmix's side via the /upload endpoint. That video can be referenced using the received upload_id.
prompt (OPTIONAL): A text prompt or query used for the Prompt Search. The value is typically a user-generated query or keyword.
story (OPTIONAL): Similar to the prompt, this key allows users to provide a song narrative or lyrics context for the audio search.
lyrics (OPTIONAL): A full-text search criteria related to lyrics in audio tracks. It includes two sub-keys: operator (indicating the type of comparison, such as contains or not-contains) and value (representing the desired lyrics to search for).
filters (OPTIONAL): Defines complex filtering conditions for the audio search. It includes logic (specifying the logical operator, such as and or or) and conditions (a list of filter conditions).
The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items.
\n","type":"text/plain"},"key":"offset","value":"0"},{"description":{"content":"The maximum number of items to return. Default: 50. Minimum: 1. Maximum: 100.
\n","type":"text/plain"},"key":"limit","value":"50"},{"description":{"content":"A unique identifier associated with a user session or a user's client-side web account.
\n","type":"text/plain"},"key":"session_id","value":"This endpoint allows you to search for tracks based on internal references, leveraging Similarity Search over multiple tracks. You can also add filtering to the request as explained in Filtering.
\n\n\nResults are sorted by relevance, from highest to lowest.
\n
The endpoint also supports clustering of the internal references to group them based on similar features and styles. This option allows you to get more targeted suggestions. By default, the tracks are not grouped into clusters, and the recommendations are made from the entire playlist.
\naudio_references (REQUIRED): A list of objects identifying reference tracks.
primary_key (REQUIRED): Harmix's internal Primary Key for your catalog track (system_id) or your catalog's Primary Key or a Composite Primary Key involving source_id and other metadata parameters that uniquely identify the track you want to refer.
weight (OPTIONAL) [DEFAULT: 1.0]: A floating-point value representing the weight of the reference. The weight indicates the importance of the reference in the search process.
cluster (OPTIONAL) [DEFAULT: **false**]: A boolean value indicating whether the reference tracks should be clustered during the search.
filters (OPTIONAL): An object containing filter criteria for the search, read detailed specification in Filtering.
\n\nThe number of supported audio references is up to 100.
\n
The body object has the following structure:
\n{\n \"audio_references\": [\n {\n \"primary_key\": {\n \"system_id\": \"<system_id>\" | null,\n \"source_id\": \"<source_id>\" | null,\n ...\n },\n \"weight\": float = 1.0\n },\n {\n \"primary_key\": {\n \"system_id\": \"<system_id>\" | null,\n \"source_id\": \"<source_id>\" | null,\n ...\n },\n \"weight\": float = 1.0\n },\n ...\n ],\n \"cluster\": bool = false,\n \"filters\": FiltersObject | null\n}\n\nThe index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items.
\n","type":"text/plain"},"key":"offset","value":"0"},{"description":{"content":"The maximum number of items to return. Default: 50. Minimum: 1. Maximum: 100.
\n","type":"text/plain"},"key":"limit","value":"50"},{"description":{"content":"A unique identifier associated with a user session or a user's client-side web account.
\n","type":"text/plain"},"key":"session_id","value":"Harmix allows for a fast and convenient search embodying Prompt Search, Video Search, Similarity Search, Story Search, and segments Highlighting in one query.
\nApart from using the different kinds of searches we provide, you can apply various filters based on your system's filtering approach or any custom requirements. Our API lets you apply multiple filters to the search results using the filter field.
\n\nYou can apply filters to any field presented in our Metadata Schema.
\n
Each filtering criteria needs to be a string-keyed array object with the following keys:
\nWe support the following operators:
\nAdditionally, filters support AND and OR logic, and can be nested. Check-out the filter structure below:
{\n filter: {\n logic: \"and|or\",\n conditions: [\n {\n // regular filter\n field: \"field_name\",\n operator: \"eq|neq|...\",\n value: \"filtering value\"\n },\n {\n // nested filter\n logic: \"and|or\",\n conditions: [ /*...*/ ]\n },\n ...\n ]\n }\n}\n\nThe action endpoint is designed for reporting and tracking user actions related to specific Harmix search results on the client's web platform. It relies on session identifiers like session_id to associate user actions, such as audio downloads, purchases, playback interactions, and more, with the corresponding search results. This integration of session data with user actions enables the creation of detailed reports. These reports offer valuable insights into user behavior, helping Harmix optimize the product's user experience, enhance features, and make data-driven decisions for continual improvement and refinement.
\n\nWe highly recommend always using this endpoint after each user's action based on the Harmix features.
\n
action (REQUIRED): The action type from the Action Types table.
session_id (OPTIONAL): A unique identifier associated with a user session or a user's client-side web account. It is utilized to track and report user interactions with Harmix based on their requests. After, the Harmix team subsequently analyzes this data to gain insights and improve the product's performance and user experience. This parameter can represent a session, user ID, or any other ID uniquely identifying the user's interaction with Harmix. We highly recommend always to use this parameter in your requests.
primary_key (REQUIRED): A unique identifier of the track provided in the Harmix search results that is either a Primary Key or a Composite Primary Key:
The Primary Key is represented as the system_id that is received along with the track metadata in the /search response.
The Composite Primary Key is represented as one or multiple fields from the Metadata Schema received in the /search response.
\nThe action type from the Action Types table.
\n","type":"text/plain"},"key":"action","value":"A unique identifier associated with a user session or a user's client-side web account.
\n","type":"text/plain"},"key":"session_id","value":"The reporting endpoints are dedicated to collecting and analyzing data related to user interactions, Harmix's product usage, and other metrics. They utilize session identifiers like session_id to track user behavior and generate comprehensive reports, offering valuable insights to the Harmix team and our clients. These insights drive informed decision-making, facilitating continuous product improvement, feature enhancements, and user experience optimization.
When making the request, you have to specify a correct action type. Currently, we support the following action types:
\n","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"0d2b2d92-a61c-4f53-87e7-a4a86d36bfe2"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"4bb99d9d-3a96-4e06-93a4-29486fabe809"}}],"_postman_id":"d270463f-cb6d-4768-a022-82b6aeef4de2"},{"name":"Tagging Endpoints","item":[{"name":"Tag Track","id":"a0f4e1a8-dff4-4ac3-aea4-475d8bbc2bb6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"multipart/form-data","type":"text"}],"body":{"mode":"formdata","formdata":[{"key":"facets","value":"[\"key\", \"bpm\", \"genres\", \"moods\", \"instruments\"]","contentType":"application/json","type":"text","description":"A list of classification attributes.
\n"},{"key":"track_id","value":"A unique track identifier.
\n"},{"key":"track","contentType":"","type":"file","description":"An audio file.
\n","fileNotInWorkingDirectoryWarning":"This file isn't in your working directory. Teammates you share this request with won't be able to use this file. To make collaboration easier you can setup your working directory in Settings.","filesNotInWorkingDirectory":["/Users/Shared/audio.mp3"],"src":"/Users/Shared/audio.mp3"},{"key":"webhook","value":"Your webhook URL.
\n","type":"text"}]},"url":"https://api.harmix.ai/tag","description":"Upload your audio track for tagging. Upon successful upload, you will receive an HTTP status 201 Created response containing a unique track_id, which can be used to check the processing status. The track will be processed asynchronously.
Additionally, specify the webhook URL in your request; the processing pipeline will call this URL once the track has been processed.
The webhook URL must not require authentication.
You can upload only MP3, WAV, and M4A audio formats with a file size limit of 120 MB.
\nIf you're using Angular or possibly other JS FE frameworks to upload files, be aware of a need to set the Content-Type header to undefined to allow the HTTP client to generate the correct multipart boundary.
facets (REQUIRED): This parameter specifies the classification attributes you expect in the tagging results. It should be a list of desired facets, such as key, BPM, genre, mood, and instruments. These facets help categorize the audio track by its musical characteristics and metadata.
track_id (REQUIRED): This parameter is used to uniquely identify your track during processing and upon results retrieval.
track (REQUIRED): This parameter is used to upload an audio track file to the server for processing. The audio file should be provided as a file attachment, and its path on the local system should be specified. Ensure that the audio file format is supported by the API (e.g., MP3, WAV, M4A).
webhook (OPTIONAL): This parameter allows you to specify a URL to which the API will send a response once the track processing is complete. This can be useful for receiving notifications or updates about the processing status or results. While not mandatory, providing a webhook URL can be beneficial for tracking and managing the processing workflow.
The following payload is sent to your webhook on success:
\n{\n \"track_id\": \"3c41f3c8-476e-41ae-b04d-9620cc7be700\",\n \"tags\": {\n \"key\": [\n \"D minor\"\n ],\n \"bpm\": 92,\n \"genres\": [\n \"Rap\",\n \"Hip-Hop\"\n ],\n \"moods\": [\n \"Criminal\",\n \"Serious\",\n \"Dark\"\n ],\n \"instruments\": [\n \"Electronic Drums\",\n \"Synthesizer\",\n \"Piano\",\n \"Synth Bass\"\n ]\n },\n \"processing_details\": {\n \"processing_status\": 1,\n \"processed_at\": \"2024-01-31 12:34:56.000000\"\n }\n}\n\nGet track processing status by its Track ID.
\nAt each stage of processing, each track is assigned a processing_status code.
track_id (REQUIRED): Track ID.
version (OPTIONAL): Returns tags along with their resprective scores if set to 2.
Harmix offers a sophisticated taxonomy for audio tagging, ensuring high-quality results. You can upload your audio track for asynchronous tagging, and we guarantee delivery of the results via your webhook within one day. Additionally, we provide an endpoint to check the tagging status or manually retrieve the results.
\nWhen making a request, you need to specify the classification attributes (facets) you expect to receive in the tagging results. Currently, we support the following attributes:
\n","auth":{"type":"apikey","apikey":{"value":"Get the history of all conversations. Provide user_id to get conversations for a specific user.
Results are ordered by update_time property in descending order.
The response contains a list of conversations with their metadata:
\ntotal: The total number of conversations for the provided user.
messages: A list of messages, details schema is described below.
id: Conversation unique identifier.
title: Title of the conversation.
user_id: User unique identifier.
create_time: Datetime object of when the conversation was created.
update_time: Datetime object of the last update of the conversation.
{\n \"total\": int,\n \"conversations\": [\n {\n \"id\": string,\n \"title\": string,\n \"user_id\": string,\n \"create_time\": datetime,\n \"update_time\": datetime\n },\n ...\n ]\n}\n\n(OPTIONAL) Fetch conversations for the given user identifier – arbitrary value from your system.
\n","type":"text/plain"},"key":"user_id","value":"(OPTIONAL) Number of conversations to return. Default: 50. Minimum: 1. Maximum: 100.
\n","type":"text/plain"},"key":"limit","value":"50"},{"description":{"content":"(OPTIONAL) The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items.
\n","type":"text/plain"},"key":"offset","value":"0"}],"variable":[]}},"response":[{"id":"47a58763-ea96-4235-9164-7f79dd74386a","name":"200 OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://uat.api.harmix.ai/conversations?user_id=Get detailed metadata of one conversation by its unique identifier. Fetch its metadata and a list of all messages from the conversation.
\nThe conversation object is returned with its metadata and messages in the following structure:
\nid: Conversation unique identifier.
title: Title of the conversation.
user_id: User unique identifier.
create_time: Datetime object of when the conversation was created.
update_time: Datetime object of the last update of the conversation.
messages: A list of objects of all messages in this conversation. Its schema is explained below.
id: Message unique identifier.
author: Author of the message: user or assistant.
create_time: Datetime object of when the message was created.
message: Text content of the message.
attachments: List of attachments which schema is explained in Attachments.
filters: Object with filters, read detailed object specification in Filtering.
{\n \"id\": string,\n \"title\": string,\n \"user_id\": string,\n \"create_time\": datetime,\n \"update_time\": datetime,\n \"messages\": [\n {\n \"id\": string,\n \"author\": \"user\" | \"assistant\",\n \"create_time\": datetime,\n \"message\": string,\n \"attachments\": [\n ... // Attachment object\n ],\n \"filters\": object | null // Filters object\n },\n ...\n ]\n}\n\nUnique conversation identifier.
\n","type":"text/plain"},"type":"any","value":"6758364f-60a8-8009-a6d1-97a3614f31bc","key":"conversation_id"}]}},"response":[{"id":"b22fea98-b71a-4bbe-bb2e-cb5a9ea75284","name":"200 OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://uat.api.harmix.ai/conversations/:conversation_id","protocol":"https","host":["uat","api","harmix","ai"],"path":["conversations",":conversation_id"],"variable":[{"key":"conversation_id","value":"6758364f-60a8-8009-a6d1-97a3614f31bc","description":"Unique conversation identifier."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"content-type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"6758364f-60a8-8009-a6d1-97a3614f31bc\",\n \"title\": \"Music Search\",\n \"user_id\": \"123\",\n \"create_time\": \"2024-12-15T10:49:52.699Z\",\n \"update_time\": \"2024-12-15T10:49:52.699Z\",\n \"messages\": [\n {\n \"id\": \"6758364f-60a8-8009-a6d1-97a3614f31bc\",\n \"author\": \"user\",\n \"create_time\": \"2024-12-15T10:49:52.699Z\",\n \"message\": \"The first message\",\n \"attachments\": [\n {\n \"id\": \"6758364f-60a8-8009-a6d1-97a3614f31bc\",\n \"type\": \"internal-track\",\n \"metadata\": {\n \"audio_url\": \"https://s3:track.mp3\",\n \"track_title\": \"Track title\",\n \"artists\": [\n \"Artist 1 name\"\n ],\n \"duration\": 140,\n \"tags\": [\n \"guitar\"\n ]\n }\n }\n ],\n \"filters\": null\n }\n ]\n}"}],"_postman_id":"28f84c7e-39ff-4c1b-94f0-774318e5c601"},{"name":"Send Message","id":"108ab181-751b-4a58-9356-28ef49e7c002","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n\t\"conversation_id\": \"6758364f-60a8-8009-a6d1-97a3614f31bc\",\n \"user_id\": \"123\",\n\t\"content\": {\n\t\t\"message\": \"Hello assistant\"\n }\n}\n","options":{"raw":{"language":"json"}}},"url":"https://uat.api.harmix.ai/conversations","description":"Send a message to Harmix AI Chat. You can continue an existing conversation or create a new one.
\nIn addition to a text message, you can also send attachments: internal track from your Harmix database or a manually uploaded file. See the schema below for how to send these attachments.
\nTo upload a file to Harmix, use the Upload Reference File endpoint to send file content to the system. The endpoint will return you upload_id which you should pass to the request as written in the next section.
conversation_id (OPTIONAL): Unique conversation identifier. The message will be added to an existing conversation if the identifier is provided. Otherwise, a new conversation will be created.
user_id (REQUIRED): Arbitrary user identifier from your system to assign conversation to a user. The value and format are up to you; you can provide the user identifier from your system to make the search easier. This value will be associated with a new conversation. In case you provide conversation_id, the previous user_id value must match the given one.
message (REQUIRED): A text message you send to the Chat.
attachments (OPTIONAL): A list of objects containing attachments for a text message. The object consists of these properties:
id: Pass track's system_id for internal attachment or upload_id for file attachment.
type: Attachment type such internal-track for a track from your database or file-upload for an uploaded file.
filters (OPTIONAL): Object with filters, read detailed object specification in Filtering.
The body object has the following structure:
\n{\n \"conversation_id\": string,\n \"user_id\": string,\n \"message\": string,\n \"attachments\": [\n {\n \"id\": string, // system_id, upload_id\n \"type\": \"internal-track\" | \"file-upload\"\n },\n ...\n ] | null,\n \"filters\": FiltersObject | null\n}\n\nThe response message is returned as a series of Server-sent events. The conversation metadata is sent, and the response text is attached. The text response from the Chat is returned in parts over a series of such events. Each message contains a text, which, combined, gives the complete response.
\nSuch an interface lets the server send events in a stream to report real-time processing status. It provides a seamless user experience when the message is gradually loaded for more extended responses.
\n\n\nRead more about Server-sent events here.
\n
You can find the sample sequence of this stream in the example response for this request.
\nThe server sends different event types to notify a client what data to expect. Below is the explanation of all types and the object returned with it.
\nmetadata – conversation metadata which includes any fields from the object below (some of the properties can be null).
\n{\n \"conversation_id\": string | null,\n \"create_time\": datetime | null,\n \"update_time\": datetime | null,\n \"title\": string | null\n}\n\nmessage – part of the response text message which is returned whenever it becomes available. Join all parts together as you keep receiving them.
\n{\n \"text\": string\n}\n\nattachments – attachments to the response message. Read more details about the schema in Attachments.
\n","urlObject":{"protocol":"https","path":["conversations"],"host":["uat","api","harmix","ai"],"query":[],"variable":[]}},"response":[{"id":"d795e077-64fc-4d0f-8429-1909e6e607b3","name":"200 OK","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"conversation_id\": \"6758364f-60a8-8009-a6d1-97a3614f31bc\",\n \"user_id\": \"123\",\n \"message\": \"Hello assistant\"\n}","options":{"raw":{"language":"json"}}},"url":"https://uat.api.harmix.ai/conversations"},"status":"OK","code":200,"_postman_previewlanguage":"plain","header":[{"key":"transfer-encoding","value":"chunked"}],"cookie":[],"responseTime":null,"body":"event: metadata\ndata: {\"conversation_id\": \"6758364f-60a8-8009-a6d1-97a3614f31bc\", \"create_time\": \"2024-12-15T10:49:52.699Z\", \"update_time\": \"2024-12-15T10:49:52.699Z\"}\n\nevent: message\ndata: {\"text\": \"This is \"}\n\nevent: message\ndata: {\"text\": \"a response\"}\n\nevent: message\ndata: {\"text\": \" from Harmix.\"}\n\nevent: attachments\ndata: [{\"id\": \"5432364f-60a8-8009-a6d1-97a3614f31bc\", \"type\": \"playlist\"}, {\"id\": \"6758364f-60a8-8009-a6d1-97a3614f31bc\", \"type\": \"internal-track\", \"metadata\": {\"audio_url\": \"https://s3:track.mp3\", \"title\": \"Track title\", \"artists\": [\"Artist 1 name\"], \"duration\": 140, \"tags\": [\"guitar\"]}}]\n\nevent: metadata\ndata: {\"title\": \"Your first chat conversation\"}\n\n"}],"_postman_id":"108ab181-751b-4a58-9356-28ef49e7c002"}],"id":"5c7c9572-15af-425e-9b44-241bf10222c2","description":"Harmix AI Chat helps you to search for music with a chat interface. You can send one-time messages or handle long-term conversations with the chat to find music for your prompt. With these endpoints, you can load the history of your conversations and send new messages.
Each conversation must be associated with user_id to connect it to a specific user. The value of user_id is arbitrary and is totally up to you. Therefore, we recommend you use a user identifier from your system to simplify the integration.
Each conversation message can have an attachment in addition to a text message. These are internal tracks, uploaded files or playlists. The following section explains which types are supported and their object schema.
\ntype: Type of the attachment: internal-track, playlist, file-upload, audio-reference.
id: Unique identifier of the attachment. Its nature depends on the attachment type: this identifier may point to the internal track system_id, upload_id of the uploaded file, or playlist's playlist_id.
metadata: Additional metadata for the attachment. Its properties depend on the attachment type and are explained in more details below.
{\n \"type\": \"internal-track\" | \"playlist\" | \"file-upload\" | \"audio-reference\",\n \"id\": string,\n \"metadata\": object | null\n}\n\ninternal-track – a track in Harmix database. id is the system_id of the internal track. Metadata object is the same as in Metadata Schema.
{\n \"id\": string, // system_id\n \"type\": \"internal-track\",\n \"metadata\": {\n ... // Track Metadata Schema\n }\n}\n\nplaylist – a playlist created for this message. id is playlist_id. It does not have any additional metadata.
{\n \"id\": string, // playlist_id\n \"type\": \"playlist\",\n \"metadata\": null\n}\n\nfile-upload – a manually uploaded file. id is upload_id of the uploaded file. Metadata contains properties of the file.
{\n \"id\": string, // upload_id\n \"type\": \"file-upload\",\n \"metadata\": {\n \"type\": string,\n \"file_name\": string,\n \"file_url\": string\n }\n}\n\naudio-reference – a reference from audio services such Spotify and YouTube. Metadata contains information about the audio source.
\n{\n \"id\": string,\n \"type\": \"audio-reference\",\n \"metadata\": {\n \"source\": \"spotify\" | \"youtube\",\n \"source_url\": string\n }\n}\n\nGet a playlist detailed metadata for a unique playlist identifier.
\n","auth":{"type":"apikey","apikey":{"value":"Unique playlist identifier.
\n","type":"text/plain"},"type":"any","value":"6758364f-60a8-8009-a6d1-97a3614f31bc","key":"playlist_id"}]}},"response":[{"id":"b0960424-b376-4ce8-82f2-f263ae964a39","name":"Existing playlist","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api.harmix.ai/playlists/:playlist_id","protocol":"https","host":["api","harmix","ai"],"path":["playlists",":playlist_id"],"variable":[{"key":"playlist_id","value":"6758364f-60a8-8009-a6d1-97a3614f31bc","description":"Unique identifier of a playlist."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"content-type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"6758364f-60a8-8009-a6d1-97a3614f31bc\",\n \"title\": \"Test playlist\",\n \"metadata\": {\n \"bpm\": 160\n },\n \"create_date\": \"2024-12-15T10:49:52.699Z\",\n \"tracks_number\": 10,\n \"tracks\": [\n {\n \"system_id\": \"6758364f-60a8-8009-a6d1-97a3614f31bc\",\n \"add_time\": \"2024-12-15T10:49:52.699Z\",\n \"metadata\": {\n \"title\": \"Test track\",\n \"artist\": \"Test artist\",\n \"duration\": 180\n }\n }\n ]\n}"}],"_postman_id":"df44c3b0-bf3c-424b-9e81-6f0966dca64a"},{"name":"Create Playlist","id":"0afb4344-341d-4569-89d8-2d2ceed49c6f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"title\": \"New playlist\",\n \"tracks\": [\n {\n \"system_id\": \"6758364f-60a8-8009-a6d1-97a3614f31bc\"\n }\n ]\n}\n","options":{"raw":{"language":"json"}}},"url":"https://api.harmix.ai/playlists","description":"Create a new playlist from a list of internal tracks.
\ntitle (REQUIRED): A title for the playlist.
user_id (OPTIONAL): An identifier of the user who owns the playlist.
tracks (REQUIRED): A list of tracks to include in the playlist.
system_id (REQUIRED): Unique track identifier.Add a track to a specific playlist.
\n","auth":{"type":"apikey","apikey":{"value":"Unique playlist identifier.
\n","type":"text/plain"},"type":"any","value":"6758364f-60a8-8009-a6d1-97a3614f31bc","key":"playlist_id"},{"description":{"content":"Internal system identifier of the track.
\n","type":"text/plain"},"type":"any","value":"c5f7274f-a2f0-5c00-851a-d27404e56476","key":"system_id"}]}},"response":[{"id":"8834b9b9-c8ab-43ef-bebf-6541238a9be2","name":"200 OK","originalRequest":{"method":"POST","header":[],"url":{"raw":"https://api.harmix.ai/playlists/:playlist_id/tracks/:system_id","protocol":"https","host":["api","harmix","ai"],"path":["playlists",":playlist_id","tracks",":system_id"],"variable":[{"key":"playlist_id","value":"6758364f-60a8-8009-a6d1-97a3614f31bc","description":"Unique playlist identifier."},{"key":"system_id","value":"c5f7274f-a2f0-5c00-851a-d27404e56476","description":"Internal system identifier of the track."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"content-type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \":playlist_id\",\n \"title\": \"Test playlist\",\n \"metadata\": {\n \"bpm\": 160\n },\n \"create_date\": \"2024-12-15T10:49:52.699Z\",\n \"tracks_number\": 10,\n \"tracks\": [\n {\n \"system_id\": \"6758364f-60a8-8009-a6d1-97a3614f31bc\",\n \"add_time\": \"2024-12-15T10:49:52.699Z\",\n \"metadata\": {\n \"title\": \"Test track\",\n \"artist\": \"Test artist\",\n \"duration\": 180\n }\n },\n {\n \"system_id\": \":track_id\",\n \"add_time\": \"2024-12-15T10:49:52.699Z\",\n \"metadata\": {\n \"title\": \"Test track new\",\n \"artist\": \"Test artist new\",\n \"duration\": 164\n }\n }\n ]\n}"}],"_postman_id":"81e7509c-cb4c-4956-a908-b1736bd34d92"},{"name":"Delete Track from Playlist","id":"6b9a3185-9af5-4494-a79e-0471b66d9710","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[],"url":"https://api.harmix.ai/playlists/:playlist_id/tracks/:system_id","description":"Delete a specific track from a playlist.
\n","auth":{"type":"apikey","apikey":{"value":"Unique playlist identifier.
\n","type":"text/plain"},"type":"any","value":"6758364f-60a8-8009-a6d1-97a3614f31bc","key":"playlist_id"},{"description":{"content":"Internal system identifier of the track.
\n","type":"text/plain"},"type":"any","value":"c5f7274f-a2f0-5c00-851a-d27404e56476","key":"system_id"}]}},"response":[{"id":"b6424c14-8694-4988-8fbf-49e09910d3f0","name":"202 Accepted","originalRequest":{"method":"DELETE","header":[],"url":{"raw":"https://api.harmix.ai/playlists/:playlist_id/tracks/:system_id","protocol":"https","host":["api","harmix","ai"],"path":["playlists",":playlist_id","tracks",":system_id"],"variable":[{"key":"playlist_id","value":"6758364f-60a8-8009-a6d1-97a3614f31bc","description":"Unique playlist identifier."},{"key":"system_id","value":"c5f7274f-a2f0-5c00-851a-d27404e56476","description":"Internal system identifier of the track."}]}},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"content-type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"6758364f-60a8-8009-a6d1-97a3614f31bc\",\n \"title\": \"Test playlist\",\n \"bpm\": 160,\n \"create_date\": \"2024-12-15T10:49:52.699Z\",\n \"tracks_number\": 10,\n \"tracks\": [\n {\n \"system_id\": \"6758364f-60a8-8009-a6d1-97a3614f31bc\",\n \"add_time\": \"2024-12-15T10:49:52.699Z\",\n \"metadata\": {\n \"title\": \"Test track\",\n \"artist\": \"Test artist\",\n \"duration\": 180\n }\n }\n ]\n}"}],"_postman_id":"6b9a3185-9af5-4494-a79e-0471b66d9710"},{"name":"Recommend New Tracks for a Given Playlist","id":"cb84796e-c561-4e5c-9144-078f6c3bfed3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"playlist_id\": \"6758364f-60a8-8009-a6d1-97a3614f31bc\",\n \"size\": 10\n}\n","options":{"raw":{"language":"json"}}},"url":"https://api.harmix.ai/playlists/recommendations/tracks","description":"Get recommendations for new tracks for a given playlist. The Harmix recommendation system analyses the tracks in the playlist and its metadata to suggest tracks for your playlist.
\nThe list of suggested tracks is returned together with their metadata. Each track also comes with a score – a metric of how well it fits in the given playlist.
\n\nThese tracks are not added to the playlist automatically. You can add tracks you like with the POST Add Track to Playlist endpoint.
\n
playlist_id (REQUIRED): Unique playlist identifier.
size (REQUIRED): Number of tracks to recommend. The maximum value is 100.
cluster (OPTIONAL) [DEFAULT: false]: Determines how the recommended tracks are grouped. When set to true, the system will group the tracks in the playlist into clusters, and the recommendations will be made based on these clusters. When set to false, the tracks are not grouped into clusters, and the recommendations are made from the entire playlist.
The Playlist Endpoints let you create, retrieve and manage playlists on Harmix.
\nA Playlist is a list of tracks combined around a similar theme. It consists of tracks from your Harmix catalog. Besides that, the playlist has a title and common metadata.
\nThese playlist metadata properties are supported by now:
\nbpm: int – the average value of bpm over all tracks in the playlistHarmix provides you with recommended playlists for your request, and you can create one from a list of internal tracks. Explore all opportunities at the endpoints of this collection.
\n\n\n","auth":{"type":"apikey","apikey":{"value":"The maximum size of a playlist is 1,000 tracks.
\n
The all-search endpoint is a powerful search feature that processes a simple search query to return a diverse array of results, including tracks, artists, playlists, albums, etc. By integrating multiple categories into a single query response, this endpoint provides users with a holistic and intuitive search experience, ensuring they find exactly what they're looking for with minimal effort.
\n\n\nResults are sorted by relevance, from highest to lowest.
\n
query (REQUIRED): A string input that represents the user's search term. This parameter accepts a simple text string and processes it to retrieve a comprehensive set of results, including tracks, artists, playlists, albums, etc. The query can include keywords, phrases, or partial names. It is designed to handle various user inputs, from specific titles and artist names to general music genres and podcast topics, ensuring a broad search capability.
session_id (OPTIONAL): A unique identifier associated with a user session or a user's client-side web account. It is utilized to track and report user interactions with Harmix based on their requests. After, the Harmix team subsequently analyzes this data to gain insights and improve the product's performance and user experience. This parameter can represent a session, user ID, or any other ID uniquely identifying the user's interaction with Harmix. We highly recommend always to use this parameter in your requests.
Harmix allows for a comprehensive and all-encompassing search functionality, enabling users to effortlessly discover tracks, artists, playlists, and more with a single query.
\n","_postman_id":"5e7a1a2c-6d6a-487d-80ea-6a735fc8b573"}],"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"a55ab518-1997-4a9d-a154-b91eb37faf20"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"5b19b339-bbf8-4aef-8719-7054eddcc178"}}],"variable":[{"key":"baseUrl","value":"https://farming-simulator.pstmn.io"}]}