Items

Upload audio into a dataset

Two intake modes: • Content-Type: multipart/form-data — form fields audio (file), optional title, description • Content-Type: application/json — { "audio_url": "https://...", "title": "...", "description": "..." }

JSON mode is the natural fit when the audio is already hosted (S3 presigned URL, CDN, your own server). Multipart is the natural fit for client-side files (browser uploads, scripts streaming local files). Both modes converge on the same storage + transcription pipeline; the resulting item is identical. Transcription minutes consumed count against your plan's monthly quota (see /api/me/usage). After upload, fetch full metadata at GET /api/items/{item_id} once transcription completes.

Constraints

• File size: Free tier is hard-capped at 400 MB per audio upload regardless of dataset config (1 GB for video and for containers intake re-wraps — amr, 3gp, wma, aiff, caf, mpeg — since only the extracted audio is kept). Paid plans honour the dataset's max_file_size_mb (default 500 MB). Exceeding the cap returns 413 Payload Too Large; JSON-mode audio_url is fetched under the same cap. (The MCP connector's transcribe_audio link path and the web paste-a-link import fetch in the pipeline without a byte cap.) • URL-fetch safety (JSON mode): audio_url must use https://. URLs that resolve to private, link-local, loopback, or otherwise internal IP ranges are rejected (SSRF guard) with 422 Unprocessable Entity. • Dataset configuration: The target dataset must have content_type = 'uploads'. Datasets backed by RSS feeds or other source types return 409 Conflict.

post/api/datasets/{id}/items

Request

  • Base URL: https://www.audioscrape.com
  • URL: https://www.audioscrape.com/api/datasets/{id}/items
  • Auth: HTTP bearer

Path parameters

idinteger required

Numeric dataset ID. Caller must be a member of the dataset's parent library.

Request body

audio_urlstring required

Publicly reachable https:// URL of the audio file. Must NOT resolve to a private / internal IP range (SSRF guard).

content_typestring nullable

What the audio IS (e.g. phone_call). Drives the Details panel, speaker-label suggestions, and processing hints. See GH#35.

derive_titleboolean nullable

GH#617: opt in to derived titles (cleaned filename placeholder + transcript-derived title from the pipeline). Default OFF on the API: the title you send — or the file's own name — is treated as your deliberate choice and never rewritten.

descriptionstring nullable
metadataunknown
titlestring nullable

Example request

{
  "audio_url": "https://files.example.com/recording.mp3"
}

Response

Upload accepted; item created and queued for transcription

duplicate_ofinteger nullable

Set when the bytes matched a recording already in the workspace: nothing was stored or transcribed, no minutes were used, and item_id is the existing recording.

item_idinteger required

ID of the newly-created item. Fetch full metadata at GET /api/items/{id}. When duplicate_of is set, this is that existing item.

messagestring required

Human-readable status message (e.g. "queued for transcription").

successboolean required

Changes

No recorded changes to this operation across all 1 revision of this API.