> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Compressions

> Call compression models on Gateway with POST /v1/compressions: send a context and the prompt it's for, get back a shorter context, and pay the next model for fewer input tokens.

Compression models shorten a long context, such as a contract, a knowledge base article, or retrieved documents, down to the parts that matter for one prompt. Use them before an expensive chat model when input tokens drive your cost, or when a context won't fit the next model's window. A compression costs a fraction of the input tokens it saves on a frontier model.

> **Not the same as context compression**
>
> [Context compression](/merge-gateway/cost/context-compression) is a setting that shrinks chat requests automatically. This endpoint is an explicit call you make, and you decide what to send next.

## Send a compression request

Send `context`, the text to shorten, and `prompt`, the question it's being shortened for. Both are required and can't be blank.

**`cURL`**

```bash title="cURL"
curl https://api-gateway.merge.dev/v1/compressions \
  -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "scaledown/compress",
    "context": "Northwind Supply'\''s master services agreement with Acme Corp was signed on 2025-03-01 and runs for three years. It covers pallet delivery to Acme'\''s warehouses in Chicago, Denver, and Atlanta, with a minimum of 40 pallets per month. Prices are fixed for the first year and then rise with the producer price index, capped at 4% per year. Invoices are due net 30 from the issue date. Late payments accrue 1.5% interest per month after a 10-day grace period, and Northwind may pause deliveries once an invoice is 45 days overdue. Disputed line items must be raised in writing within 15 days of the invoice; undisputed amounts stay due on the original date. Either party can terminate with 60 days'\'' written notice, or immediately for a material breach left uncured for 30 days. Disputes that can'\''t be settled by the account managers go to binding arbitration in Chicago under AAA commercial rules. Insurance: Northwind carries $5M in cargo coverage per shipment.",
    "prompt": "When is an invoice late, and what does lateness cost Acme?"
  }'
```

**`Python`**

```python title="Python"
import os, requests

headers = {"Authorization": f"Bearer {os.environ['MERGE_GATEWAY_API_KEY']}"}
prompt = "When is an invoice late, and what does lateness cost Acme?"
contract = open("northwind-msa.txt").read()

compressed = requests.post(
    "https://api-gateway.merge.dev/v1/compressions",
    headers=headers,
    json={"model": "scaledown/compress", "context": contract, "prompt": prompt},
).json()
print(compressed["original_tokens"], "->", compressed["compressed_tokens"])

answer = requests.post(
    "https://api-gateway.merge.dev/v1/chat/completions",
    headers=headers,
    json={
        "model": "anthropic/claude-sonnet-5-5",
        "messages": [
            {"role": "user", "content": f"{compressed['compressed_prompt']}\n\n{prompt}"},
        ],
    },
).json()
print(answer["choices"][0]["message"]["content"])
```

The cURL request returns:

```json
{
  "object": "compression",
  "model": "compress",
  "vendor": "scaledown",
  "compressed_prompt": "Prices are fixed for the first year and then rise with the producer price index, capped at 4% per year. Invoices are due net 30 from the issue date. Late payments accrue 1.5% interest per month after a 10-day grace period, and Northwind may pause deliveries once an invoice is 45 days overdue.\n\nLate payments accrue 1.5% interest per month after a 10-day grace period, and Northwind may pause deliveries once an invoice is 45 days overdue. Disputed line items must be raised in writing within 15 days of the invoice; undisputed amounts stay due on the original date.",
  "original_tokens": 273,
  "compressed_tokens": 131,
  "compression_ratio": 0.48,
  "usage": {"input_tokens": 273, "output_tokens": 0, "total_tokens": 273, "cost": 1.365e-05}
}
```

`compressed_prompt` holds the parts of `context` relevant to `prompt`, not the prompt itself, so send both to the next model. `compression_ratio` is `compressed_tokens` divided by `original_tokens`. The text can repeat sentences and change their order, so use it as model input, not as text to show a person.

## Reference

| Field      | Notes                                                                                                                   |
| ---------- | ----------------------------------------------------------------------------------------------------------------------- |
| `model`    | Required. A compression model, such as `scaledown/compress`. Gateway `@alias/...` IDs return `400 alias_not_supported`. |
| `context`  | Required. The text to shorten.                                                                                          |
| `prompt`   | Required. The question or instruction the context is being shortened for.                                               |
| `rate`     | `auto` (the default), or the share of tokens to remove, between 0 and 1                                                 |
| `vendor`   | Pin the execution vendor. A mismatch returns `400 vendor_unavailable`.                                                  |
| `customer` | [Customer](/merge-gateway/embedded-routing-stack/customers) UUID to scope the key, budget, and usage to                 |

| Limit or error                                                           | Value                                                                   |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| Unknown fields, such as `stream`                                         | `422`, rather than being ignored                                        |
| Blank `context` or `prompt`, or `rate` outside 0 to 1                    | `422` before any vendor call                                            |
| A compression model sent to another endpoint, or another model sent here | `400 unsupported_endpoint_for_model`, naming the endpoint to use        |
| [DLP](/merge-gateway/security/data-loss-prevention) match                | `422 blocked_by_dlp_policy`, including for organizations in redact mode |

`scaledown/compress` bills the original tokens as input at \$0.05 per million, with no output cost, reported as `usage.cost` in USD. It doesn't stream, and it isn't available to organizations with [zero data retention](/merge-gateway/security/zero-data-retention). `GET /v1/models` lists it among the ScaleDown models, paged at 50 by default, so pass `limit` (up to 500) when you search.

## Next steps

#### [Context compression](/merge-gateway/cost/context-compression)

Shrink long chat requests automatically, with no extra call

#### [Prompt caching](/merge-gateway/capabilities/prompt-caching)

Cut the cost of a context you send again and again