---
title: "Compress History"
method: POST
path: "/api/compress/history/"
tags: ["Compression-Agentic"]
---

# Compress History

`POST /api/compress/history/`

## Headers

- `X-API-Key` string, required

## Request body

- HistoryCompressRequest — Request to compress conversation history. The service layer injects a default query when the resolved backbone requires one (GemFilter), so callers never pass a query directly.
  - `messages` HistoryMessage[], required — Conversation history to compress (list of messages, REQUIRED, max 1000)
    - `role` string, required — Message role: 'user', 'assistant', 'system', or 'tool'
    - `content` string, required — Message content
    - `name` string, nullable — Optional name for the message sender
    - `tool_call_id` string, nullable — Tool call ID for tool messages
  - `keep_recent` integer — Number of recent messages to keep uncompressed (default: 3)
  - `compression_model_name` string, nullable — Compression model to use. Defaults to DEFAULT_MODEL_HISTORY (hcc_latte_v1).
  - `target_compression_ratio` number — Target compression ratio: 0-1 (strength) or >1 for factor. Max 200. Default: 0.3
  - `source` 'demo' | 'extension' | 'sdk:python' | 'sdk:typescript' | 'sdk:curl' | 'gateway:unknown' | 'gateway:anthropic' | 'gateway:openai' | 'gateway:gemini' | 'integration:litellm' | 'integration:hermes' — Source of an API request. Format: source[:detail] - demo, extension: no detail needed - sdk:python, sdk:typescript, sdk:curl - gateway:anthropic, gateway:openai, gateway:gemini - integration:litellm, integration:hermes

## Response `200`

Successful Response

- HistoryCompressResponse
  - `success` boolean
  - `message` string, nullable
  - `data` HistoryCompressResult
    - `summary` string, required — Compressed history summary
    - `original_tokens` integer, required — Token count of original history
    - `compressed_tokens` integer, required — Token count of summary
    - `messages_compressed` integer, required — Number of messages that were compressed
    - `messages_kept` integer, required — Number of recent messages kept
    - `compression_ratio` number, required — Actual compression ratio achieved
    - `duration_ms` integer — Processing time in milliseconds

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/compresr/apis/compresr-platform-api.md) · [All operations](https://skmtc.net/compresr/apis/compresr-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/compresr/compresr-platform-api/versions/93ee959dfa51/schema)