List of Instruments
GET /v1/entities/instrument
Retrieves a list of instruments.
Request Parameters
Location | Parameter | Type | Required/ Optional | Description |
---|---|---|---|---|
query | cursor |
string | optional | The cursor id of the first record to return. Example: dreamy_electric_guitar |
query | id |
string | optional | Filter. Will match to records whose id 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 | 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 |
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/instrument?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.name |
string | The string name of the instrument |
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 string url of the instrument’s preview file |
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[].name |
string | The string name of the tag |
data[].id |
string | The string id of the instrument |
data[].links |
object | |
data[].links.self |
string | The URL of the instrument |
data[].type |
string | The type of data (entity_instrument 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 instruments |
Example Response
Header
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Body
{
"data": [
{
"attributes": {
"name": "Roomy Kit",
"previews": [
{
"content_type": "audio/mp3",
"url": "https://public-cdn.ampermusic.com/instruments/previews/roomy_kit_v1.mp3"
}
],
"tags": [
{
"category": {
"id": "instrument_category",
"name": "Instrument Category"
},
"id": "percussion",
"name": "Percussion"
},
{
"category": {
"id": "instrument_type",
"name": "Instrument Type"
},
"id": "aux_perc",
"name": "Aux Percs"
}
]
},
"id": "roomy_kit",
"links": {
"self": "https://api.ampermusic.com/v1/entities/instrument/roomy_kit"
},
"type": "entity_instrument"
}
],
"links": {
"first": "https://api.ampermusic.com/v1/entities/instrument?limit=1",
"next": "https://api.ampermusic.com/v1/entities/instrument?limit=1&offset=1",
"next_cursor": "https://api.ampermusic.com/v1/entities/instrument?cursor=bright_roomy_kit&limit=1",
"prev": "https://api.ampermusic.com/v1/entities/instrument?limit=1",
"self": "https://api.ampermusic.com/v1/entities/instrument?limit=1"
}
}