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	Description
reel	video	A Reel with a single video
reel	carousel	A Reel carousel with multiple images
post	video	A feed post with a single video
post	carousel	A feed post with multiple images

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"
    },
    {
      "position": 2,
      "video_type": "carousel",
      "status": "pending",
      "description": null,
      "target_publish_date": null,
      "video_url": null,
      "external_ref": 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"
  }
}

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