Video Actions

These endpoints let you take actions on individual videos within a bundle — publish, finalize, request corrections, or unschedule.

Publish a Video

Publish a single configured video on an already-active bundle. Use this after adding new video slots to an accepted bundle, configuring them, and wanting the account manager to start working on them.

POST /bundles/:id/videos/:position/publish

The bundle must be in published, published_priority, or accepted status. The video must be in configured status.

curl -X POST https://app.tokportal.com/api/ext/bundles/{id}/videos/3/publish \
  -H "X-API-Key: sk_xxx"

Response:

{
  "data": {
    "video_id": "uuid",
    "position": 3,
    "bundle_id": "uuid",
    "status": "published"
  }
}

Publish All Configured Videos

Publish all configured videos on a bundle at once. Useful after batch-configuring multiple new slots.

POST /bundles/:id/videos/publish-all

curl -X POST https://app.tokportal.com/api/ext/bundles/{id}/videos/publish-all \
  -H "X-API-Key: sk_xxx"

Response:

{
  "data": {
    "bundle_id": "uuid",
    "videos_published": 3,
    "video_ids": ["uuid1", "uuid2", "uuid3"]
  }
}

TIP: Typical workflow for adding videos to an active bundle

1. POST /bundles/:id/add-video-slots — Add new slots (credits debited)
2. PUT /bundles/:id/videos/batch — Configure the new videos
3. POST /bundles/:id/videos/publish-all — Publish them so the manager can start

Finalize a Video

POST /bundles/:id/videos/:position/finalize

Marks a video as finalized, completing its lifecycle. Once finalized, no further changes can be made to the video.

A video can only be finalized when its current status is in_review.

WARNING: 3-day review window The review window lasts 72 hours from the time the video listing enters in_review. If you do not finalize the video or request corrections during that window, TokPortal automatically changes its status to finalized. Once finalized, no further corrections can be requested.

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

Response:

{
  "data": {
    "video_id": "uuid",
    "position": 1,
    "bundle_id": "bundle_abc123",
    "status": "finalized"
  }
}

Error — invalid status transition:

{
  "error": {
    "code": "VIDEO_INVALID_STATUS",
    "message": "This video is not in a valid status for this action.",
    "details": {
      "current_status": "configured",
      "required": "in_review"
    }
  }
}

Request Corrections

POST /bundles/:id/videos/:position/corrections

Sends the video back to the account manager with correction instructions. The video must currently be in_review; its status becomes pending_corrections.

Field	Type	Required	Description
comment	string	Yes	Instructions describing what needs to be changed (1-2,000 characters).
fields	object	No	Boolean flags for the affected areas: video_content, description, video_editing, and/or sound. Omitted fields are not flagged.

curl -X POST https://app.tokportal.com/api/ext/bundles/bundle_abc123/videos/2/corrections \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Sound only: replace the current sound with the official campaign track. Do not change the video or caption.",
    "fields": {
      "sound": true
    }
  }'

Response:

{
  "data": {
    "video_id": "uuid",
    "position": 2,
    "bundle_id": "bundle_abc123",
    "status": "pending_corrections"
  }
}

Unschedule a Video

POST /bundles/:id/videos/:position/unschedule

Reverts a video back to configured status (cancels scheduling). Works on published, configured, or accepted videos.

curl -X POST https://app.tokportal.com/api/ext/bundles/bundle_abc123/videos/3/unschedule \
  -H "X-API-Key: sk_xxx"

Response:

{
  "data": {
    "video_id": "uuid",
    "position": 3,
    "bundle_id": "uuid",
    "status": "configured"
  }
}

Error — invalid status:

{
  "error": {
    "code": "VIDEO_INVALID_STATUS",
    "message": "Invalid video status for this action.",
    "details": {
      "current_status": "finalized",
      "allowed": ["published", "configured", "accepted"],
      "hint": "Only published, configured, or accepted videos can be unscheduled."
    }
  }
}

Reset a Video

POST /bundles/:id/videos/:position/reset

Clears all configuration from a video slot — description, URL, dates, sound, editing instructions, and all platform-specific fields — returning it to a blank state. The slot itself is preserved and can be reconfigured with PUT /bundles/:id/videos/:position.

Only works on pending or configured videos. If a video is published or accepted, use unschedule first, then reset.

curl -X POST https://app.tokportal.com/api/ext/bundles/bundle_abc123/videos/3/reset \
  -H "X-API-Key: sk_xxx"

Response:

{
  "data": {
    "video_id": "uuid",
    "position": 3,
    "bundle_id": "uuid",
    "status": "configured",
    "message": "Video has been reset to blank state. You can reconfigure it with PUT /bundles/:id/videos/:position."
  }
}

Error — invalid status:

{
  "error": {
    "code": "VIDEO_INVALID_STATUS",
    "details": {
      "current_status": "accepted",
      "allowed": ["pending", "configured"],
      "hint": "Only pending or configured videos can be reset. Use unschedule first if the video is published or accepted."
    }
  }
}

TIP: To fully clear a published or accepted video

1. POST /bundles/:id/videos/:position/unschedule — reverts to configured
2. POST /bundles/:id/videos/:position/reset — clears all configuration

Action Summary

Action	Endpoint	Allowed From Status	Result Status
Publish	POST .../publish	configured	published
Finalize	POST .../finalize	in_review	finalized
Corrections	POST .../corrections	in_review	pending_corrections
Unschedule	POST .../unschedule	published, configured, accepted	configured
Reset	POST .../reset	pending, configured	(blank, same status)
Fix Download	POST .../fix-download	any (requires download_issue: true)	(same status, issue cleared)

See also: Fix Download Link for full details on detecting and fixing broken links.