Videos

Patch video metadata or schedule

Changes a configured slot's name, description, external reference or schedule without re-sending its media. Rescheduling obeys the maximum of 3 videos per day per bundle AND — enforced since 2026-08-26, where before only the per-day cap ran — the same minimum publish lead time as configuration: today+1 with a delivered or existing account, today+3 while the account is still being created, in UTC. Today and any past date are rejected with INVALID_DATE carrying min_days_ahead and earliest_allowed (YYYY-MM-DD), the same shape the configure PUT returns. Send either target_publish_date (a 2-day window whose end is derived as that day + 1) or the target_publish_start_date/target_publish_end_date pair, never both — this is the ONLY endpoint where the window's end can be chosen, and it must fall strictly after the start. Cannot be used once the video is finalized. Requires active TokPortal Coverage on the resolved saved account, or permanent grandfathering: a due period renews automatically at the account's stored rate immediately before execution, and nothing starts if it cannot renew. See getAccountManagedSubscription.

patch/bundles/{id}/videos/{position}

Request

  • Base URL: https://app.tokportal.com/api/ext
  • URL: https://app.tokportal.com/api/ext/bundles/{id}/videos/{position}
  • Auth: API key in header X-API-Key

Path parameters

idstring uuid required

Bundle ID.

positioninteger required

1-based video slot position.

Headers

X-TokPortal-Dry-Run'true' | '1' | 'yes'

Send true (or 1/yes) to SIMULATE this call instead of executing it. A dry run performs the full validation and pricing path of the real operation and stops before the first write: no credits are debited, no rows are created, no webhooks fire, and no operator ever sees it. The response has the same shape and status as the real call and adds dry_run: true, dry_run_notice, and — on credit-spending operations — credits_would_charge carrying the real price. Errors are identical to the real call, which is the point: this is how you learn what an operation will do before paying for it. Rate limits are consumed normally, a supplied Idempotency-Key is ignored rather than burned, and identifiers returned by a dry run are synthetic (see DRY_RUN_ID_IN_LIVE_REQUEST).

Request body

external_refstring nullable
namestring nullable
descriptionstring nullable
target_publish_datestring nullable

YYYY-MM-DD. Shorthand for a 2-day window: the end day is derived as this day + 1. Max 3 videos per day per bundle — a 4th video on the same day is rejected with VIDEOS_PER_DAY_EXCEEDED. Minimum lead time, in UTC: the earliest allowed date is today+3 days while the bundle is still having its account created, and today+1 once that account is delivered or when the bundle runs on an existing account; an earlier date is rejected with INVALID_DATE carrying min_days_ahead and earliest_allowed (YYYY-MM-DD). Cannot be combined with target_publish_start_date / target_publish_end_date.

target_publish_start_datestring date-time nullable

Start of an EXPLICIT publication window (ISO 8601 date-time). This is the only endpoint where the window's end is choosable — configuration and CSV import always derive it as start + 1 day. Send it together with target_publish_end_date and never alongside target_publish_date. Since 2026-08-26 it obeys the same minimum lead time as configuration (today+1 with a delivered or existing account, today+3 while the account is still being created, in UTC); an earlier value is rejected with INVALID_DATE carrying min_days_ahead and earliest_allowed.

target_publish_end_datestring date-time nullable

End of an EXPLICIT publication window (ISO 8601 date-time). Must be strictly after target_publish_start_date, and must be sent together with it — never alongside target_publish_date, and never on the configuration or CSV endpoints, where the end is derived and this field is refused.

Response

Patched video slot.

object required

Changes

No recorded changes to this operation across all 1 revision of this API.