---
title: "Trim one payload to what a query needs (trim-1)"
method: POST
path: "/v1/trim"
---

# Trim one payload to what a query needs (trim-1)

`POST /v1/trim`

## Request

- Base URL: `https://gateway.caveman.so`
- URL: `https://gateway.caveman.so/v1/trim`
- Auth: API key in header `x-cave-api-key`

Compression of one payload: trim-1 keeps the lines of input the query needs, verbatim, and leaves out the rest under markers. Not compaction: it never reads a conversation. The answer is the output and token counts only. Metered per call and per token against the organization's monthly trim allowance.

## Headers

- `x-cave-retention` 'metadata' | 'zdr'

## Request body

- TrimRequest
  - `input` string, required: One payload: a tool output, file, log or document. The body is at most 2 MB.
  - `query` string, required: What the payload is read for: the ask, the agent's intent, the call that produced it. Must not be blank.
  - `level` 'conservative' | 'balanced' | 'aggressive': How much trim-1 keeps: conservative keeps most.

## Response `200`

The trimmed payload

- TrimResponse
  - `output` string, required: The lines of input the query needs, verbatim and in order, with a marker for each run left out; the input itself when trimming would not cut enough.
  - `tokens_before` integer, required
  - `tokens_after` integer, required
  - `recovery_handle` string: Present when something was left out and it was stored: GET /sdk/v1/ccr/{handle} returns the input byte for byte. Absent under metadata or zdr retention, and when the installation has no recovery store or it failed; the output is the same either way.
  - `model` 'trim-1', required

## Other responses

- `400`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `402`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `413`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `429`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `4XX`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `5XX`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.

---

[API](https://skmtc.dev/caveman/apis/caveman-cloud-api.md) - [All operations](https://skmtc.dev/caveman/apis/caveman-cloud-api/llms.txt) - [OpenAPI document](https://skmtc.dev/caveman/apis/caveman-cloud-api/revisions/508312d01cfc?raw)