Create a Simple Composition

POST /v1/simple_compositions

Creates a simple composition.

Request Parameters

Location Data Item Type Required/Optional Description
body data object required
body data.type string required The type of data (simple_compositions in this case)
body data.attributes object required
body data.attributes.timeline object required See Timelines for details

Example Request

POST /v1/simple_compositions HTTP/1.1
Host: api.ampermusic.com
Content-Type: application/vnd.api+json
Authorization: Basic abcxyz

Body

{
    "data": {
        "type": "simple_compositions",
        "attributes": {
            "timeline": {
              <timeline data>
            }
        }
    }
}

Response Data

Data Item Type Description
data object
data.type string The type of data (simple_compositions in this case)
data.id string The alphanumeric ID of the user
data.attributes object
data.attributes.date_create string Date the composition was first requested
data.attributes.date_update string Date the composition last saw any activity. If never updated, then null
data.attributes.queue_position number Estimate of this job’s position in the waiting queue. If the job is not waiting (i.e. it’s running, completed or failed) this will be null
data.attributes.progress_percent number When the composition is running, shows the current progress in the range 0..100 inclusive. If the composition has not started, or has finished, then null
data.attributes.status string A coarse progress indicator. Values are listed below
data.attributes.timeline object Returned in future GETs after the job finishes successfully. If the status is not CREATED, always null – note that the input timeline is never returned, only the full (possibly modified) output of a successful compose is returned. See Timelines for details
data.links object
data.links.self string The URL of the composition
links object
links.self string The URL of this composition

Note: All dates are formatted as ISO-8601 date and time strings. For example, 2018-08-08T08:08:08+00:00.

Note: Simple Compositions are not guaranteed to exist forever. Clients must GET the composition within 24-48 hours of the original request. After this time, we reserve the right to delete the data and potentially recycle the ID.

Composition Statuses

Status Description
WAITING_CREATE Job is waiting to start
RUNNING_CREATE Job is actively being composed
CREATED Job has finished and file(s) have been created
FAILED_CREATE Job did not complete successfully and no further work will be done on it

Example Response

Header

HTTP/1.1 202 Accepted
Content-Type: application/vnd.api+json
Location: /simple_compositions/abcd1234
ETag: W/"bbc6f6ebcfff5c94258db3ddfe0b9b6a5ddca909"

Body

{
    "data": {
        "type": "simple_compositions",
        "id": "abcd1234",
        "attributes": {
            "id": "abcd1234",
            "status": "WAITING_CREATE",
            "progress_percent": null,
            "queue_position": null,
            "timeline": null,
            "date_create": "2018-10-01T00:00:00.000000+00:00",
            "date_update": null
        },
        "links": {
            "self": "https://api.ampermusic.com/v1/simple_compositions/abcd1234"
        }
    },
    "links": {
        "self": "https://api.ampermusic.com/v1/simple_compositions/abcd1234"
    }
}