Endpoint Group: Compression Options

Use the schema endpoints to discover what options a compressor accepts before submitting a job. Most image compressors support resize options, and PNG supports compression mode selection. PDF compression is fully automatic with no user-configurable options.

For human-readable documentation of each option with examples, see Options Reference. The schema endpoints below return the same information as machine-readable JSON Schema.

Endpoints

• GET /compress/schema — Full options schema covering every option across all compressors
• GET /compress/schema/{format} — Filtered schema with only the options that apply to a specific format's compressor

Auth

No authentication required. Schema endpoints are publicly accessible for discovery.

Path params

• format: file format (e.g. jpg, png, pdf)

Response

200 OK with content type application/schema+json. The response is a standard JSON Schema (draft 2020-12) document.

Example: image compressor with resize options (JPG)

GET /compress/schema/jpg

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$comment": "Options for jpg compression (job type: image.jpg-compress)",
  "properties": {
    "resize": {
      "type": "object",
      "description": "Resize image by pixels or percentage with presets (4K, 1080p, 720p, custom)",
      "properties": {
        "enabled": { "type": "boolean", "description": "Enable post-processing resize", "default": false },
        "mode": { "type": "string", "description": "Resize mode: 'pixels' targets longest edge, 'percentage' scales proportionally", "enum": ["pixels", "percentage"] },
        "preset": { "type": "string", "description": "Quick resize presets", "enum": ["off", "4k", "2k", "1080p", "720p", "custom"], "default": "off" },
        "value": { "type": "integer", "description": "Resize value: pixels mode (1-10000, longest edge), percentage mode (1-99)", "minimum": 1, "maximum": 10000 }
      }
    }
  },
  "additionalProperties": false
}

Example: PNG compressor with resize + compression mode

GET /compress/schema/png

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$comment": "Options for png compression (job type: image.png-compress)",
  "properties": {
    "resize": {
      "type": "object",
      "description": "Resize image by pixels or percentage with presets (4K, 1080p, 720p, custom)",
      "properties": {
        "enabled": { "type": "boolean", "description": "Enable post-processing resize", "default": false },
        "mode": { "type": "string", "description": "Resize mode: 'pixels' targets longest edge, 'percentage' scales proportionally", "enum": ["pixels", "percentage"] },
        "preset": { "type": "string", "description": "Quick resize presets", "enum": ["off", "4k", "2k", "1080p", "720p", "custom"], "default": "off" },
        "value": { "type": "integer", "description": "Resize value: pixels mode (1-10000, longest edge), percentage mode (1-99)", "minimum": 1, "maximum": 10000 }
      }
    },
    "compression": {
      "type": "object",
      "description": "Compression mode (lossy = smaller files via libimagequant, lossless = no quality loss via Oxipng)",
      "properties": {
        "enabled": { "type": "boolean", "description": "Enable compression mode selection (default mode is lossy)", "default": true },
        "mode": { "type": "string", "description": "Compression mode (lossy = smaller files, lossless = no quality loss)", "enum": ["lossy", "lossless"], "default": "lossy" }
      }
    }
  },
  "additionalProperties": false
}

Example: Office document compressor (DOCX, PPTX)

GET /compress/schema/docx

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$comment": "Options for docx compression (job type: document.office-compress)",
  "properties": {
    "resize": {
      "type": "object",
      "description": "Resize image by pixels or percentage with presets (4K, 1080p, 720p, custom)",
      "properties": {
        "enabled": { "type": "boolean", "description": "Enable post-processing resize", "default": false },
        "mode": { "type": "string", "description": "Resize mode: 'pixels' targets longest edge, 'percentage' scales proportionally", "enum": ["pixels", "percentage"] },
        "preset": { "type": "string", "description": "Quick resize presets", "enum": ["off", "4k", "2k", "1080p", "720p", "custom"], "default": "off" },
        "value": { "type": "integer", "description": "Resize value: pixels mode (1-10000, longest edge), percentage mode (1-99)", "minimum": 1, "maximum": 10000 }
      }
    }
  },
  "additionalProperties": false
}

Example: PDF compressor (no user options)

GET /compress/schema/pdf

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$comment": "Options for pdf compression (job type: document.pdf-compress)",
  "properties": {},
  "additionalProperties": false
}

Example: full schema (union of all options)

GET /compress/schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$comment": "Options for Compress.FAST compressors. Pass these in the 'options' form field as JSON.",
  "properties": {
    "resize": {
      "type": "object",
      "description": "Resize image by pixels or percentage with presets (4K, 1080p, 720p, custom)",
      "properties": {
        "enabled": { "type": "boolean", "description": "Enable post-processing resize", "default": false },
        "mode": { "type": "string", "description": "Resize mode: 'pixels' targets longest edge, 'percentage' scales proportionally", "enum": ["pixels", "percentage"] },
        "preset": { "type": "string", "description": "Quick resize presets", "enum": ["off", "4k", "2k", "1080p", "720p", "custom"], "default": "off" },
        "value": { "type": "integer", "description": "Resize value: pixels mode (1-10000, longest edge), percentage mode (1-99)", "minimum": 1, "maximum": 10000 }
      }
    },
    "compression": {
      "type": "object",
      "description": "Compression mode (lossy = smaller files via libimagequant, lossless = no quality loss via Oxipng)",
      "properties": {
        "enabled": { "type": "boolean", "description": "Enable compression mode selection (default mode is lossy)", "default": true },
        "mode": { "type": "string", "description": "Compression mode (lossy = smaller files, lossless = no quality loss)", "enum": ["lossy", "lossless"], "default": "lossy" }
      }
    }
  },
  "additionalProperties": false
}

Examples

# Full schema (all possible options)
curl -sS "https://api.tools.fast/compress/schema"

# Compressor-specific schema (only options that apply)
curl -sS "https://api.tools.fast/compress/schema/jpg"
curl -sS "https://api.tools.fast/compress/schema/png"
curl -sS "https://api.tools.fast/compress/schema/pdf"

# Unsupported format (returns 400)
curl -sS "https://api.tools.fast/compress/schema/mp3"

# Full schema (all possible options)
Invoke-RestMethod "https://api.tools.fast/compress/schema"

# Compressor-specific schema (only options that apply)
Invoke-RestMethod "https://api.tools.fast/compress/schema/jpg"
Invoke-RestMethod "https://api.tools.fast/compress/schema/png"
Invoke-RestMethod "https://api.tools.fast/compress/schema/pdf"

# Unsupported format (returns 400)
Invoke-RestMethod "https://api.tools.fast/compress/schema/mp3"

Error responses

400 Bad Request when the format is not supported.

Example: unsupported format

{
  "error": "schema.unsupported_format",
  "detail": "No compressor found for format 'mp3'.",
  "format": "mp3",
  "supportedFormats": ["avif", "bmp", "docx", "gif", "heic", "jpg", "pdf", "png", "pptx", "webp"]
}