--- updatedAt: 2026-08-07T13:12:19.000Z agentTools: projectIndex: https://docs.wistia.com/llms.txt --- # Edit Captions Text 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. # OpenAPI definition ````json { "openapi": "3.1.1", "info": { "title": "Data API", "description": "Wistia Data API", "version": "2026.09.0" }, "servers": [ { "url": "https://api.wistia.com/modern" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Captions" } ], "paths": { "/medias/{mediaHashedId}/captions/{languageCode}/edits": { "post": { "summary": "Edit Captions Text", "x-speakeasy-group": "captions", "x-speakeasy-name-override": "edit", "description": "Applies targeted find-and-replace corrections to a media's transcript for\nthe specified language, preserving the timings of unchanged words. The whole\nbatch is applied atomically against a specific caption version, or nothing is.\n\n## Requires api token with one of the following permissions\n```\nRead, update & delete anything\n```\n\nTokens with the \"Act with a team member's permissions\" permission\n(`all:delegate_to_contact_permissions` scope) can also be used. Requests\nmade with such a token are authorized using the permissions of the\ncontact assigned to the token.\n\nAn [expiring access token](https://docs.wistia.com/reference/post_expiring-token)\ncreated with the `all:delegate_to_contact_permissions` scope and an\nauthorization granting the `edit-transcripts` permission on this media can\nalso be used. When the media is a composite whose captions belong to\nanother media, the token also needs `edit-transcripts` on that media.\n", "parameters": [ { "name": "mediaHashedId", "in": "path", "description": "The hashed ID of the media whose transcript should be edited.", "required": true, "schema": { "type": "string" } }, { "name": "languageCode", "in": "path", "description": "The 3-character ISO 639-2 language code of the caption track to edit (e.g., `eng`, `fre`, `spa`). Some languages use extended IETF subtags (e.g., `zh-Hant`).", "required": true, "schema": { "type": "string" } }, { "name": "X-Wistia-API-Version", "in": "header", "required": true, "schema": { "type": "string", "default": "2026-09" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "unevaluatedProperties": false, "properties": { "edits": { "description": "The corrections to apply, all-or-nothing, in one new version.", "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "unevaluatedProperties": false, "properties": { "target_text": { "description": "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.", "type": "string" }, "replacement_text": { "description": "The text to substitute for the target. Use an empty string to delete the target.", "type": "string" }, "start_ms": { "description": "Optional lower bound (inclusive, in the requested media's coordinate space) restricting the match to a time window. Omit to start at the beginning.", "type": "integer" }, "end_ms": { "description": "Optional upper bound (inclusive) restricting the match to a time window. Omit to run to the end.", "type": "integer" } }, "required": [ "target_text", "replacement_text" ] } }, "expected_version": { "description": "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.", "type": "integer" } }, "required": [ "edits", "expected_version" ] } } } }, "responses": { "200": { "description": "Corrections applied; a new caption version was written.", "content": { "application/json": { "schema": { "description": "The batch was applied and a new caption version was written.", "type": "object", "unevaluatedProperties": false, "properties": { "applied": { "description": "Always true on a 200; the whole batch was applied.", "type": "boolean" }, "media_id": { "description": "The hashed ID of the media whose transcript was edited. Differs from the path media when the transcript is projected from a composite recording.", "type": "string" }, "language": { "description": "The ISO-639-2 language tag of the edited caption track.", "type": "string" }, "version": { "description": "The caption version before and after the edit.", "type": "object", "unevaluatedProperties": false, "properties": { "from": { "type": "integer" }, "to": { "type": "integer" } }, "required": [ "from", "to" ] }, "edits": { "description": "One entry per applied edit, echoing what matched and where it landed.", "type": "array", "items": { "type": "object", "unevaluatedProperties": false, "properties": { "target_text": { "description": "The target text that was sent.", "type": "string" }, "replacement_text": { "description": "The replacement text that was sent (empty string for a deletion).", "type": "string" }, "matched_text": { "description": "The transcript text that actually matched (may differ from target_text only in normalization).", "type": "string" }, "context": { "description": "Surrounding transcript text for the match, for disambiguation.", "type": "string" }, "original": { "description": "The matched span's time range, in the requested media's coordinate space.", "type": "object", "unevaluatedProperties": false, "properties": { "start_ms": { "type": "integer" }, "end_ms": { "type": "integer" } }, "required": [ "start_ms", "end_ms" ] }, "replacement": { "description": "The replacement span's new time range, or null when the target was deleted.", "type": [ "object", "null" ], "unevaluatedProperties": false, "properties": { "start_ms": { "type": "integer" }, "end_ms": { "type": "integer" } }, "required": [ "start_ms", "end_ms" ] } }, "required": [ "target_text", "replacement_text", "matched_text", "context", "original", "replacement" ] } }, "warnings": { "description": "Non-fatal advisories, usually empty. For a Remix output, these may identify source media whose transcripts can be edited.", "type": "array", "items": { "type": "string" } } }, "required": [ "applied", "media_id", "language", "version", "edits", "warnings" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "error": { "description": "Error message detailing the reason for the bad request.", "type": "string", "examples": [ "Bad request" ] }, "errors": { "description": "Array of error messages detailing the reasons for the bad request.", "type": "array", "items": { "type": "string" } } } } } } }, "401": { "description": "Unauthorized, invalid or missing token", "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "code": { "description": "A machine-readable identifier for the specific authorization failure.", "type": "string", "enum": [ "unauthorized_credentials", "account_inactive", "unauthorized_scope", "unauthorized_params" ] }, "error": { "type": "string", "examples": [ "Invalid credentials." ] } } } } } }, "403": { "description": "Forbidden, token is valid but account does not have access to feature", "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "error": { "type": "string", "examples": [ "Webinars are not available on your current plan" ] } } } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "error": { "type": "string", "examples": [ "Folder with ID 'fakeid' not found." ] } } } } } }, "409": { "description": "The version guard failed. For `stale_version`, re-read and retry with the\nactive version. For `diverged`, newer inactive versions exist, so\nre-reading will not help; wait and retry, then escalate if it persists.\n", "content": { "application/json": { "schema": { "type": "object", "unevaluatedProperties": false, "properties": { "reason": { "type": "string", "enum": [ "stale_version", "diverged" ] }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "reason", "errors" ] } } } }, "422": { "description": "One or more edits could not be resolved; nothing was written.", "content": { "application/json": { "schema": { "description": "One or more edits could not be resolved, so nothing was written. Fix the listed failures and retry the whole batch.", "type": "object", "unevaluatedProperties": false, "properties": { "errors": { "description": "Human-readable summary of what went wrong.", "type": "array", "items": { "type": "string" } }, "edit_failures": { "description": "One entry per edit that could not be resolved.", "type": "array", "items": { "type": "object", "unevaluatedProperties": false, "properties": { "target_text": { "description": "The target text of the edit that failed.", "type": "string" }, "reason": { "description": "Why the edit could not be applied. `ambiguous`: matched more than once (disambiguate with a candidate's time range). `not_found`: no exact match (adopt a suggestion's exact text). `overlapping`: two edits target overlapping spans. `spans_paragraph`: the target crosses a paragraph or non-editable boundary.", "type": "string", "enum": [ "ambiguous", "not_found", "overlapping", "spans_paragraph" ] }, "candidates": { "description": "For `ambiguous`, the exact occurrences to choose from (up to 10). For `not_found`, fuzzy suggestions to adopt verbatim (up to 3). Empty for other reasons. Times are in the requested media's coordinate space.", "type": "array", "items": { "type": "object", "unevaluatedProperties": false, "properties": { "text": { "description": "The candidate's transcript text.", "type": "string" }, "context": { "description": "Surrounding transcript text, for disambiguation.", "type": "string" }, "start_ms": { "description": "The candidate span's start in the requested media's coordinate space.", "type": "integer" }, "end_ms": { "description": "The candidate span's end in the requested media's coordinate space.", "type": "integer" } }, "required": [ "text", "context", "start_ms", "end_ms" ] } }, "hint": { "description": "A short instruction for how to recover from this failure.", "type": "string" } }, "required": [ "target_text", "reason", "candidates", "hint" ] } } }, "required": [ "errors", "edit_failures" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "unevaluatedProperties": false, "type": "object", "properties": { "error": { "type": "string", "examples": [ "Internal server error" ] } } } } } } }, "tags": [ "Captions" ], "x-readme": { "code-samples": [ { "name": "Typescript (SDK)", "language": "javascript", "code": "import { Wistia } from \"@wistia/wistia-api-client\";\n\nconst wistia = new Wistia({\n bearerAuth: process.env[\"WISTIA_BEARER_AUTH\"] ?? \"\",\n});\n\nasync function run() {\n const result = await wistia.captions.edit({\n mediaHashedId: \"\",\n languageCode: \"\",\n requestBody: {\n edits: [\n {\n targetText: \"\",\n replacementText: \"\",\n },\n ],\n expectedVersion: 751935,\n },\n });\n\n console.log(result);\n}\n\nrun();" } ] } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "x-readme": { "samples-languages": [ "javascript", "shell", "node", "python", "ruby" ] } } ````