> For the complete documentation index, see [llms.txt](https://docs.castmagic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.castmagic.io/endpoints/imports.md).

# 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.

{% hint style="info" %}
**Tier:** `core`. Base URL `https://app.castmagic.io`.
{% endhint %}

## Start an import

<mark style="color:green;">`POST`</mark> `https://app.castmagic.io/v1/imports`

#### Request Body

| Name                                  | Type   | Description                         |
| ------------------------------------- | ------ | ----------------------------------- |
| url<mark style="color:red;">\*</mark> | String | Public `http(s)` URL to import      |
| space\_id                             | String | Defaults to the key's default space |
| title                                 | String | Optional title for the recording    |

{% tabs %}
{% tab title="202: Accepted" %}

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

{% endtab %}

{% tab title="402: Payment Required Storage limit reached" %}

```json
{ "error": "storage limit exceeded" }
```

{% endtab %}

{% tab title="400: Bad Request Non-public URL" %}

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

{% endtab %}
{% endtabs %}

## Fetch an import

<mark style="color:blue;">`GET`</mark> `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.

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "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..."
}
```

{% endtab %}

{% tab title="404: Not Found" %}

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

{% endtab %}
{% endtabs %}