POST /compress

POST/api/v1/compress

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:

Authorization: Bearer ctly_live_your_api_key_here

Request Parameters

string

required

The raw text prompt or context window to compress. Maximum allowed length is 50,000 characters.

string

default:"balanced"

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)

boolean

default:"true"

When true, isolates and protects fenced code blocks and inline backticks.

boolean

default:"true"

When true, isolates and preserves valid JSON structures intact.

boolean

default:"true"

When true, isolates template tags and mustache variables ({{var}}).

Response Fields

boolean

Whether the request was processed successfully.

string

The compressed output string.

object

Execution metrics:

Show stats properties

number

Token count of the input string before compression.

number

Token count of the compressed output.

number

Number of tokens pruned by the engine.

number

Percentage of tokens saved.

number

In-memory processing latency in milliseconds.

string

Tokenizer reference utilized for token estimation (cl100k_base / o200k_base).

boolean

Verification status confirming all Safe Vault tokens were restored correctly.

Example

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"
  }'

{
  "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
  }
}

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.
`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.

Getting Started

Architecture

API Reference

Integrations

Security & Access

POST /compress

Authentication

Request Parameters

Response Fields

Example

HTTP Status Codes

​Authentication

​Request Parameters

​Response Fields

​Example

​HTTP Status Codes

Authentication

Request Parameters

Response Fields

Example

HTTP Status Codes