cobalt api documentation

this document provides info about methods and acceptable variables for all cobalt api requests.

if you are looking for the documentation for the old (7.x) api, you can find it here

POST: `/`

cobalt's main processing endpoint.

request body type: application/json response body type: application/json

⚠️ you must include Accept and Content-Type headers with every `POST /` request.

Accept: application/json
Content-Type: application/json

key	type	expected value(s)	default	description
`url`	`string`	URL to download	--	must be included in every request.
`videoQuality`	`string`	`144 / ... / 2160 / 4320 / max`	`1080`	`720` quality is recommended for phones.
`audioFormat`	`string`	`best / mp3 / ogg / wav / opus`	`mp3`
`audioBitrate`	`string`	`320 / 256 / 128 / 96 / 64 / 8`	`128`	specifies the bitrate to use for the audio. applies only to audio conversion.
`filenameStyle`	`string`	`classic / pretty / basic / nerdy`	`classic`	changes the way files are named. previews can be seen in the web app.
`downloadMode`	`string`	`auto / audio / mute`	`auto`	`audio` downloads only the audio, `mute` skips the audio track in videos.
`youtubeVideoCodec`	`string`	`h264 / av1 / vp9`	`h264`	`h264` is recommended for phones.
`youtubeDubLang`	`string`	`en / ru / cs / ja / ...`	--	specifies the language of audio to download, when the youtube video is dubbed
`youtubeDubBrowserLang`	`boolean`	`true / false`	`false`	uses value from the Accept-Language header for `youtubeDubLang`.
`alwaysProxy`	`boolean`	`true / false`	`false`	tunnels all downloads through the processing server, even when not necessary.
`disableMetadata`	`boolean`	`true / false`	`false`	disables file metadata when set to `true`.
`tiktokFullAudio`	`boolean`	`true / false`	`false`	enables download of original sound used in a tiktok video.
`tiktokH265`	`boolean`	`true / false`	`false`	changes whether 1080p h265 videos are preferred or not.
`twitterGif`	`boolean`	`true / false`	`true`	changes whether twitter gifs are converted to .gif

the response will always be a JSON object containing the status key, which will be one of:

key	type	values
`status`	`string`	`tunnel / redirect`
`url`	`string`	url for the cobalt tunnel, or redirect to an external link
`filename`	`string`	cobalt-generated filename for the file being downloaded

key	type	values
`status`	`string`	`picker`
`audio`	`string`	optional returned when an image slideshow (such as on tiktok) has a general background audio
`audioFilename`	`string`	optional cobalt-generated filename, returned if `audio` exists
`picker`	`array`	array of objects containing the individual media

key	type	values
`status`	`string`	`error`
`error`	`object`	contains more context about the error

key	type	values
`code`	`string`	machine-readable error code explaining the failure reason
`context`	`object`	optional container for providing more context

key	type	values
`service`	`string`	optional, stating which service was being downloaded from
`limit`	`number`	optional number providing the ratelimit maximum number of requests, or maximum downloadable video duration

returns current basic server info. response body type: application/json

key	type	variables
`cobalt`	`object`	information about the cobalt instance
`git`	`object`	information about the codebase that is currently running

key	type	description
`version`	`string`	current version
`url`	`string`	server url
`startTime`	`string`	server start time in unix milliseconds
`durationLimit`	`number`	maximum downloadable video length in seconds
`services`	`string[]`	array of services which this instance supports