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
`story`	A TikTok/Instagram Story — one video or one image, no description. Counts as one video slot and is verified by an account-manager screenshot (`evidence_screenshot`). See Configure Videos → Story Fields.

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.
`story`	Exactly one media: `video_url` or `story_image_url`. No description. Optional same-platform `story_repost_url` (+1 credit).

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

INFO: 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.

Instagram also supports video_type: "story" (one video or one image, no instagram_content_type). See Configure Videos → Story Fields.

YouTube

YouTube support is not available in the current public API. You may see reserved YouTube fields in templates or generated schemas, but public bundle creation currently supports TikTok and Instagram.

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: sk_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: sk_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
Patch Video Metadata	Update `external_ref` or `name` at any time without re-uploading content
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