Process private audio from your own systems.

Request a private upload URL

The API creates the project record and returns a short-lived R2 upload URL. Audio bytes do not pass through the CleanWave API service.

curl -X POST https://api.cleanwaveaudio.com/v1/uploads \
  -H "Authorization: Bearer $CLEANWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "original_filename": "interview.wav",
    "content_type": "audio/wav",
    "claimed_size_bytes": 8451021
  }'

Upload and finalize

Use the returned URL without your CleanWave key. Send every header from the response’s headers object exactly as returned. A successful finalize validates size, container, stream, duration, channels and sample rate.

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: $UPLOAD_CONTENT_TYPE" \
  --upload-file interview.wav

curl -X POST https://api.cleanwaveaudio.com/v1/uploads/$PROJECT_ID/finalize \
  -H "Authorization: Bearer $CLEANWAVE_API_KEY"

Start asynchronous analysis

A successful request returns 202 Accepted. Credits are reserved from the same balance used by the web application. Poll the project until it reachesready_for_review or failed.

curl -X POST https://api.cleanwaveaudio.com/v1/projects/$PROJECT_ID/analyze \
  -H "Authorization: Bearer $CLEANWAVE_API_KEY"

curl https://api.cleanwaveaudio.com/v1/projects/$PROJECT_ID \
  -H "Authorization: Bearer $CLEANWAVE_API_KEY"

Review suggestions and export

Analysis returns a transcript, PII detections and suggested redactions. Update the redactions if necessary, then start the asynchronous WAV export. Poll until the project reaches completed and download_ready is true.

curl -X PUT https://api.cleanwaveaudio.com/v1/projects/$PROJECT_ID/redactions \
  -H "Authorization: Bearer $CLEANWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"redactions":[{
    "entity_type":"phone_number",
    "text":"060123456",
    "start_time":12.4,
    "end_time":14.1,
    "mode":"silence",
    "review_status":"accepted",
    "detection_ids":[]
  }]}'

curl -X POST https://api.cleanwaveaudio.com/v1/projects/$PROJECT_ID/export \
  -H "Authorization: Bearer $CLEANWAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"silence"}'

Download, verify and delete

Save and verify the result before deletion. API downloads do not delete a project automatically. After verification, delete the project to remove its original, output, temporary R2 objects and retained metadata immediately.

curl -L https://api.cleanwaveaudio.com/v1/projects/$PROJECT_ID/download \
  -H "Authorization: Bearer $CLEANWAVE_API_KEY" \
  --output interview-anonymized.wav

curl -X DELETE https://api.cleanwaveaudio.com/v1/projects/$PROJECT_ID \
  -H "Authorization: Bearer $CLEANWAVE_API_KEY"

Stream a manifest of up to 50,000 files

Open an empty batch, append descriptors in fragments of 500–1,000, close the manifest, request bounded upload windows, upload directly to R2, then callprocess once. Every manifest request needs a stable idempotency key.

curl -X POST https://api.cleanwaveaudio.com/v1/batches \
  -H "Authorization: Bearer $CLEANWAVE_API_KEY" \
  -H "Idempotency-Key: import-2026-09-manifest" \
  -H "Content-Type: application/json" \
  -d '{"name":"September import","expected_file_count":50000}'

curl -X POST https://api.cleanwaveaudio.com/v1/batches/$BATCH_ID/items \
  -H "Authorization: Bearer $CLEANWAVE_API_KEY" \
  -H "Idempotency-Key: import-2026-09-chunk-0001" \
  -H "Content-Type: application/json" \
  -d '{"files":[{
    "client_reference":"call-000001",
    "original_filename":"call-000001.wav",
    "content_type":"audio/wav",
    "claimed_size_bytes":8451021
  }]}'

curl -X POST https://api.cleanwaveaudio.com/v1/batches/$BATCH_ID/finalize \
  -H "Authorization: Bearer $CLEANWAVE_API_KEY"

curl "https://api.cleanwaveaudio.com/v1/batches/$BATCH_ID/uploads?limit=100&offset=0" \
  -H "Authorization: Bearer $CLEANWAVE_API_KEY"

# Upload every item with its returned method, URL and headers.
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: $UPLOAD_CONTENT_TYPE" \
  --upload-file call-000001.wav

curl -X POST https://api.cleanwaveaudio.com/v1/batches/$BATCH_ID/process \
  -H "Authorization: Bearer $CLEANWAVE_API_KEY"

Batch workers validate uploaded objects before analysis, so individual/uploads/{project_id}/finalize calls are optional for normal batch processing. Use /retry only after a terminal failed state and/cancel to stop work that has not begun.