---
title: "Edit Captions Text"
method: POST
path: "/medias/{mediaHashedId}/captions/{languageCode}/edits"
tags: ["Captions"]
---

# Edit Captions Text

`POST /medias/{mediaHashedId}/captions/{languageCode}/edits`

## Request

- Base URL: `https://api.wistia.com/modern`
- URL: `https://api.wistia.com/modern/medias/{mediaHashedId}/captions/{languageCode}/edits`
- Auth: HTTP bearer

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.

An [expiring access token](https://docs.wistia.com/reference/post_expiring-token)
created with the `all:delegate_to_contact_permissions` scope and an
authorization granting the `edit-transcripts` permission on this media can
also be used. When the media is a composite whose captions belong to
another media, the token also needs `edit-transcripts` on that media.

## Path parameters

- `mediaHashedId` string, required
- `languageCode` string, required

## Headers

- `X-Wistia-API-Version` string, required

## Request body

- object
  - `edits` object[], required: The corrections to apply, all-or-nothing, in one new version.
    - `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.

## Response `200`

Corrections applied; a new caption version was written.

- object: The batch was applied and a new caption version was written.
  - `applied` boolean, required: Always true on a 200; the whole batch was applied.
  - `media_id` string, required: The hashed ID of the media whose transcript was edited. Differs from the path media when the transcript is projected from a composite recording.
  - `language` string, required: The ISO-639-2 language tag of the edited caption track.
  - `version` object, required: The caption version before and after the edit.
    - `from` integer, required
    - `to` integer, required
  - `edits` object[], required: One entry per applied edit, echoing what matched and where it landed.
    - `target_text` string, required: The target text that was sent.
    - `replacement_text` string, required: The replacement text that was sent (empty string for a deletion).
    - `matched_text` string, required: The transcript text that actually matched (may differ from target_text only in normalization).
    - `context` string, required: Surrounding transcript text for the match, for disambiguation.
    - `original` object, required: The matched span's time range, in the requested media's coordinate space.
      - `start_ms` integer, required
      - `end_ms` integer, required
    - `replacement` object, nullable, required: The replacement span's new time range, or null when the target was deleted.
      - `start_ms` integer, required
      - `end_ms` integer, required
  - `warnings` string[], required: Non-fatal advisories, usually empty. For a Remix output, these may identify source media whose transcripts can be edited.

## Other responses

- `400`: Bad request
- `401`: Unauthorized, invalid or missing token
- `403`: Forbidden, token is valid but account does not have access to feature
- `404`: Resource not found
- `409`: The 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.
- `422`: One or more edits could not be resolved; nothing was written.
- `500`: Internal server error

## Changes

- **2026-11-03** `b86cb2a7b420`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/wistia/apis/data-api/changes/medias/:mediaHashedId/captions/:languageCode/edits/post.md)

---

[API](https://skmtc.dev/wistia/apis/data-api.md) - [All operations](https://skmtc.dev/wistia/apis/data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/wistia/apis/data-api/revisions/b86cb2a7b420?raw)