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