> ## Documentation Index
> Fetch the complete documentation index at: https://docs.curtly.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /compress

> HTTP endpoint for prompt and context compression.

<div className="flex items-center gap-2 mb-6">
  <span className="px-2.5 py-1 rounded-md bg-blue-600 text-white font-mono text-xs font-bold uppercase">POST</span>
  <code className="text-lg font-semibold text-slate-100 font-mono">/api/v1/compress</code>
</div>

Executes deterministic compression on the input string and returns the optimized text along with token economics and latency metrics.

***

## Authentication

Include your secret API key as a Bearer token in the `Authorization` header, or via the `X-Curtly-Key` header:

```http theme={"dark"}
Authorization: Bearer ctly_live_your_api_key_here
```

***

## Request Parameters

<ParamField body="prompt" type="string" required>
  The raw text prompt or context window to compress. Maximum allowed length is **50,000 characters**.
</ParamField>

<ParamField body="mode" default="balanced" type="string">
  Compression intensity level:

  * `conservative`: \~20% – 35% reduction (formatting cleanup and preamble pruning)
  * `balanced`: \~40% – 55% reduction (standard production default)
  * `aggressive`: \~55% – 75% reduction (deep density pruning)
</ParamField>

<ParamField body="protectCodeBlocks" default="true" type="boolean">
  When `true`, isolates and protects fenced code blocks and inline backticks.
</ParamField>

<ParamField body="protectJson" default="true" type="boolean">
  When `true`, isolates and preserves valid JSON structures intact.
</ParamField>

<ParamField body="protectVariables" default="true" type="boolean">
  When `true`, isolates template tags and mustache variables (`{{var}}`).
</ParamField>

***

## Response Fields

<ResponseField name="success" type="boolean">
  Whether the request was processed successfully.
</ResponseField>

<ResponseField name="compressed" type="string">
  The compressed output string.
</ResponseField>

<ResponseField name="stats" type="object">
  Execution metrics:

  <Expandable title="stats properties">
    <ResponseField name="originalTokens" type="number">
      Token count of the input string before compression.
    </ResponseField>

    <ResponseField name="finalTokens" type="number">
      Token count of the compressed output.
    </ResponseField>

    <ResponseField name="savedTokens" type="number">
      Number of tokens pruned by the engine.
    </ResponseField>

    <ResponseField name="savedPercent" type="number">
      Percentage of tokens saved.
    </ResponseField>

    <ResponseField name="latencyMs" type="number">
      In-memory processing latency in milliseconds.
    </ResponseField>

    <ResponseField name="tokenizerUsed" type="string">
      Tokenizer reference utilized for token estimation (`cl100k_base` / `o200k_base`).
    </ResponseField>

    <ResponseField name="integrityPassed" type="boolean">
      Verification status confirming all Safe Vault tokens were restored correctly.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Example

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST https://curtly.dev/api/v1/compress \
    -H "Authorization: Bearer ctly_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "You are a customer support engineer. Please note that you must return valid JSON: {\"ticket_id\": 104}",
      "mode": "balanced"
    }'
  ```

  ```json Response (200 OK) theme={"dark"}
  {
    "success": true,
    "compressed": "Role: customer support engineer. Return valid JSON: {\"ticket_id\": 104}",
    "stats": {
      "originalTokens": 22,
      "finalTokens": 11,
      "savedTokens": 11,
      "savedPercent": 50.0,
      "latencyMs": 1.54,
      "tokenizerUsed": "cl100k_base",
      "integrityPassed": true
    }
  }
  ```
</CodeGroup>

***

## HTTP Status Codes

| Status Code             | Reason                                 | Resolution                                                                           |
| :---------------------- | :------------------------------------- | :----------------------------------------------------------------------------------- |
| `200 OK`                | Request processed successfully.        | Use `compressed` text in downstream pipeline.                                        |
| `400 Bad Request`       | Missing or invalid `prompt` parameter. | Ensure `prompt` is a string within size bounds.                                      |
| `401 Unauthorized`      | Missing, invalid, or expired API key.  | Verify credentials in the [Dashboard](https://curtly.dev/dashboard?tab=keys).        |
| `403 Forbidden`         | API key lacks required scope.          | Ensure key has `full` or `compress_only` permissions.                                |
| `429 Too Many Requests` | Rate limit or monthly quota exceeded.  | Check quota status on the [Balances tab](https://curtly.dev/dashboard?tab=balances). |