POST /v1/compress

The single business endpoint: https://macs.nanotoll.dev/v1/compress. Authenticated with your Bearer token, billed per call before processing (see billing).

Request

{
  "text": "Context windows are finite. An agent that reads a large document pays for every token twice: once to read it and once to keep it in memory. Compression reduces the second cost, but only a measured compression is safe to act on. A receipt makes it measurable.",
  "squeeze_mode": "verified",
  "target_ratio": 0.7
}

• text (required) - the input to compress. Size limits are enforced before billing; oversized payloads get HTTP 413. Model modes are capped in tokens (see max_input_tokens in GET /v1/limits), because model cost tracks tokens rather than characters: the same 40,000 characters measured 9,775-12,020 tokens across real documents.
• squeeze_mode (required) - deterministic, extractive, or verified (see the ladder).
• target_ratio (optional) - a hint, not a guarantee. The receipt discloses the realized ratio. Guidance is measured, not aspirational: 0.7 is the low-risk default for fact-dense text. Treat the value as a target, not a floor: on large inputs (tens of thousands of characters) a call can finish marginally below it, and the receipt reports what was actually achieved.

The call is stateless: no session state, no cross-call memory, no query conditioning. Input plus parameters fully determine output plus receipt.

Response

The example below is a real response, captured from the production service for the request above. Every hash and the signature are genuine: the signature verifies against the published key (verification), and integrity.output_sha256 is the SHA-256 of the compressed string.

{
  "compressed": "Context windows finite. agent reads large document pays every token twice: once read once keep memory. Compression reduces second cost, only measured compression safe. receipt makes measurable.",
  "receipt": {
    "headline": {
      "squeeze_mode": "verified",
      "ratio": 0.7481
    },
    "integrity": {
      "raw_sha256": "4b77f0c3775f53b18f1aad60d1442b43c12812f43dfb046557c1376d1987850e",
      "output_sha256": "9a0bd5cc89a3415739a4054084c91bf8585cc52d538a3cce3190fcfd568f1ea3",
      "output_is_subsequence": true
    },
    "quality": {
      "fidelity_score": 0.9766278862953186,
      "min_window_posterior": 0.9478115439414978,
      "coverage_fraction": 1.0
    },
    "counts": {
      "kept_span_count": 18,
      "pins_protected": { "MODALITY": 4 },
      "windows_total": 4,
      "exact_matches": 0,
      "windows_below_threshold": 0
    },
    "debug": {
      "model_registry": {
        "nli_q8": "9a83251a7d2ad82cd11172ba53ff240f26bf2c1038299787c082c3106e02b5b0",
        "llmlingua_tokenizer": "3a56def25aa40facc030ea8b0b87f3688e4b3c39eb8b45d5702b3a1300fe2a20",
        "nli_tokenizer": "ff6f6cebf55bcccc4a80b52e956f16ae9d11b0bad02c7db4e7b36975488bf840",
        "llmlingua_q8": "6c9a3a1ecbd8fdd12bb12c5592df5e99a2637403f3f48a50a1a2660056122f2f"
      }
    },
    "key_id": "e6b78dfeccea",
    "receipt_signature": "b377e508ff3a1c571079728d9db93bdda88732af9d3dc40c0608a25ee54202dc0060e82389aea47ed47e12fd04a70adec136d5f175a351e2206badb590c13602"
  }
}

compressed is the squeezed text. receipt is the signed per-call record: the five groups populate only for the stages that ran, and a group with no members is omitted entirely. The signature envelope ships last. Full field-by-field semantics are in receipt fields.

Two checks you can run on this example right now: raw_sha256 equals the SHA-256 of the text in the request; compressed is a byte subsequence of text (delete-only), which is what output_is_subsequence: true asserts.

Mode behaviour worth knowing

• Deterministic and extractive outputs are strict subsets of the input. The receipt's integrity.output_is_subsequence tells you whether the output is a byte-subsequence (it can be false when the fact-preserving JSON reform rewrote structure; the check is client-verifiable either way).
• On tabular JSON payloads, extractive mode skips token deletion - the JSON reform is the compression - and the receipt discloses counts.l2_skipped with the reason. target_ratio is unreachable on such payloads; the reform-only ratio is what you get.
• Verified mode runs the NLI receipt stage; its posterior fields populate in quality. The stage can relax the compression to protect fidelity; when that happens, the receipt shows both the first-attempt ratio and the retries taken.
• Requesting a mode that is not shipped returns an explicit error - the service never falls back silently to a lower rung.