The Amper Music API is implemented as a set of RESTful HTTP/1.1 requests and responses. All requests must use HTTPS protocol on port 443.
In general, the API design follows the principles of the JSON API 1.0 specification.
The base URL for all requests is
api.ampermusic.com. All requests must
include the header
Cross-Origin Resource Sharing
The Amper API supports Cross-Origin Resource Sharing (CORS) using a whitelist approach. Third-party websites and applications having a business relationship with Amper Music are added to the whitelist as required.
To activate CORS behavior, the client must include an
Origin request header
set to an approved value. For preflight (i.e.
OPTIONS) requests, the client
must access a valid URL with a supported HTTP method for that
URL in the
Access-Control-Request-Method request header. Most web browsers
perform these operations automatically, although client code may need to
perform additional steps to leverage CORS fully for their use case.
HTTP requests can use either Basic (preferred) or Bearer authentication. When a user issues a login request, the response includes a session token. This token must be used in the
Authorization header for most of the other API requests.
Basic authentication uses the
Authorization request header with the format
Authorization: <username>:<password>, where
<username>:<password> is Base64
encoded. Send a valid token as the HTTP username with a blank password. For
example, for the token
xyzzy, use the value
eHl6enk6, which is the
base64-encoded value for
xyzzy: (note the trailing colon).
Authorization: Basic eHl6enk6
Bearer authentication uses the
Authorization request header with the format
Authorization: Bearer <credentials>, where
<credentials> is a valid
token. Send the token as the
<credentials>. For example, if the token is
aabbcd, use the value
Authorization: Bearer aabbcd
All responses contain an ETag header representing the state of the resource on
the server. PATCH, PUT, or DELETE requests to modify a resource must contain an
If-Match header that matches the ETag of the resource on the server. If the
ETags do not match, no modifications are made and a
412 Precondition Failed
response is returned.
Example Request Header:
Example Response Header:
For GET requests that return a list of data records, you can specify the first
record to return and the number of records to return using the
limit query parameters. Responses return all records in “date
created” order in ascending order.
To specify the numeric offset of the the first data record returned, use the
offset query parameter. Valid values are 1 to 1000. Use the
parameter to specify the number of data records to return. Valid values are 1
to 100. The
limit parameter is optional and defaults to 10 if it is not
specified. The maximum result accessible using Offset/Limit method is 1,100
limit=100). To retrieve additional records, use the
To specify the cursor ID of the first data record returned, use the
query parameter. Use the
limit query parameter to specify the number of
records to return. Valid values are 1 to 100. The
limit parameter is optional
and defaults to 10 if it is not specified. All data records are accessible by
iterating over the entire chain of cursor IDs.
Note: This design deviates from the JSON API specification, which prescribes namespaced query parameters. For example,
The content type for all requests and responses is
Other content types are not supported.
Response Status Codes
The Amper platform returns the following response status codes:
|200 OK||The request was successful. The object was found and returned|
|201 Created||The object was successfully created. The message body contains its current state. If present, the
|202 Accepted||The request was successfully accepted. Further processing will be performed|
|204 No Content||The request was successful. The response contains no content|
|400 Bad Request||The system was unable to process the request because it was malformed|
|401 Unauthorized||The request was unsuccessful because of an authentication failure|
|404 Not Found||A path or ID specified in the URL does not exist. This code is also returned in cases where an object does exist in the system, but it does not belong to authenticated user|
|405 Method Not Allowed||The requested method cannot be performed on the specified object|
|409 Conflict||The object could not be created because it conflicts with an existing object. Ensure the user-defined project name is unique for the user|
|412 Precondition Failed||An object could not be updated or deleted because the
|415 Unsupported Media Type||The
|422 Unprocessable Entity||A POST request was parsable, but failed a validation check. A required property was either missing or a value was invalid|
|429 Too Many Requests||The request was rejected because too many similar requests have been submitted in a short amount of time. Wait and try submitting requests later|