--- title: "Post Compact Endpoint" method: POST path: "/v1/responses/compact" tags: ["Responses"] --- # Post Compact Endpoint `POST /v1/responses/compact` ## Request - Base URL: `https://api.pharia.example.com` - URL: `https://api.pharia.example.com/v1/responses/compact` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Handle POST /v1/responses/compact. Loads the chain anchored at ``previous_response_id``, asks the inference backend (via the same scheduler used by /v1/responses) to summarise it using the fixed summarisation prompt, persists the result via CompactionPort, and returns the synthetic CompactedResponse. Per the ADR: 404 on ownership/missing, 413 on > 10 MiB output, 502/504 on backend failure, 501 when compaction storage is not configured. target_size_pct is resolved here from ContextConfig so the domain service stays free of application-layer imports. ## Request body - CompactRequest: Request body for ``POST /v1/responses/compact``. v1 only accepts ``previous_response_id``. The stateless explicit-input variant is deferred to a future ADR. - `previous_response_id` string, required ## Response `200` Successful Response - CompactedResponse: Server-shaped compaction response, mirroring OpenAI's compaction object. The ``id`` is derived from the persisted row's natural key at serialisation time (see ``derive_compaction_id``); it is not stored. ``output`` contains the synthetic ``compaction`` input-item. The ``encrypted_content`` field name matches OpenAI; the value is plaintext today (real envelope encryption is its own ADR). - `id` string, required - `created_at` integer, required: Unix epoch seconds. - `object` 'response.compaction' - `output` union[], required - union: Input item type, used to determine the input item schema - InputItemMessage: Input item for structured input. Per Open Responses spec, supports: - message type: role + content - function_call type: call_id + name + arguments (for history) - function_call_output type: call_id + output (tool results) Fields: - id: unique identifier (optional on input, populated on output) - status: in_progress, completed, incomplete (optional on input) - `type` 'message', required - `id` string, nullable: Unique identifier for messages - `status` 'in_progress' | 'completed' | 'incomplete', nullable - `role` string, nullable - `content` union - string - string[] - ContentItem[] - `type` string - `text` string, required - `annotations` object[] - … - union[] - union: A typed input content part (input_text/input_image). - … - InputItemReasoning: Input item for reasoning type messages. - `type` 'reasoning', required - `id` string, required: Unique identifier for reasoning messages - `status` 'in_progress' | 'completed' | 'incomplete', nullable - `role` string, nullable - `content` union - string - string[] - ContentItem[] - `type` string - `text` string, required - `annotations` object[] - … - union[] - union: A typed input content part (input_text/input_image). - … - `summary` ReasoningSummaryItem[]: Reasoning summary items returned by the downstream service. - `type` 'summary_text', required - `text` string, required - InputItemFunctionCall: Input item for function call (history reconstruction). - `type` 'function_call', required - `id` string, required: Unique identifier for the function call - `call_id` string, required - `status` 'in_progress' | 'completed' | 'incomplete', nullable - `name` string, nullable - `arguments` string, nullable - InputItemFunctionCallOutput: Input item for function call (history reconstruction). - `type` 'function_call_output', required - `call_id` string, required - `id` string, nullable: Unique identifier for the function call output - `status` 'in_progress' | 'completed' | 'incomplete', nullable - `output` string, nullable - InputItemShellCall: Input item for shell tool call (history reconstruction). - `type` 'shell_call', required - `id` string, required: Unique identifier for the shell call - `call_id` string, required - `status` 'in_progress' | 'completed' | 'incomplete', nullable - `name` string, nullable - `arguments` string, nullable - InputItemShellCallOutput: Input item for shell tool call output (history reconstruction). - `type` 'shell_call_output', required - `call_id` string, required - `id` string, nullable: Unique identifier for the shell call output - `status` 'in_progress' | 'completed' | 'incomplete', nullable - `output` string, nullable - InputItemMcpApprovalRequest - `type` 'mcp_approval_request', required - `id` string, required: Unique identifier for the approval request - `name` string, nullable - `server_label` string, nullable - `arguments` string, nullable - InputItemMcpApprovalResponses - `type` 'mcp_approval_response', required - `id` string, required: Unique identifier for the approval response - `approval_request_id` string, required - `approve` boolean, required - `reason` string, nullable: Why the call was not approved. Filled in by the service when the user sent a new message instead of answering. - `name` string, nullable - `arguments` string, nullable - InputItemMcpListTools - `type` 'mcp_list_tools', required - `id` string, required: Unique identifier for the MCP list tools - `server_label` string, nullable - `tools` union - object - unknown[] - unknown - `error` string, nullable - InputItemMcpCall - `type` 'mcp_call', required - `id` string, required: Unique identifier for the MCP call - `name` string, required - `arguments` string, nullable - `server_label` string, nullable - `output` string, nullable - `error` McpToolExecutionError: The tool's own error, in the shape the OpenAI SDK's mcp_call uses. - `type` 'mcp_tool_execution_error' - `content` string, required - InputItemFileSearchCall: Hosted file-search call/result output item. Mirrors OpenAI/OpenResponses ``file_search_call`` enough for upstream PydanticAI clients to map it as a native tool call while allowing Sherlock result extensions in ``results``. - `type` 'file_search_call', required - `id` string: Unique identifier for the file search call - `status` 'in_progress' | 'searching' | 'completed' | 'incomplete' | 'failed', required - `queries` string[] - `results` object[], nullable - InputItemWebSearchCall: Hosted web-search call/result output item. Mirrors OpenAI/OpenResponses ``web_search_call`` enough for upstream clients to map it as a native tool call while embedding the LinkUp results directly in ``results``. - `type` 'web_search_call', required - `id` string: Unique identifier for the web search call - `status` 'in_progress' | 'searching' | 'completed' | 'failed', required - `action` object, nullable: How the model invoked the tool, e.g. {"type": "search", "query": ...} - `results` object[], nullable - InputItemCompaction: Compaction item — opaque summary blob, mirrors OpenAI's `/v1/responses/compact` shape. - `type` 'compaction', required - `id` string, nullable: Identifier of the compaction item. - `encrypted_content` string, required: The (potentially encrypted) content of the compaction summary. - `usage` UsageInfo, required: Token usage information. - `input_tokens` integer, required - `output_tokens` integer, required - `total_tokens` integer, required ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found - `413`: Content Too Large - `422`: Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically. - `425`: Too Early - `500`: Internal Server Error - `501`: Not Implemented - `502`: Bad Gateway - `504`: Gateway Timeout --- [API](https://skmtc.dev/aleph-alpha/apis/stateful-responses.md) - [All operations](https://skmtc.dev/aleph-alpha/apis/stateful-responses/llms.txt) - [OpenAPI document](https://skmtc.dev/aleph-alpha/apis/stateful-responses/revisions/2747297acb54?raw)