> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcdn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your video sources

> Import videos by link, or connect a YouTube channel or a TikTok or Instagram account, and choose what happens to new uploads.

AgentTV reads a video before AI can use it. This page covers video links and social accounts. If your videos live on your own site and player, use [Import a catalog](https://docs.agentcdn.com/guides/import-catalog.md) instead.

| You have | Do this | Console |
| - | - | - |
| One or more video links | Paste the links | **Imports**, **Add videos**, **Paste links** |
| A YouTube channel | Connect it with Google | **Imports**, **Connect YouTube** |
| A TikTok or Instagram account | Paste the profile link | **Imports**, **Add videos**, **Paste links** |
| A file on your computer | Upload it | **Imports**, **Add videos**, **Upload a file** |

Importing copies the video into AgentTV so it can be read. Your original stays where it is.

## Import videos by link

These links work:

| Platform | Link examples |
| - | - |
| YouTube | `youtube.com/watch?v=...`, `youtu.be/...`, `youtube.com/live/...`, `youtube.com/embed/...` |
| YouTube Shorts | `youtube.com/shorts/...` |
| TikTok | `tiktok.com/@name/video/...` |
| Instagram | `instagram.com/p/...`, `instagram.com/reel/...`, `instagram.com/tv/...` |

A YouTube channel link does not import by link. Connect the channel instead (see below).

> [tab] Console
>
> 1. Open **Imports**. Under **Add videos**, choose **Paste links**.
> 2. Paste one link per line in **Links**, up to 50. You can also choose **Upload a list (.txt)**.
> 3. Choose **Import**.
>
> Each link shows a result: **Queued**, **Added** (already processed, so it uses nothing), **Skipped** (already in your library) or **Failed**. Progress shows under **History**.

> [tab] API
>
> `POST /v1/imports` imports one link. It is a change, so it runs in two calls: a preview, then the same request with `confirm_token`. See [Changes run in two calls](https://docs.agentcdn.com/api-keys.md#changes-run-in-two-calls).
>
> ```bash theme={null}
> curl -X POST "https://api.agentcdn.com/v1/imports" \
>   -H "Authorization: Bearer $AGENTCDN_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"url": "https://www.youtube.com/watch?v=VIDEO_ID"}'
> ```
>
> `library_id` is optional. Without it, the video goes to your default library.
>
> The confirmed call returns `outcome`, and `import_id`, `video_id` and `message` when there are any. Follow the import with `GET /v1/imports/{import_id}`:
>
> ```bash theme={null}
> curl "https://api.agentcdn.com/v1/imports/IMPORT_ID" \
>   -H "Authorization: Bearer $AGENTCDN_API_KEY"
> ```
>
> The response has `status`, `video_id`, `video_status`, `pipeline_stages` (each with `stage` and `status`: `queued`, `running`, `completed`, `failed` or `interrupted`) and `retryable`.

> [tab] Account MCP
>
> In an AI app connected to your [account MCP](https://docs.agentcdn.com/guides/connect-mcp.md#account-mcp), ask it to import a link. It uses:
>
> * `start_import`: previews the import, then starts it once you confirm.
> * `get_import`: reads the progress by `import_id`.

## Connect a YouTube channel

You connect a YouTube channel with a Google sign-in in your browser. This proves the channel is yours. It starts only in the console, not from the API or an AI app. `GET /v1/sources` and `list_sources` give you the link to open (`youtube_connect_url`, or `connect_url` on a source that needs a new sign-in).

**1. Start in the console**

Open **Imports** and choose **Connect YouTube**. Then choose **Continue with Google**.

**2. Sign in and pick the channel**

If your Google account has more than one channel, Google shows a list. Pick the channel you want in AgentTV.

**3. Choose videos to import**

You come back to **Imports**. The channel shows under **Connected channels**. Open **Older videos** and choose the public videos to import in **Videos**.

What AgentTV reads from YouTube: your channel and video list, with titles, descriptions, thumbnails and public stats. It never posts, edits or deletes anything on YouTube.

* Public videos are listed for you to import.
* Unlisted videos import one at a time.
* Private videos cannot be imported.

An account connects one YouTube channel.

## Connect a TikTok or Instagram account

Paste the profile link, such as `https://www.tiktok.com/@your-brand`, in **Imports**, **Paste links**. When the list holds an account link, two more fields show:

* **Start with**: import the **Latest 5 videos**, the **Latest 10 videos**, or **No videos yet**.
* **New uploads**: what happens to new videos (see below).

The account then shows under **Connected channels**. Open **Choose videos to import** to pick more of its videos.

With the API or the account MCP, use `POST /v1/sources` or `manage_source` with `action: "add_account"`:

```json theme={null}
{
  "action": "add_account",
  "account_url": "https://www.tiktok.com/@your-brand",
  "new_uploads": "review_first",
  "import_recent_count": 5
}
```

`import_recent_count` is 0 to 10. Through the API it defaults to 0 and `new_uploads` defaults to `review_first`. In the console, **Start with** defaults to **Latest 5 videos** and **New uploads** to **Import automatically**.

## Choose what happens to new uploads

Each connected source has a new uploads setting. In the console it is the menu on the source's row.

| Console | API value | What happens |
| - | - | - |
| **Import automatically** | `automatic` | New uploads import by themselves. Each one uses your allowance. |
| **Review new uploads first** | `review_first` | New uploads are listed for you. Nothing imports until you pick it. |
| **Don't check for new uploads** | `off` | AgentTV stops watching the source. This pauses it. Videos already imported stay. |

To change it with the API or MCP, use `POST /v1/sources` or `manage_source` with `action: "set_new_uploads"`, `source_id` and `new_uploads`.

A YouTube channel that needs a new Google sign-in cannot import automatically. Choose **Reconnect YouTube** on its row.

## Check now, pause and remove

| Action | Console | API and MCP |
| - | - | - |
| Check now | Row menu, **Check now** (TikTok and Instagram) | `action: "check_now"` with `source_id` |
| Pause | New uploads menu, **Don't check for new uploads** | `action: "set_new_uploads"` with `new_uploads: "off"` |
| Remove | Row menu, **Remove channel** | `action: "remove"` with `source_id` |

**Check now** reads the source for new videos and imports up to `import_recent_count` of them (default 5, up to 10). Videos already in your library are skipped. With the API and MCP, check now also works on a connected YouTube channel. Set `import_recent_count` to 0 to only list new videos.

**Remove** disconnects the source. Videos already imported stay in your library and stay published. For a YouTube channel, the Google access ends and the YouTube data AgentTV read through it is deleted. To connect it again, sign in with Google in the console.

For YouTube, the row menu also has **Revoke access**. It ends the Google access and keeps the videos already imported.

List your sources with `GET /v1/sources` or `list_sources`. Each source has `id`, `platform`, `state`, `new_uploads`, `last_successful_sync_at` and `can_check_now`. Tokens are never returned.

## Import allowance

Each imported video uses your plan allowance: one video, plus the video's length in minutes. **Imports** shows what is left under **Add videos**, such as "8 videos and 120 minutes left".

Every import preview says what it uses:

* A new video uses 1 video and its length. If it is longer than what you have left, the import pauses and uses nothing.
* A video already in your library uses nothing.
* A video AgentTV already processed is added at once and uses nothing.
* When the allowance is used up, the preview says the import would not start (`would_pause`). Nothing is used.

Connecting an account with recent videos, check now, and automatic new uploads each use the allowance for every video they import. The preview says so before you confirm.

## After the import

A video is downloaded and processed. This takes minutes to hours. You can watch it in **Imports**, **History**, or in **Videos**.

| `video_status` | Meaning |
| - | - |
| `cataloged` | Listed from a source, not imported yet. |
| `queued` | Waiting for processing to start. |
| `downloading` | The video is being copied. |
| `processing` | The video is being read: transcript, chapters and moments. |
| `live` | Ready. AI can use it. |
| `failed` | Processing failed. |
| `unsupported` | The video has no media AgentTV can read. |
| `removed` | The video was removed. |

To be told when a video is ready instead of polling, add a webhook for `video.live`. See [Webhooks](https://docs.agentcdn.com/guides/webhooks.md).

## YouTube Analytics

If you connected a YouTube channel, you can also turn on YouTube Analytics. Open a YouTube video in **Videos**, choose the **Analytics** tab, then **Turn on YouTube Analytics**. Google asks you to allow read-only access to your channel's analytics.

You then see, for each of your YouTube videos:

* Where viewers rewatch and where they drop off
* The YouTube searches that found the video
* Daily views and watch time
* Traffic sources, devices, countries, age and gender

Revenue is a separate step. In the **Revenue** section, choose **Show revenue**. **Memory** also shows an **On YouTube** block with views and searches across your videos.

The numbers are YouTube's, shown as YouTube reports them. Only you, the channel owner, see them. They are never shown to visitors or given to AI agents that use your public videos. Disconnecting YouTube deletes them.

To read them yourself, use `GET /v1/videos/{video_id}/youtube-analytics` or the account MCP tool `get_video_youtube_analytics`:

```bash theme={null}
curl "https://api.agentcdn.com/v1/videos/vid_123/youtube-analytics" \
  -H "Authorization: Bearer $AGENTCDN_API_KEY"
```

When `analytics_scope_granted` is `false`, YouTube Analytics is not turned on and `reports` is empty.

## Reference

| Task | API | Account MCP tool |
| - | - | - |
| Import a link | `POST /v1/imports` | `start_import` |
| Follow an import | `GET /v1/imports/{import_id}` | `get_import` |
| List sources | `GET /v1/sources` | `list_sources` |
| Add, change, check or remove a source | `POST /v1/sources` | `manage_source` |
| YouTube Analytics for a video | `GET /v1/videos/{video_id}/youtube-analytics` | `get_video_youtube_analytics` |

API keys: [API keys](https://docs.agentcdn.com/api-keys.md). All endpoints: [API reference](https://docs.agentcdn.com/api-reference/overview.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.