Video Actions

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

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: tok_live_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: tok_live_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

Removes the video from the publishing schedule and resets it to pending status. All previously configured content and metadata are cleared.

A video can only be unscheduled when its current status is configured.

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

Response:

{
  "data": {
    "position": 3,
    "status": "pending",
    "unscheduled_at": "2026-02-11T15:30:00Z"
  }
}

Error — invalid status:

{
  "error": {
    "code": "INVALID_STATUS_TRANSITION",
    "message": "Cannot unschedule a video with status 'published'. Only 'configured' videos can be unscheduled.",
    "details": {
      "current_status": "published",
      "allowed_statuses": ["configured"]
    }
  }
}

Action Summary

Action	Endpoint	Allowed From Status	Result Status
Finalize	POST .../finalize	accepted, in_review	finalized
Corrections	POST .../corrections	published, accepted	configured
Unschedule	POST .../unschedule	configured	pending