Uploads
Send audio and artwork as immutable asset versions.
Files never pass through the API. You declare a file, PUT its bytes to a signed URL, then finalize it. An order refers to files by asset_version_id.
POST /uploadswithkind(audioorartwork),size_bytes,sha256(64 hex characters) andcontent_type. Optional:filename,recording_title, andasset_idto add a new version to an existing asset. Needs anIdempotency-Key; a repeat with the same key returns the same upload with a fresh URL.PUTthe exact bytes toupload.urlbeforeupload.expires_inseconds pass. The URL is single-use.POST /uploads/{id}/finalizewith{}. It checks the stored size, moves the file out of reach of the upload URL (it can no longer be replaced) and answers 202 withstate: processingwhile the bytes are checked against the declared SHA-256 in the background.GET /uploads/{id}untilstateisfinalized, usually within a minute (longer for very large files). Wait 2 seconds before the first check, then double the wait after each check, up to 30 seconds between checks; stop atfinalizedorrejected. A finalized upload has theasset_version_idto use in orders.
Upload states
| State | Meaning |
|---|---|
created | Waiting for the bytes and for finalize. An upload left here for a day is rejected as upload_expired. |
processing | Finalize was called; the bytes are being checked. |
finalized | The bytes matched. asset_version_id is set, and the version never changes. |
rejected | rejected_reason says why: size_mismatch, checksum_mismatch, file_missing, verification_failed (the file could not be checked after several tries; uploading it again usually works) or upload_expired. Start a new upload. |
Retrying finalize
Finalize is safe to retry with the same Idempotency-Key, including after a timeout: a retry resumes the work and returns the current state (202 while processing), and once the upload is finalized it returns the same version marked Idempotent-Replayed: true. A file that did not match is a 422 with the reason. Its key is bound to this upload and this exact request before any work starts, so a different request needs a new key, even if the first one failed.
Finalizing before the bytes are stored returns 409 upload_incomplete.
Quality checks
Finalizing only checks that the bytes are the ones you declared. Decoding, runtime and artwork checks run later, at order validation; a problem moves the order to needs_attention. See Validation and artwork.
import { createHash } from "node:crypto";
import { readFile } from "node:fs/promises";
const bytes = await readFile("side-a.wav");
const declared = {
kind: "audio",
size_bytes: bytes.byteLength,
sha256: createHash("sha256").update(bytes).digest("hex"),
content_type: "audio/wav",
filename: "side-a.wav",
};