CAcaveman

Compact a whole agent history to a token budget (compact-1)

Compaction of a whole history: compact-1 returns the history to continue from within budget_tokens. Not compression of one payload: use /v1/trim for that. The answer is the history and token counts only. A history that already fits comes back as sent. Metered per call and per token against the organization's monthly compact allowance.

post/v1/compact

Request

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

Headers

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

metadata or zdr narrows the project's retention for this call: the model runs in memory, nothing is stored and no recovery handle is returned. A call never widens the project's retention.

Request body

messagesobject[] required

The agent's whole history: OpenAI chat messages (tool_calls, role tool) or Anthropic Messages (tool_use and tool_result blocks), not mixed. The body is at most 8 MB.

budget_tokensinteger required

The most tokens the history may take after its leading system messages, which are kept as sent and not counted.

Response

The compacted history

messagesobject[] required

The history to continue from, in the request's shape: the system prompt, the user's messages, one compact-1 block (a ledger of the work and the older lines most likely needed, with markers for what was left out), then the newest turns. Every message kept whole is returned as sent, byte for byte, and a history that already holds a compact-1 block keeps everything up to it byte-identical, so the provider's prompt cache survives.

tokens_beforeinteger required

The request's text tokens after its leading system messages (cl100k_base estimate of compact-1's serialization; images and thinking blocks are not counted).

tokens_afterinteger required

The answer's text tokens, counted the same way; at most budget_tokens. Images and thinking blocks kept in whole messages come on top.

recovery_handlesstring[]

Present when text was left out and it was stored: GET /sdk/v1/ccr/{handle} returns the left-out spans, each under the reference its marker shows. Absent under metadata or zdr retention, and when the installation has no recovery store or it failed: the markers then point at nothing.

model'compact-1' required

Changes

No recorded changes to this operation across all 1 revision of this API.