Skip to main content
POST
Recall similar cells (layer L0)

Authorizations

x-hyphae-key
string
header
required

The API key issued for the calling agent. Required on every endpoint except GET /healthz.

Body

application/json

The body for POST /v1/recall.

text
string
required

The query text to embed and recall against.

k
integer
default:10

The maximum number of nodes to return.

Required range: x >= 1
filter
object

Structural filter for recall/query. source_agent and tenant_id here are client-convenience filters; the enforced read boundary is applied separately by the server.

Response

Hydrated nodes in rank order (nearest-first).

id
string<uuid>
required
tenant_id
string
required

Always set; default in V1.

embedding
number<float>[]
required

The cell's embedding vector.

node_type
required

What a graph node represents. Serialized as an externally-tagged enum: the unit variant Scene is the bare string "Scene"; the data-carrying variants are single-key objects (Cell, Agent, Beacon).

Available options:
Scene
cell_type
enum<string>
required

The nine cell types the energy and promotion models are calibrated against.

Available options:
Decision,
Constraint,
Risk,
Pattern,
Lesson,
Fact,
Preference,
Context,
Task
content
string
required
salience
number<float>
required

Constrained to [0.0, 1.0].

Required range: 0 <= x <= 1
source_agent
string
required

The agent that produced this cell.

created_at
string<date-time>
required
last_accessed
string<date-time>
required
layer
enum<string>
required

Semantic hierarchy. L0 = raw cells, L1 = scene centroids/patterns, L2 = architectural decisions/constraints.

Available options:
L0,
L1,
L2
scene_id
string<uuid> | null

The owning scene, if any.

superseded_by
string<uuid> | null

Supersession pointer; set once this cell has been abstracted into a higher-layer Pattern. null = live.