Workorder API
The Work Order API allows third-party applications, platforms, and custom workflows to dynamically launch captioning projects inside Closed Caption Creator. Rather than building a subtitle editor, developers can construct a single URL containing a JSON description of the project — including the media source, caption tracks, and publish destinations — and provide that link to their users. When a user opens the link, Closed Caption Creator loads the project automatically and presents the editor ready for work.
How It Works
A Work Order is a JSON object that describes every aspect of a project: its name, frame rate, media source, one or more caption tracks with their import files, and one or more publish destinations where the completed captions will be delivered via HTTP POST. Once the JSON is constructed, it is URL-encoded and appended to the Work Order endpoint as a query parameter:
https://app.closedcaptioncreator.com/workorder?description=<URL-encoded JSON>
When the project is opened, the Work Order Import process runs automatically, loading all configured tracks and media without any manual steps. When the editor is finished, clicking Publish in the toolbar triggers the Work Order Publish workflow, which encodes each track according to its configured publish profile and delivers the file to the specified server address as an HTTP POST request.
Top-Level Properties
The following properties configure the overall project loaded from a Work Order.
| Property | Description | Values | Default |
|---|---|---|---|
task | Sets the permission level. Edit tasks allow full caption editing and publish a new file. Review tasks produce a pass/fail report instead. | edit, review | edit |
projectName | The display name shown in the toolbar. Limited to 100 characters. | String | Untitled |
incode | A global SMPTE timecode offset applied to the entire project. | hh:mm:ss:ff or hh:mm:ss;ff | 00:00:00:00 |
frameRate | The project frame rate used for timecode calculation. Critical for broadcast formats such as SCC and EBU-STL. | 23.976, 24, 25, 29.97, 30, 59.94, 60 | 24 |
dropFrame | Sets drop frame or non-drop frame mode. Only applicable at 29.97 and 59.94 frame rates. | true, false | Derived from frame rate |
mediaUrl | URL to the video source. Can be a cloud storage file, YouTube URL, public Vimeo URL, or HLS stream. Ensure CORS is configured for any bucket origin. | URL String | — |
mediaType | Identifies the media source type so the player loads it correctly. | file, hls, youtube, vimeo | file |
thumbnailUrl | An image to display in the video player before the media loads. | URL to JPG or PNG | — |
publishText | Custom message displayed at the top of the Publish window. | String | — |
redirectUrl | The URL the page navigates to after a successful publish. | URL String | https://app.closedcaptioncreator.com |
importAlertSuccess | A SweetAlert2 config object { title, text } displayed when the Work Order loads successfully. | Object | — |
importAlertError | A SweetAlert2 config object { title, text } displayed when the Work Order fails to load. | Object | — |
publishAlertSuccess | A SweetAlert2 config object { title, text } displayed after a successful publish. | Object | — |
publishAlertError | A SweetAlert2 config object { title, text } displayed after a failed publish. | Object | — |
Track Configuration
The tracks property is an array of objects, each representing one Event Group that will be created in the project. Each track imports a caption file from a URL and specifies how it should be delivered on publish. Multiple tracks can be included in a single Work Order, supporting multilingual projects from a single link.
| Property | Description | Values | Default |
|---|---|---|---|
type | The Event Group type created in the editor. | subtitle, transcription, translation | subtitle |
status | Whether the track will be published. Tracks set to Do Not Publish are available for reference but excluded from the publish workflow. | Publish, Do Not Publish | Publish |
displayName | The track name visible in the Event Group tab in the UI. Limited to 60 characters. | String | Untitled |
language | The track language used for AI translation and spell-check. | ISO 639 language code | en-US |
rtl | Enables right-to-left text direction for languages such as Arabic. | true, false | false |
maxCps | Maximum reading speed in characters per second. Events exceeding this value are flagged. | Integer 0–9999 | 9999 |
maxWpm | Maximum reading speed in words per minute. Events exceeding this value are flagged. | Integer 0–9999 | 9999 |
maxChars | Maximum characters per line per event. | Integer 0–9999 | 32 |
maxLines | Maximum lines per event. | Integer 0–9999 | 2 |
overlaps | When enabled, overlapping events are flagged as errors. | true, false | true |
illegalChars | When enabled, non-608-compliant characters are flagged. | true, false | false |
importOptions.url | Direct URL to the caption or subtitle file to import. | URL String | — |
importOptions.profile | The decode profile used to parse the file. | scenerist, subRip, webVtt, ebuStl, and more | subRip |
importOptions.frameRate | Frame rate of the file being imported, if different from the project. | See frameRate values | 24 |
importOptions.dropFrame | Drop frame setting for the imported file. | true, false | Derived from frame rate |
publishOptions[].url | The server endpoint where the encoded file will be delivered via HTTP POST. | URL String | — |
publishOptions[].profile | The encode profile used to generate the output file. | scenerist, subRip, webVtt, ebuStl, and more | subRip |
publishOptions[].auth | When true, the user is prompted for a username and password before the publish request is sent. | true, false | false |
publishOptions[].offset | A SMPTE timecode offset applied to the output file. | hh:mm:ss:ff | 00:00:00:00 |
publishOptions[].offsetType | Whether the offset is added to or subtracted from all timecodes. | add, subtract | add |
publishOptions[].tcMultiplier | A multiplier applied to timecodes at export, useful when delivering a file at a different frame rate than the project. | Number | 1.000 |
Publish Workflow
When a user clicks Publish in the Closed Caption Creator toolbar, the Work Order Publish workflow begins. Each track whose status is set to Publish is encoded using the specified publish profile and sent as an HTTP POST to the configured publishOptions.url. If auth is enabled on a publish destination, the user is first prompted to enter a username and password, which are transmitted alongside the file. After all tracks are delivered, the page redirects to the redirectUrl if one is configured. For review-mode work orders, a pass/fail report is posted instead of a caption file.
Troubleshooting
If media does not load after opening the Work Order link, confirm that CORS is correctly configured for the media source. Cloud storage buckets served from Amazon S3, Google Cloud Storage, or similar providers must allow cross-origin requests from app.closedcaptioncreator.com. Videos hosted on platforms that disable embedding will not be accessible through the file media type.
If the Work Order fails to import or shows an error on load, the most common cause is a malformed or incompletely URL-encoded JSON description. The entire JSON value of the description query parameter must be URL-encoded. Use a reliable encoding library or online tool to encode the JSON before appending it to the link, and verify that all required properties such as importOptions.url and importOptions.profile are present for each track.
If a publish attempt fails with an authentication error, confirm that the server receiving the POST request is accepting the credentials being submitted and that the auth property is set correctly on the relevant track's publish options.