---
title: "Surface Insights"
method: POST
path: "/v1/insights/surface"
tags: ["insights"]
---

# Surface Insights

`POST /v1/insights/surface`

## Request

- Base URL: `https://api.heirmos.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.heirmos.com/v1/insights/surface`
- Auth: HTTP bearer

시추(프루스트 트리거, P19-1) — surface deep + weathered + near memories.

The opposite of search: given the current context, returns memories you
haven't recalled in a while but are semantically standing on. On-demand,
read-only, **never logs a recall** (the server is recalling, not the user —
logging would reset weathering and self-destruct the signal).

## Request body

- SurfaceRequest: POST /v1/insights/surface — 시추(프루스트 트리거, Phase 19 P19-1). The AI passes its current conversation context; the server surfaces deep + weathered + semantically-near memories (the OPPOSITE of search — what you didn't ask for but are standing on).
  - `context` string
  - `limit` integer

## Response `200`

Successful Response

- SurfaceResponse: POST /v1/insights/surface — on-demand, read-only, NOTHING persisted. The surfacing is the SERVER recalling, not the user — so it does NOT log a recall_event (that would reset weathering and self-destruct the very signal it rides on; DECISIONS ## 정책, 2026-06-14).
  - `items` SurfaceItem[], required
    - `path` string, required
    - `title` string, nullable
    - `summary` string, nullable
    - `score` number, required
    - `reason` string, nullable
  - `context_used` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/heirmos/apis/heirmos-api.md) · [All operations](https://skmtc.dev/heirmos/apis/heirmos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/heirmos/apis/heirmos-api/revisions/ed490b1866e7?raw)