Navigation :

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

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"
    }
}