Imports

Import a recording from a URL — YouTube, TikTok, Spotify, Drive, and more.

Import media from a URL into a space. Downloading, transcription, and content generation all run asynchronously — poll GET /v1/imports/:id for status, or subscribe a webhook to transcript.completed.

Supported sources include YouTube, TikTok, Spotify, Google Drive, and direct media URLs.

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

Start an import

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

Request Body

Name	Type	Description
url*	String	Public http(s) URL to import
space_id	String	Defaults to the key's default space
title	String	Optional title for the recording

202: Accepted

{
    "import_id": "imp_...",
    "status": "queued",
    "source": "url",
    "url": "https://youtube.com/watch?v=...",
    "title": null,
    "progress": 0,
    "error": null,
    "recording_id": null
}

402: Payment Required Storage limit reached

{ "error": "storage limit exceeded" }

400: Bad Request Non-public URL

{ "error": "url must resolve to a public address" }

Fetch an import

GET https://app.castmagic.io/v1/imports/:id

Poll for status. Statuses are queued, processing, completed, error, and canceled. recording_id is populated once the recording exists.

200: OK

{
    "import_id": "imp_...",
    "status": "completed",
    "source": "url",
    "url": "https://youtube.com/watch?v=...",
    "title": "My imported video",
    "progress": 1.0,
    "error": null,
    "recording_id": "e1..."
}

404: Not Found

{ "error": "Import not found: imp_..." }