{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"c3127063-b6d8-4572-afcc-52e337608da0","name":"Harmix API Documentation","description":"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.\n\n---\n\n# 📄 Overview\n\nHarmix provides a variety of searches to satisfy your needs:\n\n- **Prompt Search**: Search music in your catalog using free text. For example: _Lush and uplifting instrumental featuring guitar and piano for a reflective mood._\n    \n- **Video Search**: Upload your video to get the ideal music match that fits the mood.\n    \n- **Similarity Search**: Provide reference track(s) to find similar ones in your catalog.\n    \n- **Story 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._\n    \n\n---\n\n# 🚀 How to Integrate\n\n### Uploading Your Catalog\n\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](#1543852a-de15-4e0d-b868-3aee3f393289) for you to be able to upload your music catalog to Harmix's environment to be processed there and become available for search asynchronously.\n\nAll you need to do is upload an audio file and specify its metadata with the [source_id](#metadata-schema) 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](#dc5f2dca-f6c7-4276-84db-b5a893303c49) endpoint.\n\nOnce the track is uploaded and processed, you can make it available for search on your platform or application.\n\n### Executing CRUD Queries\n\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.\n\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.\n\nTherefore, we provide primary API endpoints to support your [CRUD operations](#1543852a-de15-4e0d-b868-3aee3f393289) within your catalogs on our side.\n\n### Performing Search Queries\n\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](#770050a2-600c-4021-b8eb-84eb435f3070) endpoint.\n\n---\n\n# 📒 Metadata Schema\n\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> Don't hesitate to contact us if you want to upload more metadata not present in the predefined schema. \n  \n\n### Primary Key\n\nThe **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.\n\n### Extra Metadata Parameters\n\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\n``` json\n{\n    \"custom_attribute_1\": \"value1\",\n    \"custom_attribute_2\": \"value2\",\n    \"tags\": \"[\\\"tag1\\\", \\\"tag2\\\", \\\"tag3\\\"]\",\n    \"related_ids\": \"[\\\"123\\\", \\\"456\\\", \\\"789\\\"]\"\n}\n\n ```\n\n### Schema\n\n| Name | Type | Required | Primary Key Component | Description | Example |\n| --- | --- | --- | --- | --- | --- |\n| source_id | String | **Yes** | **Yes** | Unique identifier for your system to be able to match results from Harmix with your internal databases. | 1234-5678-3456 |\n| isrc | String | No | **Yes** | International Standard Recording Code. | AB1234567890 |\n| track_title | String | **Yes** | **Yes** | Name of the track. | Sunflower |\n| track_number | String | No | **Yes** | Number of the track on an album. | 12 |\n| track_code | String | No | **Yes** | Code of the track. Usually, it is created from label code, album number, and track number. | HRMX9#12 |\n| track_description | String | No | No | Description of the track. | A track that conveys a sense of hope, loyalty, and love for someone or something that is unique and special. |\n| version | Bool | No | No | Indicates if the track is a version of another track. | False |\n| version_tag | String | **No** | **Yes** | Version type, e.g. Main, 60s, No Drums, Instrumental, etc. | Main |\n| version_name | String | No | No | Name of the track with a version tag. | Sunflower (Main) |\n| versions_number | Integer | No | No | Number of track versions. | 5 |\n| master_id | String | No | No | Unique identifier of the master track from which the current child track is derived. | 1234-5678 |\n| label_name | String | No | **Yes** | Name of the label. | Harmix Records |\n| label_code | String | No | **Yes** | Code of the label. | HRMX |\n| album_id | String | No | **Yes** | Album ID. | hrmx-albm-rck3 |\n| album_number | String | No | **Yes** | Number of the album. | 3 |\n| album_code | String | No | **Yes** | Code of the album. Usually, label code and album number. | HRMX3 |\n| album_name | String | No | No | Name of the album. | Happy evenings |\n| album_description | String | No | No | Description of the album. | Music for happy evenings |\n| album_cover_url | String | No | No | URL to the album cover image. | [https://harmix.ai/storage/hrmx-albm-rck3-cover.jpg](https://harmix.ai/storage/hrmx-albm-rck3-cover.jpg) |\n| album_keywords | Array\\[String\\] | No | No | An array of keywords for the album the track belongs to. | \\[\"Happy\", \"Enticing\"\\] |\n| release_year | Integer | No | **Yes** | Release year of the track. | 2017 |\n| release_date | String | No | **Yes** | Release date of the track in the following format: YYYY-MM-DD. | 2017-12-05 |\n| duration | Integer | No | No | Duration of the track in seconds. | 224 |\n| tempo | String | No | No | Tempo of the track (not BPM). | slow |\n| bpm | Integer | No | **Yes** | Beats per minute.  <br>**Validation rule**: value must be greater than 0. | 80 |\n| key | String | No | **Yes** | Musical key of the track. | D#m |\n| time_signature | String | No | **Yes** | Track time signature that indicates how many beats are in each measure (or bar) and what type of note gets one beat. | 3/4 |\n| is_instrumental | Bool | No | **Yes** | Indicator whether the track is instrumental. | False |\n| is_vocal | Bool | No | **Yes** | Indicator whether the track is vocal. | True |\n| lyrics | String | No | No | Lyrics of the track. | \"You’re the sunflower, …\" |\n| lyrics_language | String | No | No | Language of the lyrics. | EN |\n| explicit_lyrics | Bool | No | **Yes** | Indicator of the track having explicit lyrics. | False |\n| artists | Array\\[String\\] | No | No | An array of artist names who created the track. | \\[\"John Doe\", \"Jane Doe\"\\] |\n| composers | Array\\[String\\] | No | No | An array of composer names who created the track. | \\[\"John Doe\", \"Jane Doe\"\\] |\n| genres | Array\\[String\\] | No | No | An array of genres of the track. | \\[\"Pop\", \"Rap\"\\] |\n| moods | Array\\[String\\] | No | No | An array of moods of the track. | \\[\"Happy\", \"Enticing\"\\] |\n| instruments | Array\\[String\\] | No | No | An array of instruments featured in the track. | \\[\"Piano\", \"Acoustic guitar\"\\] |\n| music_keywords | Array\\[String\\] | No | No | An array of possible track usages (music for/suitable for). | \\[\"Commercial\", \"Cafe\", \"Games\"\\] |\n| decades | Array\\[String\\] | No | No | An array of track decades. | \\[\"2010s\"\\] |\n| vocals | Array\\[String\\] | No | No | An array of track vocals. | \\[\"vocal\", \"male vocal\"\\] |\n| available_countries | Array\\[String\\] | No | No | An array of markets in which the album is available: [http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). | \\[\"US\", \"UK\", \"DE\", \"FR\"\\] |\n| active | Bool | No | **Yes** | Identifier of the track being filterable based on some arbitrary criteria. | True |\n| licensable | Bool | No | **Yes** | Identifier of the track being filterable by licensability of your tracks. | True |\n| restricted | Bool | No | **Yes** | Identifier of the track being filterable by some internal restrictions on your tracks. | False |\n| commercial | Bool | No | **Yes** | Identifier of the track being filterable by being a commercial or non-commercial track. | True |\n| recognisable | Bool | No | **Yes** | Identifier of the track being filterable by recognisability. | False |\n| sync_history | Bool | No | **Yes** | Identifier of the track being filterable by having a sync history, i.e., being synchronized with visual content. | False |\n| jam_sync | Bool | No | **Yes** | Identifier of the track being filterable by having a jam sync. | False |\n| hit | Bool | No | **Yes** | Identifier of the track being filterable by the track being a hit. | False |\n| top | Bool | No | **Yes** | Identifier of the track being filterable by the track being a top. | False |\n| publishers | Array\\[String\\] | No | No | An array of publishers of the track. | \\[\"Harmix Studio\"\\] |\n| owner | Array\\[String\\] | No | No | An array of track owner names. | \\[\"Owner\"\\] |\n| share | Double | No | No | Used in case of filtering by your share on a track. | 0.5 |\n| external_id | String | No | **Yes** | Used in case of filtering by any external ID of your use. | 1234-5678 |\n| popularity | Double | No | No | Popularity of the track. | 87.5 |\n| audio_url | String | No | No | URL to audio file. | [https://harmix.ai/storage/myaudio.mp3](https://harmix.ai/storage/myaudio.mp3) |\n| waveform_url | String | No | No | URL to the file containing audio waveform. | [https://harmix.ai/storage/myaudio-waveform.json](https://harmix.ai/storage/myaudio-waveform.json) |\n| extra_parameters | Dict\\[String, String\\] | No | No | Dictionary of additional metadata parameters that you want to retain with the audio metadata. | {\"custom_attribute_1\": \"value1\", \"custom_attribute_2\": \"value2\"} |\n\n---\n\n# ✔️ Authentication\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.\n\nIn your API requests, include your API key in the `api_key` header, as shown in the example:\n\n``` json\napi_key: <YOUR-API-KEY>\n\n ```\n\n---\n\n# 🔴 Exceptions\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.\n\nOur API is designed to return exceptions in a standardized JSON structure. This structure includes the following key components:\n\n- **Error Code**: Each exception is associated with a unique error code. This code serves as a specific identifier for the type of exception encountered.\n    \n- **Short 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.\n    \n- **Details**: 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\n``` json\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\n ```\n\nOur documentation includes a readily accessible table containing our internal error codes, each accompanied by descriptive explanations.\n\n| **Code** | **HTTP** | **Description** |\n| --- | --- | --- |\n| 1000 | 500 | Indicates an internal error that led to a denial of service situation. |\n| 1000 | 503 | Indicates that Harmix is unavailable at the moment. |\n| 1001 | 409 | Issued when a user tries to add the same track to the database more than once. |\n| 1002 | 404 | Issued when the requested track record does not exist. |\n| 1003 | 409 | Issued when multiple track records were found for the provided Primary Key. Update the Primary Key field in your request to uniquely identify a single track record. |\n| 1004 | 400 | Issued when the selected reference track has not been processed yet. Try again later once it is processed. |\n| 1005 | 400 | Issued when the selected audio segment exceeds the track's duration. Adjust the segment to fit within the track's limits. |\n| 1006 | 404 | Issued when the selected reference track was not found. Update the audio reference parameters and try again. |\n| 2001 | 400 | Issued when the input audio file does not match the expected format. |\n| 2002 | 400 | Issued when the input audio file is either damaged or inaccessible for reading. |\n| 2003 | 400 | Issued when the number of uploaded files is not within the allowed threshold. |\n| 2004 | 400 | Issued when the provided reference type is invalid. |\n| 2005 | 400 | Issued when the uploaded file size exceeds the maximum allowed limit. |\n| 2006 | 400 | Issued when the provided reference format is invalid. |\n| 3001 | 400 | Issued when the provided audio URL is of an unsupported format, or both the audio URL and audio file are provided. |\n| 4001 | 401 | Issued when failed to authorize the client. Verify that the correct API key was used. |\n| 4002 | 403 | Issued when the authorized client wants to activate the Highlights feature but is forbidden to do so. Get in touch with Harmix Support at [support@harmix.ai](https://mailto:support@harmix.ai) to enable the feature. |\n| 4003 | 403 | Issued when the authorized client does not have access to the request parameter or filter. |","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"31751929","team":5893483,"collectionId":"c3127063-b6d8-4572-afcc-52e337608da0","publishedId":"2s9Ykj9iJU","public":true,"publicUrl":"https://docs.harmix.ai","privateUrl":"https://go.postman.co/documentation/31751929-c3127063-b6d8-4572-afcc-52e337608da0","customColor":{"top-bar":"FFFFFF","right-sidebar":"2E303E","highlight":"7424FF"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/a8e7a865-5a9c-41a0-8676-ffb4d319e436/TG9nby5wbmc=","colors":{"top-bar":"2E303E","right-sidebar":"2E303E","highlight":"7424FF"}},{"name":"light","logo":"https://content.pstmn.io/d5a7aea0-4006-489b-8a56-6b9150ac325a/TG9nbyAoMikucG5n","colors":{"top-bar":"FFFFFF","right-sidebar":"2E303E","highlight":"7424FF"}}]}},"version":"8.10.1","publishDate":"2023-12-12T17:33:10.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/d5a7aea0-4006-489b-8a56-6b9150ac325a/TG9nbyAoMikucG5n","logoDark":"https://content.pstmn.io/a8e7a865-5a9c-41a0-8676-ffb4d319e436/TG9nby5wbmc="}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/22fbfccf73e2e8e7972a0a89ed0aafe61549f9352341d08256c7e77615166e03","favicon":"https://res.cloudinary.com/postman/image/upload/v1702382747/team/inzzbsoyxqtxdyjntkph.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://docs.harmix.ai/view/metadata/2s9Ykj9iJU"}