Upload API

The endpoint ¶

All uploads target a single route. The Content-Type header decides the intake mode: multipart/form-data for raw bytes, application/json for URL-fetch.

{id} is the numeric ID of an upload-type dataset you own (or are a member of via its parent workspace). Datasets created for podcast feeds will reject uploads — create a dataset with content_type: "uploads" first. The authenticated caller must be a workspace member; otherwise the API returns 404 (we deliberately don't disclose whether the dataset exists).

Multipart upload ¶

Use multipart when the audio lives on the machine making the request — browser file picker, a CLI script streaming a local file, a desktop client. The file bytes travel in the audio form field.

curl -X POST "https://www.audioscrape.com/api/datasets/123/items" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -F "audio=@/path/to/interview.mp3" \
     -F "title=Q3 customer interview — ACME Corp" \
     -F "description=30-min discovery call with the ACME product team"

{
  "success": true,
  "item_id": 84217,
  "message": "Audio file queued for transcription with priority 100"
}

Form fields

Datasets configured with require_metadata = true will reject uploads that omit either title or description.

JSON URL upload ¶

Use the JSON variant when the audio is already hosted somewhere on the public internet — an S3 presigned URL, a CDN object, your own static server. Audioscrape downloads it, stores a copy on its own object storage, and queues the same transcription pipeline. This mirrors what the transcribe_audio MCP tool does under the hood, so the two surfaces stay at parity.

curl -X POST "https://www.audioscrape.com/api/datasets/123/items" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "audio_url": "https://files.example.com/recording.mp3",
       "title": "Founder fireside — March 2026",
       "description": "Recording from our internal all-hands"
     }'

{
  "success": true,
  "item_id": 84218,
  "message": "Audio fetched from URL and queued for transcription"
}

JSON body

SSRF guards on audio_url

Because the server fetches whatever URL you provide, we apply strict filters to prevent the endpoint from being used as a reflector into internal infrastructure:

• Scheme must be https — plain http and other schemes are rejected.
• The hostname is resolved server-side; if any resolved IP is loopback, link-local, RFC 1918 private, broadcast, documentation, unspecified, or IPv6 unique-local / link-local, the request is rejected.
• Fetch has a 120-second timeout and is capped at the dataset's effective file-size limit. Content-Length over the cap is rejected before the body is read.
• HTTP status must be 2xx; non-success responses surface as an error to the caller.
• The file extension (derived from the URL path) must match the dataset's allowed-formats list, same as multipart.

File size and format limits ¶

The effective size cap is the smaller of the dataset's max_file_size_mb setting and the account-plan cap. Free-tier accounts are hard-capped at 200 MB per upload regardless of dataset config; paid plans default to the dataset setting (500 MB out of the box, configurable higher). Files exceeding the cap return HTTP 413.

Default accepted extensions: mp3, wav, m4a, ogg, flac. Datasets can override this list in their settings.

Transcription minutes consumed by uploads count against your plan's monthly quota. See /pricing for current plan limits.