STEP 4 — IMPORT CONTENT

Endpoints in this step support importing content from YouTube (playlists, individual videos, pasted URLs) or uploading files. All require authentication unless noted.

13. GET /onboarding/import/options

Get all available content import methods.

Request

GET /onboarding/import/options
Authorization: Bearer <token>

Response 200 OK

{
  "status": "success",
  "data": {
    "import_options": [
      {
        "id": "import_playlists",
        "label": "Import Playlists",
        "description": "Import entire playlists from your YouTube channel",
        "badge": "FASTEST",
        "icon": "playlist-icon",
        "requires_platform": "youtube",
        "platform_connected": true
      },
      {
        "id": "select_videos",
        "label": "Select Videos",
        "description": "Choose specific videos to import",
        "requires_platform": "youtube",
        "platform_connected": true
      },
      {
        "id": "paste_links",
        "label": "Paste Links",
        "description": "Paste YouTube video URLs directly",
        "requires_platform": null,
        "platform_connected": null
      },
      {
        "id": "upload_files",
        "label": "Upload Files",
        "description": "Upload video files from your device",
        "requires_platform": null,
        "platform_connected": null
      }
    ]
  }
}

14. GET /onboarding/import/playlists

Fetch playlists from the connected YouTube account.

Query Parameters

Parameter	Type	Required	Default	Description
platform	string	No	youtube	Social platform
page	int	No	1	Page number
limit	int	No	20	Results per page

Request

GET /onboarding/import/playlists?platform=youtube&page=1&limit=20
Authorization: Bearer <token>

Response 200 OK

Returns platform, total, page, limit, and playlists array (each with playlist_id, title, emoji, thumbnail_url, video_count, last_updated, last_updated_formatted).

15. GET /onboarding/import/videos

Fetch individual videos from connected YouTube account.

Query Parameters

Parameter	Type	Required	Default	Description
platform	string	No	youtube	Social platform
playlist_id	string	No	—	Filter by playlist
q	string	No	—	Search query
page	int	No	1	Page number
limit	int	No	20	Results per page

Request

GET /onboarding/import/videos?platform=youtube&page=1&limit=20
Authorization: Bearer <token>

Response 200 OK

Returns platform, total, page, limit, and videos array (each with video_id, title, thumbnail_url, duration_seconds, duration_formatted, views, published_at, etc.).

16. POST /onboarding/import/playlists

Import selected playlists from YouTube.

Request Body

{
  "platform": "youtube",
  "playlist_ids": ["PLxxxxxxxxxxxxxxx", "PLyyyyyyyyyyyyyyy"]
}

Response 202 Accepted

{
  "status": "success",
  "message": "Import started for 2 playlists",
  "data": {
    "job_id": "import_job_abc123",
    "platform": "youtube",
    "playlists_queued": 2,
    "estimated_videos": 36,
    "status": "processing",
    "started_at": "2024-11-01T10:00:00Z",
    "estimated_completion_seconds": 45,
    "poll_url": "/onboarding/import/status?job_id=import_job_abc123"
  }
}

17. POST /onboarding/import/videos

Import specific selected videos from YouTube.

Request Body

{
  "platform": "youtube",
  "video_ids": ["dQw4w9WgXcQ", "abc123xyz"]
}

Response 202 Accepted

Returns job_id, platform, videos_queued, status, started_at, estimated_completion_seconds, poll_url.

18. POST /onboarding/import/links

Import content by pasting YouTube video URLs.

Request Body

{
  "urls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "https://youtu.be/abc123xyz"
  ]
}

Response 202 Accepted

Returns job_id, urls_queued, urls_invalid, status, poll_url.

Errors

{
  "status": "error",
  "code": 422,
  "errors": [
    { "url": "https://notayoutube.com/video", "reason": "Only YouTube URLs are supported" }
  ]
}

19. POST /onboarding/import/upload

Upload video files directly from device. Use multipart/form-data. Fields: files (file[]), optional titles (string[]).

Response 202 Accepted

Returns job_id, files_queued, total_size_bytes, total_size_formatted, status, upload_progress_percent, poll_url.

Errors

{
  "status": "error",
  "code": 413,
  "message": "File too large. Maximum file size is 10GB per video."
}

20. GET /onboarding/import/status

Poll import or upload job status.

Query Parameters

Parameter	Type	Required	Description
job_id	string	Yes	Job ID from import/upload response

Request

GET /onboarding/import/status?job_id=import_job_abc123
Authorization: Bearer <token>

Response 200 OK (In Progress)

Returns job_id, status (e.g. "processing"), progress_percent, videos_processed, videos_total, videos_failed, started_at, estimated_completion_at.

Response 200 OK (Completed)

Returns status: "completed", progress_percent: 100, videos_processed, videos_total, completed_at, imported_videos array, and onboarding with updated current_step, percent_complete.

Response 200 OK (Failed)

Returns status: "failed", error_message, failed_at.