Videos

Videos are the content units within a bundle. Each video occupies a specific position (1-indexed) in the bundle and represents a single piece of content to be published on a creator's social media account.

Video Types

Every video has a video_type that determines what content it contains:

Type	Description
video	A single video file
carousel	Multiple images displayed as a slideshow

Platform-Specific Behavior

Each platform supports different combinations of video types and has its own requirements.

TikTok

Type	Requirements
video	Video file required. Sound URL optional.
carousel	Carousel images required. Sound URL required.

Instagram

Instagram requires the instagram_content_type field to distinguish between reels and feed posts:

Content Type	Video Type	Result
reel	video	Reel Video
reel	carousel	Reel Fixed Photos — creates a video from images (not swipeable)
post	video	Post Video
post	carousel	Post Carousel — swipeable photo carousel

Reel Fixed Photos vs Post Carousel

On Instagram, video_type: "carousel" behaves differently depending on instagram_content_type:

• With "reel": Instagram creates a video from your images (Fixed Photos — not swipeable). This is a Reel, not a carousel.
• With "post": Instagram creates a swipeable photo carousel in the feed.

YouTube

Type	Requirements
video	Video file required. Title, tags, category, and visibility are configurable.

YouTube does not support carousels.

Video Status Lifecycle

Each video progresses through the following statuses:

pending → configured → published → accepted → in_review → finalized

Status	Description
pending	Position exists but no content has been configured yet.
configured	Content has been uploaded and metadata set. Ready for review.
published	The video has been published to the platform by the creator.
accepted	The brand has reviewed and accepted the published video.
in_review	The video is undergoing final review before completion.
finalized	The video lifecycle is complete. No further changes allowed.

Publish Date Rules

The target_publish_date field controls when the video should be published.

• New accounts (not yet delivered): minimum 3 days from today.
• Existing accounts (already delivered): minimum 1 day from today.

Dates earlier than the allowed minimum are rejected with a VALIDATION_ERROR.

List All Videos in a Bundle

Retrieve every video configured for a bundle.

GET /bundles/:id/videos

curl -X GET https://app.tokportal.com/api/ext/bundles/bundle_abc123/videos \
  -H "X-API-Key: tok_live_xxx"

Response:

{
  "data": [
    {
      "position": 1,
      "video_type": "video",
      "status": "configured",
      "description": "Unboxing the new product line",
      "target_publish_date": "2026-03-15",
      "video_url": "https://pub-xxx.r2.dev/videos/abc123.mp4",
      "external_ref": "campaign-42-v1",
      "download_issue": false,
      "download_issue_comment": null
    },
    {
      "position": 2,
      "video_type": "carousel",
      "status": "pending",
      "description": null,
      "target_publish_date": null,
      "video_url": null,
      "external_ref": null,
      "download_issue": false,
      "download_issue_comment": null
    }
  ]
}

Get a Single Video

GET /bundles/:id/videos/:position

curl -X GET https://app.tokportal.com/api/ext/bundles/bundle_abc123/videos/1 \
  -H "X-API-Key: tok_live_xxx"

Response:

{
  "data": {
    "position": 1,
    "video_type": "video",
    "status": "configured",
    "description": "Unboxing the new product line",
    "target_publish_date": "2026-03-15",
    "video_url": "https://pub-xxx.r2.dev/videos/abc123.mp4",
    "tiktok_sound_url": "https://www.tiktok.com/music/original-sound-123",
    "editing_instructions": "Add brand logo at the end",
    "external_ref": "campaign-42-v1",
    "download_issue": false,
    "download_issue_comment": null
  }
}

What's Next

Topic	Description
Configure Videos	Set content, metadata, and platform-specific fields
CSV Import	Bulk-import videos from a CSV file
Video Actions	Finalize, request corrections, or unschedule videos
Fix Download Link	Detect and fix broken download links flagged by managers