Uploads

Upload a media file directly to storage, then turn it into a recording.

Uploading is a two-step, direct-to-storage flow:

1. POST /v1/uploads to reserve an object and get a signed upload_url.

2. PUT the raw file bytes to upload_url.

3. Call POST /v1/recordings with the returned object_id to create the recording and start transcription.

Tier: core. Base URL https://app.castmagic.io.

Start an upload

POST https://app.castmagic.io/v1/uploads

Request Body

Name	Type	Description
filename*	String	Name of the file, e.g. interview.m4a
content_type*	String	MIME type, e.g. audio/mp4
content_size*	Integer	Size in bytes
space_id	String	Defaults to the key's default space
title	String	Optional title carried to the recording

201: Created

{
    "object_id": "obj_...",
    "upload_url": "https://storage.googleapis.com/...",
    "upload_url_expires_in_seconds": 1800,
    "space_id": "a1..."
}

402: Payment Required Storage limit reached

{ "error": "storage limit exceeded" }

Files are capped at 10 GB. Uploads that would exceed the plan's storage hard limit are rejected with 402. The signed upload_url is valid for 30 minutes (upload_url_expires_in_seconds).

PUT the file bytes

Upload the raw bytes to the returned upload_url with an HTTP PUT. Use the same Content-Type you declared:

curl -X PUT \
    -H "Content-Type: audio/mp4" \
    --data-binary @interview.m4a \
    "$UPLOAD_URL"

This request goes straight to storage — it does not carry your Castmagic Authorization header. Once the bytes are uploaded, call POST /v1/recordings with the object_id. Castmagic verifies the bytes actually arrived before creating the recording; if they never did, that call returns 422.