Edit Captions Text

post

https://api.wistia.com/modern/medias/{mediaHashedId}/captions/{languageCode}/edits

Applies targeted find-and-replace corrections to a media's transcript for
the specified language, preserving the timings of unchanged words. The whole
batch is applied atomically against a specific caption version, or nothing is.

Requires api token with one of the following permissions

Read, update & delete anything

Tokens with the "Act with a team member's permissions" permission
(all:delegate_to_contact_permissions scope) can also be used. Requests
made with such a token are authorized using the permissions of the
contact assigned to the token.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

mediaHashedId

string

required

The hashed ID of the media whose transcript should be edited.

languageCode

string

required

The 3-character ISO 639-2 language code of the caption track to edit (e.g., eng, fra, spa). Some languages use extended IETF subtags (e.g., zh-Hant).

Body Params

edits

array of objects

required

length between 1 and 20

The corrections to apply, all-or-nothing, in one new version.

edits*

target_text

string

required

The exact transcript text to replace. Matched exactly after normalization (case, punctuation, and whitespace are ignored). Fuzzy matches are never applied — they are only returned as suggestions.

replacement_text

string

required

The text to substitute for the target. Use an empty string to delete the target.

start_ms

integer

Optional lower bound (inclusive, in the requested media's coordinate space) restricting the match to a time window. Must be sent with end_ms.

end_ms

integer

Optional upper bound (inclusive) restricting the match to a time window. Must be sent with start_ms.

expected_version

integer

required

The active caption version returned with the caption content used to prepare these edits. The edit applies only if that is still the active version; otherwise it returns 409 so you re-read and retry.

Headers

X-Wistia-API-Version

string

required

Defaults to 2026-09

Responses

Language

Credentials

Bearer

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Corrections applied; a new caption version was written.

400Bad request

401Unauthorized, invalid or missing token

403Forbidden, token is valid but account does not have access to feature

404Resource not found

409The version guard failed. For stale_version, re-read and retry with the active version. For diverged, newer inactive versions exist, so re-reading will not help; wait and retry, then escalate if it persists.

422One or more edits could not be resolved; nothing was written.

500Internal server error