PATCH https://api.vidyard.com/dashboard/v1/captions/:id
Updates a caption

Given a valid caption id, will update the caption using the supplied parameters and values

Warning: Even though the server returns a 200 response, in general, if the response object status indicates it is pending or in progress, it is not safe to assume that the caption file is ready, and so you should use the content status API endpoint to verify it is ready before trying to use it.

Supported Formats

json

Errors

Code Description
401 Unauthorized: auth_token omitted or authentication failed
403 Forbidden: This action cannot be performed
406 Not Acceptable: Accept or Content-Type headers must be application/json, text/csv or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
422 Unprocessable Entity: body has wrong attributes
404 Not Found: The requested resource could not be found
400 Bad Request: body has wrong syntax or unable to handle request

Examples

RESPONSE
Code: 200
Content-Type: application/json
{
  "srt_url": "//cdn.vidyard.com/transcriptions/BeQAX/i-UTPAWS.srt",
  "vtt_url": "//cdn.vidyard.com/transcriptions/BeQAX/Yut9l8z4.vtt",
  "txt_url": "//cdn.vidyard.com/transcriptions/BeQAX/Yut9l8z4.txt",
  "language": "en",
  "id": 1011,
  "status": "pending",
  "formatted_text": "The quick brown fox\njumped over the lazy dog.",
  "plain_text": "The quick brown fox jumped over the lazy dog.",
  "created_at": 1442297000,
  "updated_at": 1442297001,
  "formatted_language_name": "English (en)",
  "localized_language_name": "English",
  "is_default": true,
  "notes": "Transcription request notes",
  "srt_download_url": "//vidyard.s3.amazonaws.com/transcriptions/BeQAX/i-UTPAWS.srt",
  "vtt_download_url": "//vidyard.s3.amazonaws.com/transcriptions/BeQAX/Yut9l8z4.vtt",
  "txt_download_url": "//vidyard.s3.amazonaws.com/transcriptions/BeQAX/Yut9l8z4.txt",
}
RESPONSE
Code: 404
Content-Type: application/json
{
  "error": "404: No caption exists with that id"
}

Params

Param name Description
auth_token
optional

API token needed to authorize requests
This can appear as an attribute in the body of the request or the query parameters on the URL

Validations:

  • Must be a String
vtt_url
optional

The URI of a VTT file that is being used to update the captions content (if any)

Validations:

  • Must be a String
language
optional

A valid language locale code indicating the new language of the caption (if any)

Validations:

  • Must be a String
content
optional

A plaintext representation of the captions content in VTT format (if any)

Warning: Since this is JSON formatted, newlines must be replaced with their escape sequence equivalent (e.g., '\n')

Validations:

  • Must be a String
error_message
optional

Set error message of caption

Validations:

  • Must be a String
is_default
optional

Indicates whether or not this is default caption for the video (if changed)

Validations:

  • Must be one of: true, false, 1, 0.
creator_type
optional , nil allowed

Set the new type of the creator of the caption (if changed)

Validations:

  • Must be one of: Automatic, Manual.

Returns

Code: 200

Description:

The updated caption for the video

Param name Description
srt_url
required

The URI of the SRT-formatted version of the caption

Validations:

  • Must be a String
vtt_url
required

The URI of the VTT-formatted version of the caption

Validations:

  • Must be a String
txt_url
required

The URI of the TXT-formatted version of the caption

Validations:

  • Must be a String
language
required

The language locale code indicating the language the caption is in

Validations:

  • Must be a String
id
required

The internal ID of the caption

Validations:

  • Parameter has to be Integer.
status
required , nil allowed

The current state of the caption

Validations:

  • Must be one of: captioning, complete, draft, error, initializing, in_process, in_progress, published, saving, transcribing.
created_at
required

The timestamp when the caption was created

Validations:

  • Must be a DateTime
updated_at
required

The timestamp when the caption was last updated

Validations:

  • Must be a DateTime
formatted_language_name
required

The name of the language in which the caption was formatted

Validations:

  • Must be a String
localized_language_name
required

The name of the language in which the caption was localized

Validations:

  • Must be a String
is_default
required

Indicates whether or not this is the default caption for the associated video

Validations:

  • Must be one of: true, false, 1, 0.
notes
required

Additional notes created for the user about the caption

Validations:

  • Must be a String
srt_download_url
required

A fully qualified URL from which the SRT-formatted version of the caption can be downloaded

Validations:

  • Must be a String
vtt_download_url
required

A fully qualified URL from which the VTT-formatted version of the caption can be downloaded

Validations:

  • Must be a String
txt_download_url
required

A fully qualified URL from which the TXT-formatted version of the cpation can be downloaded

Validations:

  • Must be a String
creator_type
required

Indicates if the caption was created automatically or manually

Validations:

  • Must be one of: Automatic, Manual.

Code: 404

Description:

Message returned when the caption could not be found

Param name Description
error
required

A contextual error message when a request could not be completed

Validations:

  • Must be a String