TokPortal video reschedule: use PATCH for partial edits, PUT for replacement

A narrow API choice can create a very practical editorial failure. Suppose a team has already configured a TokPortal video slot with the correct media, sound, and platform-specific fields. Later, someone only wants to adjust the caption or move the publishing window. At that moment, the question is not abstract REST style. It is whether the operator should resend the full slot with PUT or make a smaller change with PATCH. TokPortal’s current configuration docs answer that directly: single-slot PUT is a full-replace write, so omitted fields are cleared, while PATCH exists for lightweight metadata edits and rescheduling [1]. For an AI-assisted workflow, that distinction matters because “reconstruct the whole object from memory” is exactly where accidental field loss becomes likely.

The safest default is therefore simple: if the slot’s media configuration is already correct and you do not intend to redefine it, use PATCH. TokPortal documents PATCH /bundles/:id/videos/:position as the endpoint for updating external_ref, name, description, or schedule without re-uploading content [1]. The same page explicitly describes it as the reschedule endpoint, and the only place where the publishing window’s end day can be chosen [1]. That last detail is easy to miss. On configure PUT, target_publish_date represents a two-day window whose end is derived automatically; target_publish_end_date is not valid there [1]. So this is not only about reducing risk. It is also about choosing the endpoint that exposes the scheduling control you actually need.

PUT still has a valid role, but it is narrower than many operators assume. Use it when your intent is to define the slot’s complete configuration: media type, asset fields, caption, schedule, and any applicable extras. TokPortal warns that PUT /bundles/:id/videos/:position and batch PUT both replace the slot’s entire configuration, and a field you omit is cleared rather than preserved [1]. The docs also note a related change in validation behavior: an unrecognized field is now refused with 400 UNKNOWN_FIELD instead of being silently stripped in the full-replace flow [1]. That reduces one class of silent mistakes, but it does not solve the more ordinary one: sending a technically valid body that is incomplete for your real intent. In other words, a well-formed PUT can still be the wrong operational choice.

A reusable procedure for agents and human operators is: first classify the intended change, then choose the smallest write surface that matches it. Step 1: list the fields that truly need to change. Step 2: if the set is limited to external_ref, name, description, or scheduling fields, prefer PATCH [1]. Step 3: if the change requires redefining media or other slot-defining fields, prepare a full PUT body and treat it as authoritative replacement [1]. Step 4: run a dry run before live execution so the request goes through the same validation and pricing path but stops before the first write; TokPortal documents that a dry run creates no rows, debits no credits, and fires no webhook [2]. Step 5: only after validation passes should the operator send the real call. This sequence is a workflow choice, not a platform requirement. The platform requires valid inputs; the extra classification step is how you avoid self-inflicted configuration loss.

One more detail changes the practical rescheduling rule: PATCH is no longer a loophole around date validation. TokPortal’s docs state that rescheduling now obeys the same minimum lead time as configuration, with earlier dates rejected as INVALID_DATE and the response carrying details such as min_days_ahead and earliest_allowed [1]. The exact minimum depends on bundle state: today + 3 while an account is still being created, and today + 1 for a delivered or existing account, in UTC [1]. That means PATCH is safer for preserving slot fields, but not looser about scheduling. An agent that used to think “PATCH is just a harmless date tweak” should instead treat it as a real write subject to operational constraints.

Worked example — HYPOTHETICAL SAMPLE INPUTS. Imagine a delivered account with bundle ID bnd_example_01 and slot position 1. The slot already contains a valid video_url, an approved description, and a TikTok sound URL. Editorial review decides only two things should change: the caption needs one clarification, and the acceptable publishing window should move from a start date of 2026-09-14 to an explicit UTC window spanning 2026-09-15T00:00:00Z through 2026-09-16T00:00:00Z. Because the media and platform-specific settings should remain untouched, the safer operation is a dry-run PATCH, not a reconstructive PUT. A hypothetical MCP-style request would look like this: {"name":"tokportal_patch_bundle_video","arguments":{"dry_run":true,"id":"bnd_example_01","position":1,"body":{"description":"Clarified caption for the same video asset.","target_publish_start_date":"2026-09-15T00:00:00Z","target_publish_end_date":"2026-09-16T00:00:00Z"}}}. The important point is not this exact JSON. It is the decision logic behind it: use PATCH because the intended edit is partial, and use dry_run because the same validation can be checked without producing live side effects [1][2].

For agent design, this suggests a durable rule: do not let the endpoint be selected merely by which schema your system happens to cache. Let it be selected by intent. If intent equals “replace the whole slot,” use PUT. If intent equals “preserve the slot and alter only lightweight metadata or timing,” use PATCH [1]. Add two guardrails from the docs. First, log the API version and request ID headers returned by the server, because TokPortal treats the public API as a versioned stable contract and includes a request identifier for correlation [3]. Second, treat dry runs and live calls as separate states in your audit trail; the sandbox docs are explicit that dry-run identifiers are synthetic, do not exist live, and should not be carried into real requests [2]. That combination—intent-based endpoint choice, preview before write, and version-aware logging—is a more robust operating pattern than “always PUT the latest object.”