### Local Development Setup

Source: https://context7.com/imputnet/cobalt/llms.txt

Instructions for setting up Cobalt for local development. This includes cloning the repository, installing dependencies, and starting the API server.

```bash
# Prerequisites: Node.js >= 18, pnpm, git
git clone https://github.com/imputnet/cobalt
cd cobalt/api

pnpm install

# Create .env file — API_URL is the only required variable
cat > .env <<EOF
API_URL=http://localhost:9000/
# API_PORT=9000
# COOKIE_PATH=./cookies.json
EOF

# Start the API
pnpm start

# Run service tests
pnpm test

# Generate a JWT secret
pnpm token:jwt
```

--------------------------------

### Install and Start nscd Service (Ubuntu)

Source: https://github.com/imputnet/cobalt/blob/main/docs/run-an-instance.md

On Ubuntu 22.04, install and start the nscd service to resolve DNS issues for the ffmpeg-static binary, as per issue #101.

```bash
sudo apt install nscd
sudo service nscd start
```

--------------------------------

### Example API Key File

Source: https://github.com/imputnet/cobalt/blob/main/docs/protect-an-instance.md

An example JSON-formatted API key file demonstrating configurations for rate limits, IP allowlists, and user agent restrictions.

```json
{
    "b5c7160a-b655-4c7a-b500-de839f094550": {
        "limit": 10,
        "ips": ["10.0.0.0/8", "192.168.42.42"],
        "userAgents": ["*Chrome*"]
    },
    "b00b1234-a3e5-99b1-c6d1-dba4512ae190": {
        "limit": "unlimited",
        "ips": ["192.168.1.2"],
        "userAgents": ["cobaltbot/1.0"]
    }
}
```

--------------------------------

### GET / - Instance Info

Source: https://context7.com/imputnet/cobalt/llms.txt

Returns metadata about the running cobalt instance, including version, supported services, start time, and git information. No authentication is required.

```APIDOC
## GET /

### Description
Returns metadata about the running cobalt instance: version, supported services, start time, and git info.

### Method
GET

### Endpoint
/

### Parameters
None

### Request Example
```bash
curl -s https://your.cobalt.instance/ | jq .
```

### Response
#### Success Response (200)
- **cobalt** (object) - Information about the Cobalt instance.
  - **version** (string) - The version of the Cobalt instance.
  - **url** (string) - The base URL of the Cobalt instance.
  - **startTime** (string) - The timestamp when the instance started.
  - **turnstileSitekey** (string, optional) - The Turnstile site key if configured.
  - **services** (array) - A list of supported services.
- **git** (object) - Git information about the build.
  - **commit** (string) - The git commit hash.
  - **branch** (string) - The git branch.
  - **remote** (string) - The git remote URL.

#### Response Example
```json
{
  "cobalt": {
    "version": "11.7.1",
    "url": "https://your.cobalt.instance/",
    "startTime": "1719700000000",
    "turnstileSitekey": "1x00000000000000000000BB",
    "services": ["youtube", "twitter", "tiktok", "instagram"]
  },
  "git": {
    "commit": "a52dde7",
    "branch": "main",
    "remote": "https://github.com/imputnet/cobalt"
  }
}
```
```

--------------------------------

### Start Cobalt API

Source: https://github.com/imputnet/cobalt/blob/main/docs/run-an-instance.md

Run the Cobalt API locally using the pnpm start command after setting up the environment variables.

```bash
pnpm start
```

--------------------------------

### Install API Dependencies

Source: https://github.com/imputnet/cobalt/blob/main/docs/run-an-instance.md

Install the necessary Node.js dependencies for the Cobalt API using pnpm.

```bash
pnpm install
```

--------------------------------

### API Key Authentication Example

Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md

Use this header format for API key authentication. Ensure the key is provided by the instance owner.

```http
Authorization: Api-Key aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
```

--------------------------------

### Prefill Download Link with URL Hash

Source: https://github.com/imputnet/cobalt/blob/main/web/README.md

Pass the URL in the `#` parameter to prefill the input box and start the download automatically. The link can also be URI-encoded.

```html
https://cobalt.tools/#https://www.youtube.com/watch?v=dQw4w9WgXcQ
```

```html
https://cobalt.tools/#https%3A//www.youtube.com/watch%3Fv=dQw4w9WgXcQ
```

--------------------------------

### Get Instance Info

Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md

Provides basic information about the Cobalt instance, including version, URL, and supported services.

```APIDOC
## GET /

### Description
Provides basic instance info.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
Body type: `application/json`
- **cobalt** (object) - Information about the cobalt instance.
  - **version** (string) - cobalt version.
  - **url** (string) - instance url.
  - **startTime** (string) - instance start time in unix milliseconds.
  - **turnstileSitekey** (string) - site key for a turnstile widget (optional).
  - **services** (string[]) - array of services which this instance supports.
- **git** (object) - information about the codebase that is currently running.
  - **commit** (string) - commit hash.
  - **branch** (string) - git branch.
  - **remote** (string) - git remote.
```

--------------------------------

### Download Audio Only (MP3)

Source: https://context7.com/imputnet/cobalt/llms.txt

This example demonstrates downloading only the audio from a SoundCloud track in MP3 format at 320kbps, with filename styling set to 'pretty'.

```bash
# Download audio only as MP3 at 320kbps with metadata
curl -s -X POST https://your.cobalt.instance/ \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://soundcloud.com/artist/track",
    "downloadMode": "audio",
    "audioFormat": "mp3",
    "audioBitrate": "320",
    "filenameStyle": "pretty"
  }' | jq .
```

--------------------------------

### Start Cobalt Docker Container

Source: https://github.com/imputnet/cobalt/blob/main/docs/run-an-instance.md

After configuring your docker-compose.yml, run this command to start the Cobalt container in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Download YouTube Video (AV1, MKV, Subtitles)

Source: https://context7.com/imputnet/cobalt/llms.txt

This example shows how to download a YouTube video using the AV1 codec and MKV container at maximum quality, with English subtitles embedded.

```bash
# Download YouTube video as AV1 in MKV at max quality with subtitles
curl -s -X POST https://your.cobalt.instance/ \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "videoQuality": "max",
    "youtubeVideoCodec": "av1",
    "youtubeVideoContainer": "mkv",
    "subtitleLang": "en"
  }' | jq .
```

--------------------------------

### Handle Twitter/X Multi-Image Post (Picker)

Source: https://context7.com/imputnet/cobalt/llms.txt

This example shows how to request a multi-image post from Twitter/X. The API returns a 'picker' array containing URLs and thumbnails for each image.

```bash
# Twitter/X multi-image post — returns picker
curl -s -X POST https://your.cobalt.instance/ \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://x.com/user/status/1234567890123456789"}' | jq .

# Picker response example:
# {
#   "status": "picker",
#   "picker": [
#     {"type": "photo", "url": "https://pbs.twimg.com/media/...", "thumb": "https://pbs.twimg.com/media/..."},
#     {"type": "photo", "url": "https://pbs.twimg.com/media/...", "thumb": "https://pbs.twimg.com/media/..."}
#   ]
# }
```

--------------------------------

### Download YouTube Video (Default)

Source: https://context7.com/imputnet/cobalt/llms.txt

This example shows the default behavior for downloading a YouTube video, resulting in an MP4 file with 1080p H.264 video. The response includes a tunnel URL and filename.

```bash
# Download a YouTube video at 1080p H.264 in MP4 (default behavior)
curl -s -X POST https://your.cobalt.instance/ \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}' | jq .

# Response (tunnel):
# {
#   "status": "tunnel",
#   "url": "https://your.cobalt.instance/tunnel?id=V1StGXR8...&exp=1719703600000&sig=abc123...&sec=xyz789...&iv=uvw456...",
#   "filename": "Rick Astley - Never Gonna Give You Up.mp4"
# }
```

--------------------------------

### Docker Compose Commands

Source: https://context7.com/imputnet/cobalt/llms.txt

Commands to manage the Cobalt Docker Compose instance. Use these to start the service and view logs.

```bash
# Start the instance
docker compose up -d
```

```bash
# View logs
docker compose logs -f cobalt
```

--------------------------------

### Bearer Token Authentication Example

Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md

Use this header format for Bearer token authentication, typically obtained after solving a challenge like Turnstile.

```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

--------------------------------

### Get Cobalt Instance Info

Source: https://context7.com/imputnet/cobalt/llms.txt

Use this endpoint to retrieve metadata about the running Cobalt instance, including version, supported services, and git information. No authentication is required.

```bash
curl -s https://your.cobalt.instance/ | jq .

# Expected response:
# {
#   "cobalt": {
#     "version": "11.7.1",
#     "url": "https://your.cobalt.instance/",
#     "startTime": "1719700000000",
#     "turnstileSitekey": "1x00000000000000000000BB",   // only if turnstile is configured
#     "services": ["youtube", "twitter", "tiktok", "instagram", ...]
#   },
#   "git": {
#     "commit": "a52dde7",
#     "branch": "main",
#     "remote": "https://github.com/imputnet/cobalt"
#   }
# }
```

--------------------------------

### Download TikTok Video (No Watermark, Full Audio)

Source: https://context7.com/imputnet/cobalt/llms.txt

This example demonstrates downloading a TikTok video without a watermark and including the original full audio. It also enables H.265 support.

```bash
# TikTok: download without watermark, include original full audio
curl -s -X POST https://your.cobalt.instance/ \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.tiktok.com/@user/video/1234567890",
    "tiktokFullAudio": true,
    "allowH265": true
  }' | jq .
```

--------------------------------

### Create and Configure .env File

Source: https://github.com/imputnet/cobalt/blob/main/docs/run-an-instance.md

Create a .env file in the API directory and add the required API_URL environment variable for local development.

```bash
# Example .env file content:
API_URL=http://localhost:9000/
```

--------------------------------

### GET /tunnel

Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md

Retrieves a file stream for tunnels (proxy/remux/transcode). Errors are reported via HTTP status codes.

```APIDOC
## GET /tunnel

### Description
Endpoint for file tunnels (proxy/remux/transcode). The response is a file stream. All errors are reported via HTTP status codes.

### Returned Headers
- `Content-Length`: file size, in bytes. Returned when exact final file size is known.
- `Estimated-Content-Length`: estimated file size, in bytes. Returned when real `Content-Length` is not known. A rough estimate which should NOT be used for strict size verification. Can be used to show approximate download progress in UI.

### Possible HTTP Status Codes
- 200: OK
- 401: Unauthorized
- 403: Bad Request
- 404: Not Found
- 429: Too Many Requests (rate limit exceeded, check [RateLimit-* headers](https://www.ietf.org/archive/id/draft-polli-ratelimit-headers-02.html#name-header-specifications))
- 500: Internal Server Error.
```

--------------------------------

### Generate a UUIDv4

Source: https://github.com/imputnet/cobalt/blob/main/docs/protect-an-instance.md

Command to generate a new UUIDv4 using Node.js, which should be used instead of example UUIDs when creating your API key file.

```bash
node -e "console.log(crypto.randomUUID())"
```

--------------------------------

### Create Docker Compose Configuration File

Source: https://github.com/imputnet/cobalt/blob/main/docs/run-an-instance.md

Navigate to the Cobalt directory and create the docker-compose.yml file using your preferred text editor.

```bash
cd cobalt && nano docker-compose.yml
```

--------------------------------

### Configure Turnstile in Docker Compose

Source: https://github.com/imputnet/cobalt/blob/main/docs/protect-an-instance.md

Add TURNSTILE_SITEKEY and TURNSTILE_SECRET environment variables to your docker-compose.yml file. Ensure you use your own generated keys and not the example values.

```yaml
environment:
    API_URL: "https://your.instance.url.here.local/"
    TURNSTILE_SITEKEY: "2x00000000000000000000BB" # use your key
    TURNSTILE_SECRET: "2x0000000000000000000000000000000AA" # use your key
```

--------------------------------

### Navigate to Cobalt API Directory

Source: https://github.com/imputnet/cobalt/blob/main/docs/run-an-instance.md

Change your current directory to the 'api' subdirectory within the cloned Cobalt repository.

```bash
cd cobalt/api
```

--------------------------------

### Create Cobalt Configuration Directory

Source: https://github.com/imputnet/cobalt/blob/main/docs/run-an-instance.md

Use this command to create a dedicated directory for your Cobalt configuration files.

```bash
mkdir cobalt
```

--------------------------------

### Configure API Key File Path

Source: https://github.com/imputnet/cobalt/blob/main/docs/protect-an-instance.md

Add the API_KEY_URL environment variable to your docker-compose.yml to specify the path to your keys.json file. This example uses a file path.

```yaml
environment:
    # ... other variables here ...
    API_KEY_URL: "file:///keys.json"
```

--------------------------------

### POST /

Source: https://github.com/imputnet/cobalt/blob/main/docs/api.md

Cobalt's main processing endpoint. Requires `Accept` and `Content-Type` headers set to `application/json`.

```APIDOC
## POST /

### Description
Cobalt's main processing endpoint.

> [!IMPORTANT]
> you must include correct `Accept` and `Content-Type` headers with every `POST /` request.
```
Accept: application/json
Content-Type: application/json
```

### Request Body
body type: `application/json`

#### Parameters
| key               | type      | description/value                                               | default    |
|:------------------|:----------|:----------------------------------------------------------------|:-----------|
| `url`             | `string`  | source URL                                                      | *required* |
| `audioBitrate`    | `string`  | `320 / 256 / 128 / 96 / 64 / 8` (kbps)                          | `128`      |
| `audioFormat`     | `string`  | `best / mp3 / ogg / wav / opus`                                 | `mp3`      |
| `downloadMode`    | `string`  | `auto / audio / mute`                                           | `auto`     |
| `filenameStyle`   | `string`  | `classic / pretty / basic / nerdy`                              | `basic`    |
| `videoQuality`    | `string`  | `max / 4320 / 2160 / 1440 / 1080 / 720 / 480 / 360 / 240 / 144` | `1080`     |
| `disableMetadata` | `boolean` | title, artist, and other info will not be added to the file     | `false`    |
| `alwaysProxy`     | `boolean` | always tunnel all files, even when not necessary                | `false`    |
| `localProcessing` | `string`  | `disabled / preferred / forced`                                 | `disabled` |
| `subtitleLang`    | `string`  | any valid ISO 639-1 language code                               | *none*     |
```

--------------------------------

### Docker Compose Deployment Configuration

Source: https://context7.com/imputnet/cobalt/llms.txt

Configuration for deploying Cobalt using Docker Compose. This setup includes auto-updates via Watchtower and port mapping for reverse proxy access.

```yaml
# docker-compose.yml
services:
    cobalt:
        image: ghcr.io/imputnet/cobalt:11

        init: true
        read_only: true
        restart: unless-stopped
        container_name: cobalt

        ports:
            - 127.0.0.1:9000:9000  # use with a reverse proxy

        environment:
            API_URL: "https://api.your-domain.com/"

            # Optional: cookie auth for Instagram, Reddit, Twitter, YouTube, Vimeo
            # COOKIE_PATH: "/cookies.json"

            # Optional: bot protection
            # TURNSTILE_SITEKEY: "1x00000000000000000000BB"
            # TURNSTILE_SECRET: "1x0000000000000000000000000000000AA"
            # JWT_SECRET: "your-random-64-char-secret-here"

            # Optional: API key auth
            # API_KEY_URL: "file:///keys.json"
            # API_AUTH_REQUIRED: "1"

            # Optional: Redis for multi-instance / shared rate limiting
            # API_REDIS_URL: "redis://redis:6379"
            # API_INSTANCE_COUNT: "4"

            # Optional: limits
            # DURATION_LIMIT: "10800"      # max video duration in seconds (default: 3h)
            # RATELIMIT_WINDOW: "60"        # rate limit window in seconds
            # RATELIMIT_MAX: "20"           # max requests per window

        # volumes:
        #     - ./cookies.json:/cookies.json:ro
        #     - ./keys.json:/keys.json:ro

        labels:
            - com.centurylinklabs.watchtower.scope=cobalt

    watchtower:
        image: ghcr.io/containrrr/watchtower
        restart: unless-stopped
        command: --cleanup --scope cobalt --interval 900 --include-restarting
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
```

--------------------------------

### POST / - Main API Endpoint

Source: https://context7.com/imputnet/cobalt/llms.txt

Initiates a download or conversion process. Accepts either an API key or a Bearer JWT token for authentication. The response typically contains a URL for the file stream.

```APIDOC
## POST /

### Description
Initiates a download or conversion task for a given URL.

### Method
POST

### Endpoint
/

### Parameters
#### Request Body
- **url** (string) - Required - The URL of the media to process.
- **downloadMode** (string) - Optional - Specifies the download mode (e.g., "audio").

### Authentication
Requires either an `Authorization: Api-Key <key>` header or an `Authorization: Bearer <token>` header.

### Request Example (API Key)
```bash
curl -s -X POST https://your.cobalt.instance/ \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Api-Key b5c7160a-b655-4c7a-b500-de839f094550" \
  -d '{"url": "https://vimeo.com/123456789", "downloadMode": "audio"}' | jq .
```

### Request Example (Bearer JWT)
```bash
curl -s -X POST https://your.cobalt.instance/ \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{"url": "https://www.reddit.com/r/aww/comments/xyz/"}' | jq .
```

### Response
#### Success Response (200)
- The response structure may vary, but typically includes information to access the processed file, potentially including a tunnel URL.

#### Response Example (Illustrative)
```json
{
  "url": "https://your.cobalt.instance/tunnel?id=...&exp=...&sig=...&sec=...&iv=..."
}
```
```