File Fetch

The File Fetch endpoint allows you to submit a publicly accessible URL and let the Compressor API download the file on your behalf. This method is ideal when processing files already stored online — CDNs, cloud buckets, static assets, media libraries, user-hosted content, or external systems.

POST https://api.compressor.app/1.0/fetch

Unlike the Upload endpoint, Fetch accepts only JSON in the request body. All processing instructions, as well as the file URL, must be passed in a structured JSON payload. Your request must specify Content-Type: application/json.

Request Structure

A Fetch request includes:

• url — The publicly accessible URL pointing to the file you want to compress or transform
• headers (optional) — A map of custom HTTP request headers to include when we retrieve your file
• Additional processing parameters for compression, resizing, format conversion, extraction, and more

Example Request

curl https://api.compressor.app/1.0/fetch \
  -X POST \
  -u your-api-key: \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example.com/files/video.mp4",
    "video": {
      "resize": {
        "width": 1280,
        "height": 720,
        "mode": "fit"
      }
    }
  }'

This method is often significantly faster than uploading binary content, especially for large files, since only metadata and instructions are transmitted from your infrastructure.

Fetching Protected or Private Assets

If your files require HTTP Basic Authentication, you may embed credentials directly into the URL:

https://username:password@www.example.com/secure-video.mp4

Default Fetch Headers

When retrieving remote files, the Compressor API performs the outbound request using a small, predictable set of default HTTP headers. These headers are applied automatically to ensure broad compatibility across origins, CDNs, and storage providers.

By default, the following headers are included:

User-Agent: Compressor/1.0 (+https://compressor.app)
Accept: */*
Accept-Language: en-US,en;q=0.8
Cache-Control: no-cache
Pragma: no-cache

The User-Agent clearly identifies Compressor as the requesting service and includes a reference URL for transparency and troubleshooting. This makes it easier for origin servers to recognize, log, or allowlist fetch traffic.

Caching-related headers (Cache-Control and Pragma) instruct intermediaries to revalidate content with the origin, helping ensure that the most up-to-date version of a file is retrieved during processing.

Custom Fetch Headers

If your origin requires custom request headers you can override or extend the default behavior using the headers property in your request payload. Any headers you supply will be merged into the outbound fetch request.

This is useful for:

• Host header enforcement
• Signed URLs
• Token-based authentication
• Proprietary CDN rules
• Anti-bot or anti-hotlinking mechanisms

Example:

curl https://api.compressor.app/1.0/fetch \
  -X POST \
  -u your-api-key: \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.website.com/asset.jpg",
    "headers": {
      "host": "example.com",
      "x-api-token": "abc123",
      "x-my-custom-header": "true"
    },
    "image": {
      "resize": {
        "width": 640,
        "height": 480
      }
    }
  }'

Any custom headers provided will be included in the outbound fetch request made by Compressor.

Notes & Best Practices

• Always supply a valid, absolute URL including protocol.
• Avoid using ephemeral or short-lived signed URLs for long-running jobs unless using asynchronous mode.
• Use Fetch for remote assets; use Upload when working with local files or user uploads.
• Combine Fetch with External Storage Connectors to create fully automated ingestion → processing → storage pipelines.