List of Descriptors
GET /v1/entities/descriptor
Retrieves a list of descriptors.
Request Parameters
Location | Parameter | Type | Required/ Optional | Description |
---|---|---|---|---|
query | render_speed_over |
number | optional | Filter. Will match to records whose average_render_speed is greater than or equal to the provided value |
query | bands.id |
string | optional | Filter. Will match to records that possess a band whose id contains the given string |
query | bands.name |
string | optional | Filter. Will match to records that possess a band whose name contains the given string |
query | cursor |
string | optional | The cursor id of the first record to return. Example: documentary_minimal_intriguing |
query | for_tempo |
number | optional | Filter. Will match to records where the given integer is greater than or equal to min_tempo and less than or equal to max_tempo |
query | id |
string | optional | Filter. Will match to records whose id contains the given string |
query | instruments.id |
string | optional | Filter. Will match to records that possess an instrument whose id contains the given string |
query | instruments.name |
string | optional | Filter. Will match to records that possess an instrument whose name contains the given string |
query | limit |
number | optional | The number of records to return. May be a value between 1 and 100 inclusive. If a value is not specified, the default is 10 |
query | max_tempo |
number | optional | Filter. Will match to records whose max_tempo matches the given integer |
query | min_tempo |
number | optional | Filter. Will match to records whose min_tempo matches the given integer |
query | name |
string | optional | Filter. Will match to records whose name contains the given string |
query | offset |
number | optional | The numeric offset of the first record to return. May be a value between 1 and 100,000 inclusive |
query | tags.category |
string | optional | Filter. Will match to records that possess a tag whose category contains the given string id |
query | tags.id |
string | optional | Filter. Will match to records that possess a tag whose id contains the given string |
query | tags.name |
string | optional | Filter. Will match to records that possess a tag whose name contains the given string |
For a description of how to use these query parameters, see Pagination.
Example Request
Header
GET /v1/entities/descriptor?offset=0&limit=1 HTTP/1.1
Host: api.ampermusic.com
Content-Type: application/vnd.api+json
Authorization: Basic abcxyz
Response Data
Data Item | Type | Description |
---|---|---|
data |
array | |
data[].attributes |
object | |
data[].attributes.average_render_speed |
number | The average factor faster than real time which the descriptor typically takes to render |
data[].attributes.bands |
array | |
data[].attributes.bands[].id |
string | The string id of the band |
data[].attributes.bands[].name |
string | The string name of the band |
data[].attributes.instruments |
array | |
data[].attributes.instruments[].id |
string | The string id of the instrument |
data[].attributes.instruments[].name |
string | The string name of the instrument |
data[].attributes.max_tempo |
number | The maximum beats per minute the descriptor is intended to be used with |
data[].attributes.min_tempo |
number | The minimum beats per minute the descriptor is intended to be used with |
data[].attributes.name |
string | The string name of the descriptor |
data[].attributes.previews |
array | |
data[].attributes.previews[].content_type |
string enum | The content type of the previews, currently audio/mp3 . |
data[].attributes.previews[].url |
string | The URL of the descriptor’s preview files |
data[].attributes.tags |
array | |
data[].attributes.tags[].category |
object | |
data[].attributes.tags[].category.id |
string | The string id of the category |
data[].attributes.tags[].category.name |
string | The string name of the category |
data[].attributes.tags[].id |
string | The string id of the tag |
data[].attributes.tags[].labels[].id |
string | The string id of the label of the tag |
data[].attributes.tags[].labels[].name |
string | The string name of the label of the tag |
data[].attributes.tags[].labels |
array | |
data[].attributes.tags[].name |
string | The string name of the tag |
data[].id |
string | The string ID of the descriptor |
data[].links |
object | |
data[].links.self |
string | The URL of the descriptor |
data[].type |
string | The type of data (entity_descriptor in this case) |
links |
object | |
links.first |
string | The URL of the first (or possibly only) page of results. It is always available |
links.next |
string | The URL of the next page of results when using offset/limit mode. It is omitted if there are no additional pages and is available on the first page, and on any subsequent page, accessed with offset/limit mode |
links.next_cursor |
string | The URL of the next page of results when using cursor/limit mode. It is omitted if there are no additional pages and is available on the first page, and on any subsequent page, accessed with cursor/limit mode |
links.prev |
string | The URL of the previous page of results when using offset/limit mode. It is omitted if there is no previous page and is not available in cursor/limit mode |
links.self |
string | The URL of this list of descriptors |
Example Response
Header
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Body
{
"data": [
{
"attributes": {
"average_render_speed": 2.746950884518184,
"bands": [
{
"id": "corporate_pop_inspirational_high_energy_band_1",
"name": "Corporate Pop Inspirational High Energy Band 1"
},
...
],
"instruments": [
{
"id": "xy_modern_martin_steel",
"name": "Martin (Modern) - Sweet"
},
...
],
"max_tempo": 130,
"min_tempo": 110,
"name": "Corporate Pop Inspirational High Energy",
"previews": [
{
"content_type": "audio/mp3",
"url": "https://public-cdn.ampermusic.com/bands/previews/corporate_pop_inspirational_high_energy_band_1_v1.mp3"
}
],
"tags": [
{
"category": {
"id": "style",
"name": "Style"
},
"id": "corporate_pop",
"name": "Corporate Pop"
},
...
]
},
"id": "corporate_pop_inspirational_high_energy",
"links": {
"self": "https://api.ampermusic.com/v1/entities/descriptor/corporate_pop_inspirational_high_energy"
},
"type": "entity_descriptor"
}
],
"links": {
"first": "https://api.ampermusic.com/v1/entities/descriptor?limit=1",
"next": "https://api.ampermusic.com/v1/entities/descriptor?limit=1&offset=1",
"next_cursor": "https://api.ampermusic.com/v1/entities/descriptor?cursor=cinematic_percussion_epic_brewing",
"prev": "https://api.ampermusic.com/v1/entities/descriptor?limit=1",
"self": "https://api.ampermusic.com/v1/entities/descriptor?limit=1"
}
}