Pages · Uploads

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.

  1. POST /uploads with kind (audio or artwork), size_bytes, sha256 (64 hex characters) and content_type. Optional: filename, recording_title, and asset_id to add a new version to an existing asset. Needs an Idempotency-Key; a repeat with the same key returns the same upload with a fresh URL.
  2. PUT the exact bytes to upload.url before upload.expires_in seconds pass. The URL is single-use.
  3. POST /uploads/{id}/finalize with {}. It checks the stored size, moves the file out of reach of the upload URL (it can no longer be replaced) and answers 202 with state: processing while the bytes are checked against the declared SHA-256 in the background.
  4. GET /uploads/{id} until state is finalized, 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 at finalized or rejected. A finalized upload has the asset_version_id to use in orders.

Upload states

StateMeaning
createdWaiting for the bytes and for finalize. An upload left here for a day is rejected as upload_expired.
processingFinalize was called; the bytes are being checked.
finalizedThe bytes matched. asset_version_id is set, and the version never changes.
rejectedrejected_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.

Computing the declaration (Node)
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",
};