---
title: "Register a YouTube video's METADATA from the user's own connected channel (idempotent)"
method: POST
path: "/api/v1/videos/import"
---

# Register a YouTube video's METADATA from the user's own connected channel (idempotent)

`POST /api/v1/videos/import`

## Request

- Base URL: `https://everpop.app`
- URL: `https://everpop.app/api/v1/videos/import`
- Auth: HTTP bearer

Metadata only — the video cannot be clipped until its file is uploaded (pair with /videos/upload + linkSourceVideoId).

## Request body

- object
  - `url` string, required
  - `rightsConfirmed` boolean

## Response `200`

The library video — browserUploadUrl is the sign-in-gated page where the user uploads this video's file (null once it has one).

- ImportVideoEnvelope
  - `ok` unknown, required
  - `data` object, required
    - `videoId` string, required: A sourceVideoId for POST /api/v1/clip once the video's file is uploaded.
    - `title` string, required
    - `existing` boolean, required: true when the video was already in the library (the call is idempotent).
    - `browserUploadUrl` string, uri, nullable, required: The sign-in-gated page where the user uploads this video's file; null once it has one.

## Other responses

- `400`: No YouTube channel is connected to the account; the user connects one first.
- `401`: The API key did not authenticate. code=key_missing: no Authorization: Bearer epk_... header. code=key_invalid: the key is unknown or revoked. code=key_expired: the key passed its expiry; the user creates a new one in Dashboard → API.
- `402`: REST and MCP need the Pro or Scale plan. reason=subscription: the account has no active subscription (subscribe, or redeem an invite code). reason=plan: the account's plan doesn't include this (API and agent access need Pro or Scale).
- `403`: The video belongs to a channel the user has not connected: import again with rightsConfirmed only if the USER confirms they hold the rights. Also code=scope (read-only key) or code=suspended.
- `404`: The video is not on YouTube (deleted or private).
- `422`: No YouTube video id in url, or the body did not validate.
- `429`: Too many requests. code=rate_limited: the per-minute limit; wait Retry-After (60) seconds. code=quota_exhausted (with used, limit, resetsAt, retryable: false): the monthly allowance is used up; Retry-After is the seconds until resetsAt — tell the user rather than wait. code=queue_capacity (retryable: true): the render queue is full; retry after Retry-After (180).
- `502`: code=upstream_error — YouTube credentials could not be refreshed or YouTube refused the request (the message says why); reconnecting the channel usually fixes it.

---

[API](https://skmtc.dev/everpop/apis/everpop-api.md) · [All operations](https://skmtc.dev/everpop/apis/everpop-api/llms.txt) · [OpenAPI document](https://skmtc.dev/everpop/apis/everpop-api/revisions/1a9fb20867f5?raw)