Free Text Search

You can use Cyanite.ai API to search for tracks that match a specific free text description. This functionality is available through query.freeTextSearch.

Specifying a Target

The query.freeTextSearch query has a required parameter which is the query.freeTextSearch(target:) argument of the FreeTextSearchTarget input type. This argument specifies what kind of search results we want. Currently, it is possible to get results from the library, or Spotify.

Target	query.freeTextSearch(target:) value
library	{ library: {} }
spotify	{ spotify: {} }

caution

It is only possible to specify one target. Mixing options e.g. { library: {}, spotify: {} } might result in an error.

Specifying a Search Text

To specify the search text you need to set the query.freeTextSearch(searchText:) parameter, the type of this parameter is String and it has no restrictions aside from being an English text. If the search text is in any other language, the results might not make sense.

Specify an amount of tracks to fetch

By default the query.freeTextSearch quey will return up to 10 tracks, given they match all the specified filters and there are enough available. It is possible to fetch up to 100 songs by specifying the query.freeTextSearch(first:) argument of the Int type.

Example Query (Spotify)

query FreeTextSearchExample {
  freeTextSearch(
    first: 10
    target: { spotify: {} }
    searchText: "relaxing and quiet song for meditation"
  ) {
    ... on FreeTextSearchError {
      message
      code
    }
    ... on FreeTextSearchConnection {
      edges {
        cursor
        node {
          id
          title
        }
      }
    }
  }
}

Response

{
  "data": {
    "freeTextSearch": {
      "edges": [
        {
          "cursor": "3hlJJFZfkVcJInmQHjybmQ",
          "node": {
            "id": "3hlJJFZfkVcJInmQHjybmQ",
            "title": "HeadLab INC. - Prelude"
          }
        },
        {
          "cursor": "2v3zGxXL4uE4pBcWrrWBY8",
          "node": {
            "id": "2v3zGxXL4uE4pBcWrrWBY8",
            "title": "The Cat and Owl - Begin the Beguine"
          }
        },
        {
          "cursor": "2im8y2Qrnj0xvt5c9BgNYF",
          "node": {
            "id": "2im8y2Qrnj0xvt5c9BgNYF",
            "title": "Chris Walla - Kanta's Theme"
          }
        },
        {
          "cursor": "402eCegPnC05HLdbx6Ds3r",
          "node": {
            "id": "402eCegPnC05HLdbx6Ds3r",
            "title": "Ageena - Finally You Needed Me"
          }
        },
        {
          "cursor": "3JluMpRA2buMEgVjFU8YMj",
          "node": {
            "id": "3JluMpRA2buMEgVjFU8YMj",
            "title": "Daniel Patarava - Grand Hotel"
          }
        },
        {
          "cursor": "6kEYoPEp74I13PoZbrBhrq",
          "node": {
            "id": "6kEYoPEp74I13PoZbrBhrq",
            "title": "audio ark 9 - Lost and Found"
          }
        },
        {
          "cursor": "2YFTQtEwhO5GginJoN5h48",
          "node": {
            "id": "2YFTQtEwhO5GginJoN5h48",
            "title": "Shearwater - Missing Islands"
          }
        },
        {
          "cursor": "0uEv3TJJXLtLc5K5AyDb0R",
          "node": {
            "id": "0uEv3TJJXLtLc5K5AyDb0R",
            "title": "Paul Haslinger - Phoenix"
          }
        },
        {
          "cursor": "2os8XYkCWhd7t9iPv6OVm1",
          "node": {
            "id": "2os8XYkCWhd7t9iPv6OVm1",
            "title": "Kevin Moore - Hallways and Light"
          }
        },
        {
          "cursor": "0ZMHR34vwloqw798ogZmmg",
          "node": {
            "id": "0ZMHR34vwloqw798ogZmmg",
            "title": "Deep Inside - Morning Hue"
          }
        }
      ]
    }
  }
}

Example Query (Library)

query FreeTextSearchExample {
  freeTextSearch(
    first: 10
    target: { library: {} }
    searchText: "relaxing and quiet song for meditation"
  ) {
    ... on FreeTextSearchError {
      message
      code
    }
    ... on FreeTextSearchConnection {
      edges {
        cursor
        node {
          id
          title
        }
      }
    }
  }
}

Response

{
  "data": {
    "freeTextSearch": {
      "edges": [
        {
          "cursor": "1681618",
          "node": {
            "id": "1681618",
            "title": "7eb5cc1aa51e49f6/589646f128c1d004/3c42bf06f115a583"
          }
        },
        {
          "cursor": "1841452",
          "node": {
            "id": "1841452",
            "title": "08c2b1fdfa7b9167/a94b9845f143e86b/de4ff33d0538885a"
          }
        },
        {
          "cursor": "1497201",
          "node": {
            "id": "1497201",
            "title": "5ac224c86dc9fca2/c743bba1081f2f0e/54fdfde827f2fba5"
          }
        },
        {
          "cursor": "1579601",
          "node": {
            "id": "1579601",
            "title": "b26d404cace45cd3/ffce9e7d443cef74/7ab12d39e875bf75"
          }
        },
        {
          "cursor": "1512108",
          "node": {
            "id": "1512108",
            "title": "70cb3c0497fe0fbd/661c9364d4812bf2/1ebadb9b58d60a2b"
          }
        },
        {
          "cursor": "1670008",
          "node": {
            "id": "1670008",
            "title": "658cccfee3088ddc/8c63ebb3bfcba267/094dd902686b27bb"
          }
        },
        {
          "cursor": "1578819",
          "node": {
            "id": "1578819",
            "title": "b26d404cace45cd3/84c941feb2f9892b/5f0ce08e0cd869ae"
          }
        },
        {
          "cursor": "1509668",
          "node": {
            "id": "1509668",
            "title": "70cb3c0497fe0fbd/1c20b8829256493a/9b0f1658d57fde82"
          }
        },
        {
          "cursor": "1686149",
          "node": {
            "id": "1686149",
            "title": "8467005e2d79c5ad/6663be42a395a16b/1a42464d74bdcaec"
          }
        },
        {
          "cursor": "1729168",
          "node": {
            "id": "1729168",
            "title": "bbcf9e8c23cbeb9f/1fd1eac5be747cc1/bc973f893dd3f46a"
          }
        }
      ]
    }
  }
}