---
title: "Compact context"
method: POST
path: "/v1/compact"
tags: ["compact"]
---

# Compact context

`POST /v1/compact`

Compress chat history and code context by removing irrelevant lines at 33,000 tok/s. Every surviving line is byte-for-byte identical to the original input. Accepts string input or message arrays.

## Request body

- CompactRequest — Text or conversation to compress, plus the knobs controlling how aggressively lines are pruned.
  - `input` string — Text to compact. One of `input` or `messages` is required.
  - `messages` CompactInputMessage[] — Conversation messages to compact. Takes priority over `input`.
    - `role` 'system' | 'user' | 'assistant', required — Role of the author of this message. System messages are preserved verbatim unless `compress_system_messages` is set.
    - `content` string, required — Text of this message, from which the compactor prunes irrelevant lines
  - `query` string — Focus query for relevance-based pruning. Lines relevant to this query are kept.
  - `compression_ratio` number — Fraction of input to keep. 0.3 = aggressive, 0.7 = light.
  - `preserve_recent` integer — Keep last N messages uncompressed.
  - `compress_system_messages` boolean — When true, system messages are also compressed. By default they are preserved verbatim.
  - `include_line_ranges` boolean — Include compacted_line_ranges in response.
  - `include_markers` boolean — Include (filtered N lines) text markers. When false, gaps become empty lines.
  - `model` string — Model ID.

## Response `200`

Compact response with compressed output and metadata

- CompactResponse — Compacted output, per-message line ranges, and usage statistics.
  - `id` string, required — Unique identifier for the compact request
  - `object` string, required — Object type, always `compact`
  - `model` string, required — Model used
  - `output` string, required — All compacted messages joined into a single string
  - `messages` CompactOutputMessage[], required — Per-message compaction results
    - `role` string, required — Role carried over from the corresponding input message
    - `content` string, required — The compacted message content with irrelevant lines removed
    - `compacted_line_ranges` CompactLineRange[] — Line ranges that were removed during compaction (1-indexed, inclusive)
      - `start` integer, required — Start line number (1-indexed, inclusive)
      - `end` integer, required — End line number (1-indexed, inclusive)
    - `kept_line_ranges` CompactLineRange[] — Line ranges force-preserved via `<keepContext>` tags (1-indexed, inclusive)
      - `start` integer, required — Start line number (1-indexed, inclusive)
      - `end` integer, required — End line number (1-indexed, inclusive)
  - `usage` CompactUsage, required — Usage statistics — token counts and timing for a single compaction.
    - `input_tokens` integer, required — Number of tokens in the text submitted for compaction
    - `output_tokens` integer, required — Number of tokens in the compacted output
    - `compression_ratio` number, required — Actual compression ratio achieved (output_tokens / input_tokens)
    - `processing_time_ms` integer, required — Processing time in milliseconds

## Other responses

- `400` — Malformed request — missing or invalid fields.
- `401` — Missing or invalid API key.
- `429` — Rate limited — retry after the interval in the Retry-After header.
- `500` — Internal error — safe to retry with backoff.

---

[API](https://skmtc.dev/morphllm/apis/morph-api.md) · [All operations](https://skmtc.dev/morphllm/apis/morph-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/morphllm/morph-api/revisions/b9a74274b2ab/schema)