Getting started

Idempotency

If a request to create a job times out, you can't tell whether the job exists, and retrying could create and bill a second job. Send an Idempotency-Key with POST /v1/jobs, and a retry with the same key and body within 24 hours returns the original job instead.

Sending a key

The key is a string of 1 to 128 characters that you send in the Idempotency-Key header, with one key for each job you create. A UUID works, or an ID from your own system such as episode-12-enhance, as long as every retry sends the same key.

curl -sS https://platform-api.nomono.co/v1/jobs \  -H "Authorization: Bearer $NOMONO_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: episode-12-enhance" \  -d '{    "session_id": "ses_01a14471a03b7c56a1e28d9f4b6c7d8e",    "products": {"enhancement": {"preset": "listening.full"}},    "outputs": [{"type": "tracks", "format": "wav"}]  }'

The header is optional. A request that gets an error doesn't use up its key, and after you fix the request you can send it again with the same key.

Sending the request again

Request	Response
A key not used in the last 24 hours	`201` with a new job.
The same key and the same body, within 24 hours	`201` with the original job, in its current state.
The same key and a different body, within 24 hours	`409` `idempotency_conflict`.
Concurrent requests with one key	One job is created. If the bodies differ, the second request gets the `409`.

409 Conflict

{  "error": {    "code": "idempotency_conflict",    "message": "Idempotency-Key was already used with a different body",    "hint": "Send a new key for a different job"  }}

Bodies are compared by their content, so field order, whitespace and defaults you write out make no difference. A key expires 24 hours after its job was created.

Failed jobs

A key returns its job even when that job has failed, so to try a failed job again, create it with a new key, as Jobs describes.

Other requests

The other routes don't take a key. When you repeat one after it succeeded, you get:

Request	Sent again
`POST /v1/uploads`	Creates another upload. An upload you never complete expires after 24 hours.
`POST /v1/uploads/{upload_id}/parts`	Returns new URLs for the same parts. The earlier URLs keep working until the upload expires.
`POST /v1/uploads/{upload_id}/complete`	Returns the same source.
`POST /v1/sessions`	Returns `422` `session_invalid` with "Source is already in another session". List your sessions to find the one the first request made.
`DELETE /v1/uploads/{upload_id}`, `/v1/sources/{source_id}` and `/v1/sessions/{session_id}`	Returns `404` `not_found`.
`DELETE /v1/jobs/{job_id}`	Returns `409` `job_not_cancellable` with "The job is cancelled; only a queued job can be cancelled".

GET requests are always safe to repeat.