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. Please contact your sales representative if your require CORS for a client-side implementation.
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 any (or a blank)
password. For example, for the token
xyzzy, use the value
eHl6enk6, which is
the base64-encoded value for
Note: The password field is not used, but the colon that precedes it must be present. If a value is supplied in the password field, it will be ignored.
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 100,000. 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 100,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,
Certain endpoints which return lists of objects can be sorted based on an
attribute within the objects. This is accomplised by adding a
parameter to the query string, with a value corresponding to the name of
the field or fields to sort on. Multiple fields may be specified by
concatenating the names together with a comma (
By default, sorting is performed in ascending order. To reverse a sort,
prepend a dash (
-) character before an attribute name.
If multiple fields are provided, the ones listed first will be applied first, and subsequent fields will be used to resolve objects that compared equal based on earlier fields.
The general format of a copy request is:
This means the following:
POST /resource-nameas usual. For all writable attributes defined by the model, use the value that already exists in the attributes of the resource identified by
- Once the attributes have been pre-filled, examine the request body sent by the client and update any values that the client overrode.
- Perform field validation, and proceed as usual.
All fields on the
POST become optional, and where unspecified, they use the value from the source object. It is possible to
POST with an empty request body, in which case a complete duplicate will be made. It is also possible to
POST with a request body that specifies every available attribute, in which case the end effect is just a straight
POST with nothing from the source object remaining.
The general format of a move request is:
The request body must be empty.
This works much the same as copy, with the key differences being:
- No attribute can be overridden in the request body, and
idspecified will be detached from its current parent object and reattached to the specified one
Move operations generally short-circuit the field validations. Since there is no opportunity to modify the field values during the move, there is no need to validate their contents.
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|
Several endpoints support freeform
meta attributes for storage of client data. There are a few constraints that
meta data must abide by:
metaobject cannot have more than 10 top-level keys within it.
- Each top-level key within the
metaobject must have a name that begins with a lowercase letter, and consists solely of lowercase letters, numbers, and underscores. Key names must be less than 50 characters long.
- Each top-level value within the
metaobject, when serialized to a JSON string, must use less than 5,000 bytes.
Methods that update resources (e.g.
PATCH) will replace the
meta object if supplied. This means that clients must resend the entire
meta object, even parts that may be unchanged, if they wish to update only part of it.