---
title: "Compress a text input"
method: POST
path: "/v1/compress"
tags: ["compression"]
---

# Compress a text input

`POST /v1/compress`

## Request

- Base URL: `https://api.thetokencompany.com`
- URL: `https://api.thetokencompany.com/v1/compress`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/thetokencompany/apis/the-token-company-compression-api/docs/v1/compress/post.ts> (a function with typed inputs; its response is checked against the schema)

Compresses a single input — a string, or an object or array that is JSON-encoded first — and returns the compressed text with before-and-after token counts. Send the result to any LLM in place of the original. Wrap any span in <ttc_safe> tags to exclude it from compression. Aggressiveness guidance: 0.05-0.2 for text the model must answer questions about, 0.5-0.8 for conversation history and background context. If the compression backend is unavailable the API returns the original input unchanged rather than failing, so a compression outage never breaks the calling flow.

## Request body

- CompressionRequest: One input to compress, plus the settings to compress it with.
  - `model` string, required: Compression model. `bear-2` is current and recommended; `bear-1.2` is the previous generation.
  - `input` union, required: The content to compress. Objects and arrays are JSON-encoded before compression. Must not be empty.
    - string
    - object
    - unknown[]
      - unknown
  - `compression_settings` CompressionSettings: How hard to compress.
    - `aggressiveness` number, float: How much content to remove. Use 0.05-0.2 for text the model reads directly and answers questions about; 0.5-0.8 for conversation history and background context where exact wording matters less. Defaults to 0.2 when omitted.
  - `app_id` string: Your own label for the calling application, so usage can be broken down per app. A per-request value overrides one set on the client.

## Response `200`

The compressed text and its token counts.

- CompressionResponse: The compressed text and its token counts.
  - `output` string, required: The compressed text, ready to send to any LLM.
  - `output_tokens` integer, required: Token count after compression.
  - `original_input_tokens` integer, required: Token count of the original input, before compression.

## Other responses

- `401`: The API key is missing, invalid, or inactive.
- `402`: Insufficient balance on the account.
- `413`: The input exceeds the per-request token limit.
- `422`: The request body failed server-side validation. `detail` is an array with one entry per rejected field.
- `429`: Too many requests. Retry after a pause.
- `500`: Unexpected server error.
- `503`: A dependency the API needs is unavailable. Retry.

---

[API](https://skmtc.dev/thetokencompany/apis/the-token-company-compression-api.md) - [All operations](https://skmtc.dev/thetokencompany/apis/the-token-company-compression-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thetokencompany/apis/the-token-company-compression-api/revisions/5b11c3a26661?raw)