# Closed Caption Converter API

> Closed Caption Converter is a REST API for converting, conforming, QCing, translating, transcribing and delivering closed caption and subtitle files in over 30 formats.

- Base URL: `https://api.closedcaptionconverter.com`
- Auth: every `/jobs` request needs both headers `x-api-key: <API key>` and `username: <account email>`. Keep the key server-side.
- Submit a job: `POST /jobs` as `multipart/form-data` with `source` (file upload or public HTTPS URL) and `config` (Job Description as a JSON string), or as `application/json` where the body is the Job Description with a `source` URL.
- The response is JSON `{ id, target, status, statusMsg, qcReport, progress }`. The output file is downloaded from the signed URL in `target`; it is not embedded in the response.
- If `status` is `queued` or `in progress` (transcription, alignment, very large jobs), poll `GET /jobs/{id}` until `status` is `passed` or `failed`.
- Profile names must match exactly. Get the valid lists from `GET /help/profiles/source` and `GET /help/profiles/target` (no auth). `GET /help/schemas/job` returns a Job Description with all defaults.
- Errors are plain-text bodies with HTTP 400, 401, 404, 429 or 500.

## Docs

- [API Getting Started](https://www.closedcaptionconverter.com/docs/api/getting-started.md): Base URL, authentication headers, endpoints, request formats, job response, polling and errors.
- [Job Types & Descriptions](https://www.closedcaptionconverter.com/docs/api/job-types-descriptions.md): The Job Description JSON object: every field and each job type (convert, qc, translate, transcribe, align, deliver).
- [Example Job Description](https://www.closedcaptionconverter.com/docs/example-job-description.md): A complete Job Description with every option populated.
- [Job Presets](https://www.closedcaptionconverter.com/docs/api/presets.md): Saving Job Descriptions as presets and submitting jobs with preset_id.
- [API — Access Providers](https://www.closedcaptionconverter.com/docs/api/access-providers.md): Using cloud storage, transcription and translation providers in jobs, and delivery_options.
- [Job Status Dashboard](https://www.closedcaptionconverter.com/docs/api/job-history-dashboard.md): Job statuses and the job history dashboard.

## Optional

- [Closed Caption Profiles & Formats](https://www.closedcaptionconverter.com/docs/profiles-formats.md): Supported caption formats and their exact profile names.
- [Filters](https://www.closedcaptionconverter.com/docs/filters.md): Filters available in a Job Description: Auto Format, timing, event gap, search & replace, segmentation & conform, QC.
- [Encoding & Decoding Options](https://www.closedcaptionconverter.com/docs/encoding-decoding-options.md): Format-specific encoding_options and decoding_options, and metadata passthrough.
- [Full documentation](https://www.closedcaptionconverter.com/docs/llms-full.txt): All of the pages above in a single file.
- [Compact documentation](https://www.closedcaptionconverter.com/docs/llms-small.txt): Core API pages only, for smaller context windows.