Media

The media library holds your audio files, MP3 or WAV. Add a file here once, then send it by its media_id as many times as you like. Add a file from a public URL in one call, or upload the bytes yourself with a signed upload.

Where you use media

Where Field
Ringless voicemail (POST /rvm) media_id
Voice broadcasts (POST /voice-broadcast) media_on_speech, media_on_beep, media_on_transfer, media_on_confirm, media_on_opt_out
Audio MMS (POST /sms, POST /phone/public/sms/reply) media_ids. See MMS.
Transcription and voice cloning media_id
Compliance check media_id or audio_url

The library stores audio only. To send an image, pass media_urls on the text instead.

For an audio MMS, the stored file must be 1 MiB or smaller. A voicemail recording is often larger, so export a shorter or lower-bitrate MP3 for MMS.

Transcription and voice cloning detect whether a media_id was stored as MP3 or WAV, so you don't need to pass ext with it. See Audio formats.

Routes

Method Route Scope What it does
GET /media/public/media media:read List your playable media
POST /media/public/media media:write Add media from a URL, or start a signed upload
POST /media/public/media/{media_id}/complete media:write Finish a signed upload
GET /media/public/media/{media_id}/policy media:write Get fresh upload URLs
GET /media/public/media/{media_id} media:read Get one media entry
POST /campaign/public/compliance media:write Check audio for compliance problems. A paid call.
PUT /media/public/media/{media_id} media:write Rename or relabel media
DELETE /media/public/media/{media_id} media:write Delete media

List media

Returns the media you can send, newest first. An entry waiting for its signed upload to finish isn't listed.

Field Type Required Description
skip integer No Entries to skip. Default 0.
limit integer No Page size. Default 100.
curl "https://api-v2.dropcowboy.com/media/public/media?limit=10" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
  "data": {
    "medias": [
      {
        "team_id": "cd5cd773-4617-4b28-854d-d3adc74c96d5",
        "media_id": "0786a81e-e11e-4e53-ab64-71f552db23b3",
        "name": "September promo",
        "created_at": 1757491200000,
        "approved_at": 1757491200000,
        "api_allowed": true
      }
    ],
    "total": 1
  },
  "meta": { "request_id": "88f84098-c512-4585-9fd7-0d8bc8400944" }
}

data.total counts every playable entry, not just this page. Page with skip until you've read total entries. Timestamps are epoch milliseconds.

Create media

Send JSON with either url or signed_upload: true. The response is 201.

To upload a file from your computer without writing the signed upload yourself, use the upload script in the Drop Cowboy® examples on GitHub: npm run upload-media in Node.js, python upload_media.py in Python, or dotnet run -- upload-media in C#. Each one uploads DC_AUDIO_FILE and prints its media_id.

Field Type Required Description
name string Yes Display name.
type string No Your own label, for example rvm.
url string One of url or signed_upload Public URL of an MP3 or WAV file.
ext string No With url: the file's format, .wav (default) or .mp3.
signed_upload boolean One of url or signed_upload true to get signed URLs and upload the bytes yourself.

From a URL

We download the file while you wait. It must be 50 MiB or smaller and download within 15 seconds. When the call returns, the media is ready to send.

curl -X POST https://api-v2.dropcowboy.com/media/public/media \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October follow-up",
    "type": "rvm",
    "url": "https://files.example.com/october-follow-up.mp3",
    "ext": ".mp3"
  }'
{
  "data": {
    "media_id": "55b9e55e-23f1-4c16-8865-f4b6261ebeea",
    "name": "October follow-up",
    "type": "rvm",
    "media_exists": true,
    "approved_at": 1759312800000,
    "api_allowed": true
  },
  "meta": { "request_id": "3028a01c-9f13-4158-a864-2daa70189301" }
}

If the download fails, no media is saved. Fix the URL and call again.

Signed upload

Use this when the file is on your own server rather than at a public URL.

  1. Create the entry with signed_upload: true. The response has upload.mp3 and upload.wav, each with a signed url and the content_type to send.
  2. PUT the file to the URL for its format, with exactly that Content-Type. The URLs are valid for 2 days.
  3. Call Complete a signed upload. Until you do, the entry has media_exists: false and can't be sent.
curl -X POST https://api-v2.dropcowboy.com/media/public/media \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "name": "October follow-up", "type": "rvm", "signed_upload": true }'
{
  "data": {
    "media_id": "55b9e55e-23f1-4c16-8865-f4b6261ebeea",
    "name": "October follow-up",
    "type": "rvm",
    "signed_upload": true,
    "media_exists": false,
    "api_allowed": false,
    "upload": {
      "mp3": { "url": "https://uploads.example.com/55b9e55e-23f1-4c16-8865-f4b6261ebeea.mp3?X-Amz-Signature=...", "content_type": "audio/mpeg" },
      "wav": { "url": "https://uploads.example.com/55b9e55e-23f1-4c16-8865-f4b6261ebeea.wav?X-Amz-Signature=...", "content_type": "audio/wav" }
    }
  },
  "meta": { "request_id": "50bb4bbb-3f86-459a-9761-f8bd7ff12f1b" }
}
curl -X PUT "$UPLOAD_MP3_URL" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @october-follow-up.mp3

A 403 from the PUT means the Content-Type you sent differs from the returned content_type, or the URL expired. Send the type exactly as returned, or refresh the URLs.

Complete a signed upload

Call this after your PUT succeeds. The media is then ready to send.

curl -X POST https://api-v2.dropcowboy.com/media/public/media/55b9e55e-23f1-4c16-8865-f4b6261ebeea/complete \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
  "data": {
    "media_id": "55b9e55e-23f1-4c16-8865-f4b6261ebeea",
    "media_exists": true,
    "approved_at": 1759313100000,
    "api_allowed": true
  },
  "meta": { "request_id": "764ff1bd-86e1-49af-8703-2ad22b53f04a" }
}

Refresh upload URLs

Returns new signed upload URLs for an entry, in the same mp3 and wav shape as upload. Call it when a PUT is rejected because the URL expired.

curl https://api-v2.dropcowboy.com/media/public/media/55b9e55e-23f1-4c16-8865-f4b6261ebeea/policy \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
  "data": {
    "mp3": { "url": "https://uploads.example.com/55b9e55e-23f1-4c16-8865-f4b6261ebeea.mp3?X-Amz-Signature=...", "content_type": "audio/mpeg" },
    "wav": { "url": "https://uploads.example.com/55b9e55e-23f1-4c16-8865-f4b6261ebeea.wav?X-Amz-Signature=...", "content_type": "audio/wav" }
  },
  "meta": { "request_id": "e2db9755-0c26-4aae-823a-dfb1b7c05acf" }
}

Get media

curl https://api-v2.dropcowboy.com/media/public/media/55b9e55e-23f1-4c16-8865-f4b6261ebeea \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
  "data": {
    "_id": "66f2b1c4e8a9d3f1a2b4c6d8",
    "team_id": "cd5cd773-4617-4b28-854d-d3adc74c96d5",
    "media_id": "55b9e55e-23f1-4c16-8865-f4b6261ebeea",
    "media_exists": true,
    "name": "October follow-up",
    "type": "rvm",
    "src_url": "https://files.example.com/october-follow-up.mp3",
    "created_at": 1759312800000,
    "created_by": "fa933d82-485f-43b0-80ab-860121f06980",
    "modified_at": null,
    "modified_by": null,
    "deleted_at": null,
    "deleted_by": null,
    "approved_at": 1759312800000
  },
  "meta": { "request_id": "787d0f0b-aa13-4ce9-890c-202d68b72467" }
}

A deleted entry returns 404, so a media_id you stored earlier is safe to send only if this call still finds it.

Update media

Changes the name or type. The audio can't be replaced: create new media instead.

Field Type Required Description
name string No New display name.
type string No New label.
curl -X PUT https://api-v2.dropcowboy.com/media/public/media/55b9e55e-23f1-4c16-8865-f4b6261ebeea \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "name": "October follow-up v2" }'
{
  "data": {
    "team_id": "cd5cd773-4617-4b28-854d-d3adc74c96d5",
    "media_id": "55b9e55e-23f1-4c16-8865-f4b6261ebeea",
    "modified_at": 1759399200000,
    "modified_by": "fa933d82-485f-43b0-80ab-860121f06980",
    "name": "October follow-up v2"
  },
  "meta": { "request_id": "c6e0e173-ab7e-45d6-b470-72d593b15f56" }
}

The response echoes the change even when the media_id doesn't exist. To confirm an entry exists, get it first.

Delete media

Removes the entry from your library. Messages already sent aren't affected.

curl -X DELETE https://api-v2.dropcowboy.com/media/public/media/55b9e55e-23f1-4c16-8865-f4b6261ebeea \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
  "data": { "deleted": true },
  "meta": { "request_id": "964c9795-8bdd-475a-917a-2ec2727c2cfb" }
}

Check audio for compliance

Transcribes a recording and checks it against the rules that most often get voicemail, call and text campaigns flagged: telemarketing and consent rules, the carrier and CTIA messaging rules, and our terms of service. Run it before you send, so a problem reaches you in a response and not as a rejected campaign.

Send exactly one field:

Field Type Description
audio_url string A public https link to an MP3 or WAV. We fetch it once and don't store it.
media_id string A recording on your account. The result is kept on the recording.

Recordings can be up to 3 minutes long.

curl -X POST https://api-v2.dropcowboy.com/campaign/public/compliance \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "audio_url": "https://files.example.com/spring-promo.mp3" }'
{
  "data": {
    "mode": "audio_url",
    "media_id": null,
    "status": "complete",
    "analyzed_at": 1760227200000,
    "detected_language": "en",
    "has_flags": true,
    "checks": [
      {
        "severity": "warning",
        "message": "The message makes a promotional offer without saying who is calling."
      }
    ],
    "tos_flags": [],
    "charge": { "amount": 0.05, "currency": "USD" }
  },
  "meta": { "request_id": "08aba0ac-3266-48d7-8367-644694cc3465" }
}

Each entry in checks has a severity of info, warning or danger. tos_flags list terms-of-service topics found in the audio. Treat both as advice to fix the message before you send. They aren't legal advice, and an empty result doesn't mean the message complies. Some findings are held back and show as a single notice in checks that the recording may need review.

When you send media_id, GET /media/public/media/{media_id} returns the latest result as compliance until you analyze the file again.

Price. Each analysis that completes costs $0.05, taken from your prepaid balance, unless your account has its own rate. The response shows the amount as charge. Checking the same recording again is charged again. A request that is refused or fails, or a recording that is too long, has no speech or can't be fetched, costs nothing. Accounts still on a trial get 402: add funds first.

Limits. Each account can send 60 requests a minute and run 3 analyses at once. Past either, you get 429 with a Retry-After header. Wait that many seconds, then retry.

Retries. Send an Idempotency-Key header (1 to 255 printable ASCII characters) to retry safely. A retry with the same key and body within 24 hours returns the stored response with Idempotent-Replayed: true, and isn't charged again. A failed request releases the key, so retrying runs it again.

Status When What to do
400 Not exactly one of audio_url and media_id, an audio_url that isn't a public https address, or an invalid Idempotency-Key. Fix the request.
402 A trial account, a past-due subscription, or a balance too low for the analysis. Add funds or update your payment method, then retry.
404 The media_id isn't on your account, or was deleted. Check the id with List media.
409 The Idempotency-Key was used with a different body, or its first request hasn't finished. Use a new key for a new request. For an unfinished one, retry shortly with the same key.
413 The file is too large to analyze. Export a smaller file.
415 The audio_url file isn't an MP3 or WAV. Export an MP3 or WAV.
422 The audio_url couldn't be fetched, the recording is longer than 3 minutes, or it has no speech. Check the link, or send a shorter recording.
429 Too many requests, or too many analyses at once. Wait Retry-After seconds, then retry.
502, 504 The analysis failed or took too long. Retry with exponential backoff.

Errors

Status When What to do
400 The url isn't a public http or https address. Host the file somewhere reachable from the internet.
413 The file at url is larger than 50 MiB. Export a smaller file.
502 The server at url returned an error or closed the connection. Open the URL yourself to check it, then call again.
504 The file didn't download within 15 seconds. Use faster hosting, or a signed upload.
400 On complete: Upload not found. PUT audio to the signed URL first. Upload the file to a signed URL, then complete. If the URL expired, refresh it.
404 The media_id isn't on your account, or was deleted. Check the id with List media.
403 From the signed upload URL: the Content-Type differs from the returned content_type, or the URL expired. Send the returned type exactly, or refresh the URLs.

Sends that use media report their own outcomes. 3033 (Media Not Found) means the media_id was deleted, belongs to another account, or its upload was never completed. 3035 (Media Too Large) means the file is over the MMS size limit. See Outcomes for both. For every other error, see Responses, errors and limits.

Code samples

The requests from this page, ready to copy. Set DC_KEY and DC_SECRET to your API key pair first.

List media
curl "https://api-v2.dropcowboy.com/media/public/media?limit=10" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
From a URL
curl -X POST https://api-v2.dropcowboy.com/media/public/media \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October follow-up",
    "type": "rvm",
    "url": "https://files.example.com/october-follow-up.mp3",
    "ext": ".mp3"
  }'
Signed upload
curl -X POST https://api-v2.dropcowboy.com/media/public/media \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "name": "October follow-up", "type": "rvm", "signed_upload": true }'
Signed upload (2)
curl -X PUT "$UPLOAD_MP3_URL" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @october-follow-up.mp3
Complete a signed upload
curl -X POST https://api-v2.dropcowboy.com/media/public/media/55b9e55e-23f1-4c16-8865-f4b6261ebeea/complete \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
Refresh upload URLs
curl https://api-v2.dropcowboy.com/media/public/media/55b9e55e-23f1-4c16-8865-f4b6261ebeea/policy \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
Get media
curl https://api-v2.dropcowboy.com/media/public/media/55b9e55e-23f1-4c16-8865-f4b6261ebeea \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
Update media
curl -X PUT https://api-v2.dropcowboy.com/media/public/media/55b9e55e-23f1-4c16-8865-f4b6261ebeea \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "name": "October follow-up v2" }'