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 accepted or in_review.

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

Response:

{
  "data": {
    "position": 1,
    "status": "finalized",
    "finalized_at": "2026-02-11T14:30:00Z"
  }
}

Error — invalid status transition:

{
  "error": {
    "code": "INVALID_STATUS_TRANSITION",
    "message": "Cannot finalize a video with status 'configured'. The video must be 'accepted' or 'in_review'.",
    "details": {
      "current_status": "configured",
      "allowed_statuses": ["accepted", "in_review"]
    }
  }
}

Request Corrections

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

Sends the video back to the creator with correction instructions. The video status reverts to configured so the creator can make changes and re-publish.

Field	Type	Required	Description
message	string	Yes	Instructions describing what needs to be changed.

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 '{
    "message": "The brand logo is not visible enough. Please make it larger and move it to the bottom-right corner."
  }'

Response:

{
  "data": {
    "position": 2,
    "status": "configured",
    "correction_requested_at": "2026-02-11T15:00:00Z",
    "correction_message": "The brand logo is not visible enough. Please make it larger and move it to the bottom-right corner."
  }
}

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	accepted, in_review	finalized
Corrections	POST .../corrections	published, accepted	configured
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.