# https://compresr.ai/docs/api-reference/compress-qs

> Human-readable page: https://compresr.ai/docs/api-reference/compress-qs

`POST /api/compress/question-specific/`

Supply a long `context` and a `query`; the model keeps the parts of the context that matter for that query and drops the rest. This is the headline Compresr endpoint.

## Request body

`latte_v2` accepts every parameter `latte_v1` accepts, **plus** three `latte_v2`-only knobs for dynamic compression-ratio selection. The shared parameters apply identically on both models; the `latte_v2`-only knobs are rejected with `422` if sent to `latte_v1`. See [Models](/docs/api-reference/models) for the canonical reference and decision guide.

### Shared parameters (both models)

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `context` | string | yes | The text to compress. Pass null or an empty string to get an empty result back with no billing. |
| `query` | string | yes | The question or topic to preserve relevance for. Cannot be empty. |
| `compression_model_name` | "latte_v1" \| "latte_v2" | yes | Routes the call. `{{DEFAULT_MODEL}}` is the recommended default; pick `latte_v1` when you need the older backbone explicitly. See [Models](/docs/api-reference/models). |
| `target_compression_ratio` | number | no | Compression strength. Removal fraction when `0 < r ≤ 1`, Nx target when `r > 1`. See [Models › target_compression_ratio](/docs/api-reference/models#target_compression_ratio). Ignored on `latte_v2` when `dynamic=true`. |
| `coarse` | boolean | no | Paragraph-level compression. Faster and cheaper, less precise than token-level. |
| `heuristic_chunking` | boolean | no | Pre-chunk the context with structure-aware heuristics (paragraphs, code blocks, markdown sections) before scoring. |
| `disable_placeholders` | boolean | no | Drop the `[...]` markers the model normally inserts between kept spans. |

### `latte_v2`-only parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `dynamic` | boolean | no | Pick the compression ratio per-input automatically inside `[dynamic_min_ratio, dynamic_max_ratio]`. Overrides `target_compression_ratio` when `true`. Rejected on `latte_v1` with `422`. |
| `dynamic_min_ratio` | number | no | Floor on the chosen Nx ratio when `dynamic=true`. Must be `≥ 1.0`. Only consulted when `dynamic=true`. |
| `dynamic_max_ratio` | number | no | Ceiling on the chosen Nx ratio when `dynamic=true`. Must be `≥ 1.0` and `≥ dynamic_min_ratio`. Only consulted when `dynamic=true`. |

## Response

| Field | Type | Description |
| --- | --- | --- |
| `success` | boolean | true on success. |
| `data` | object |  |
| `data.original_context` | string | The input context, echoed back. |
| `data.compressed_context` | string | The compressed output you forward to your LLM. |
| `data.original_tokens` | integer | Token count of the input context. |
| `data.compressed_tokens` | integer | Token count after compression. |
| `data.tokens_saved` | integer | original_tokens − compressed_tokens. |
| `data.target_compression_ratio` | number \| null | The ratio you requested, if any. |
| `data.actual_compression_ratio` | number | The ratio actually achieved (0 to 1). |
| `data.duration_ms` | integer | Server-side processing time in milliseconds. |

## Status codes

| Status | Description |
| --- | --- |
| 200 | Compression succeeded. |
| 400 | Malformed JSON body. |
| 401 | Missing or invalid `X-API-Key`. |
| 422 | A field failed validation (e.g. empty `query`, `target_compression_ratio > 200`). |
| 429 | Rate limit hit for your tier. |
| 500 | Upstream compression service error. |
| 503 | Upstream compression service error. |

```python
import os
from compresr import CompressionClient

client = CompressionClient(api_key=os.environ["COMPRESR_API_KEY"])

result = client.compress(
    context=(
        "The James Webb Space Telescope (JWST) is a space telescope designed "
        "primarily to conduct infrared astronomy. As the most powerful telescope "
        "ever launched, its 6.5-metre primary mirror is composed of 18 gold-coated "
        "hexagonal beryllium segments. It orbits the Sun near the Sun-Earth L2 "
        "Lagrange point, about 1.5 million kilometres from Earth."
    ),
    query="What is the diameter of JWST's primary mirror?",
    compression_model_name="{{DEFAULT_MODEL}}",
    target_compression_ratio=0.5,
)

print(result.data.compressed_context)
```

**TypeScript**

```typescript
import { CompressionClient } from '@compresr/sdk';

const client = new CompressionClient({
  apiKey: process.env.COMPRESR_API_KEY!,
});

const result = await client.compress({
  context:
    'The James Webb Space Telescope (JWST) is a space telescope ' +
    'designed primarily to conduct infrared astronomy. Its 6.5-metre ' +
    'primary mirror is composed of 18 gold-coated hexagonal beryllium ' +
    'segments. It orbits near the Sun-Earth L2 Lagrange point.',
  query: "What is the diameter of JWST's primary mirror?",
  compressionModelName: '{{DEFAULT_MODEL}}',
  targetCompressionRatio: 0.5,
});

console.log(result.data.compressed_context);
```

**cURL**

```bash
curl -X POST https://api.compresr.ai/api/compress/question-specific/ \
  -H "X-API-Key: $COMPRESR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "context": "The James Webb Space Telescope (JWST) ...",
    "query": "What is the diameter of JWST'"'"'s primary mirror?",
    "compression_model_name": "{{DEFAULT_MODEL}}",
    "target_compression_ratio": 0.5
  }'
```

  response={

```json
{
  "success": true,
  "data": {
    "original_context": "The James Webb Space Telescope ...",
    "compressed_context": "JWST's 6.5-metre primary mirror is composed of 18 gold-coated hexagonal beryllium segments.",
    "original_tokens": 78,
    "compressed_tokens": 21,
    "tokens_saved": 57,
    "target_compression_ratio": 0.5,
    "actual_compression_ratio": 0.27,
    "duration_ms": 412
  }
}
```