API Reference

Authentication

All endpoints require a Bearer token in the Authorization header.

Two token tiers control access:

Token	Variable	Access level
Pipeline key	KNOWLEDGE_API_KEY	Write: ingest and seed endpoints; also accepted on query and gravity endpoints
User key	KNOWLEDGE_API_USER_KEY	Read: query, analysis, and gravity endpoints only

# Include a valid Bearer token in the Authorization header of every request
Authorization: Bearer <token>

Requests with a missing or invalid token return 401 Unauthorized.

---

POST /api/v1/records

Ingest a single record into the quantum store.

Adds or updates the record in the in-memory columnar store and factor graph. New records receive co-occurrence edges to their K=5 nearest neighbours by ingest order within the same source. Re-ingesting an existing record_id updates the columnar metadata without resetting accumulated mass.

Auth: Pipeline key only

Request body:

Field	Type	Required	Description
record_id	string	Yes	Unique identifier for this record
source_id	string	Yes	Producer identifier; used to scope query results
signal_value	float	No	Normalised quality signal in [0.0, declared_upper_bound]
declared_upper_bound	float	No	Upper bound for signal_value; defaults to 1.0
timestamp	string	No	ISO 8601 timestamp; used for recency fallback ordering
extra_data	object	No	Arbitrary JSON object up to 64KB; field-value pairs drive IDF semantic index

Response 201:

{"status": "ok", "record_id": "my-record-1"}

Example:

# Ingest a single record with signal quality and optional semantic metadata
curl -X POST http://localhost:8080/api/v1/records \
  -H "Authorization: Bearer your-pipeline-key" \
  -H "Content-Type: application/json" \
  -d '{
    "record_id": "my-record-1",
    "source_id": "my-source",
    "signal_value": 0.82,
    "declared_upper_bound": 1.0,
    "timestamp": "2026-05-19T12:00:00Z",
    "extra_data": {"region": "us-east", "severity": "low"}
  }'

---

POST /api/v1/seed/records

Batch-ingest records from an existing corpus into the quantum store.

Designed for bootstrapping a new source from historical data before live ingest begins. All records in one call are ingested as a single topology write and a single async DuckDB batch. For large corpora, prefer seed over repeated single-record ingest calls.

Auth: Pipeline key only

Request body:

{
  "records": [
    {
      "record_id": "my-record-1",
      "source_id": "my-source",
      "signal_value": 0.82,
      "declared_upper_bound": 1.0,
      "timestamp": "2026-05-19T12:00:00Z"
    }
  ]
}

Each record in the records array accepts the same fields as POST /api/v1/records.

Response 201:

{"status": "ok", "seeded": 47}

Example:

# Bulk-seed a source from a list of historical records in one API call
curl -X POST http://localhost:8080/api/v1/seed/records \
  -H "Authorization: Bearer your-pipeline-key" \
  -H "Content-Type: application/json" \
  -d '{"records": [{"record_id": "r1", "source_id": "src", "signal_value": 0.9}]}'

---

GET /api/v1/sources

List all source identifiers in the store, sorted alphabetically.

Auth: Pipeline key or user key

Response 200:

[
  {"id": "source-a"},
  {"id": "source-b"}
]

Example:

# List all known source identifiers currently in the store
curl http://localhost:8080/api/v1/sources \
  -H "Authorization: Bearer your-read-only-key"

---

GET /api/v1/sources/{source_id}/records

List records for a source, re-ranked by quantum walk amplitude.

The walk seeds from the most recent records in the source and evolves the wavefunction over the full factor graph. Records are returned in Born-rule amplitude order descending. Up to 5 cross-source records surfaced by the walk are appended after the primary results.

Auto-REINFORCE runs at query time: each returned record's utility mass is updated from its signal quality. The quantum eraser accumulates a small mass penalty on records the walk assigned near-zero amplitude.

Auth: Pipeline key or user key

Path parameters:

Parameter	Description
source_id	Source identifier, exact match

Query parameters:

Parameter	Type	Default	Constraints	Description
limit	integer	50	min: 1, max: 500	Number of results to return
min_signal	float	—	—	Exclude records with signal_value below this threshold. Omit to return all.

Response 200:

[
  {
    "record_id": "my-record-1",
    "source_id": "my-source",
    "signal_value": 0.82,
    "declared_upper_bound": 1.0,
    "timestamp": "2026-05-19T12:00:00Z"
  }
]

Example: all records, quantum-ranked

# Retrieve records for a source ranked by quantum walk amplitude
curl "http://localhost:8080/api/v1/sources/my-source/records" \
  -H "Authorization: Bearer your-read-only-key"

Example: high-signal records only

# Retrieve records with signal_value >= 0.7, quantum-ranked
curl "http://localhost:8080/api/v1/sources/my-source/records?min_signal=0.7&limit=20" \
  -H "Authorization: Bearer your-read-only-key"

---

POST /api/v1/query

Context-seeded quantum walk query.

Accepts an explicit list of context_ids as the walk seed rather than seeding from the most recent records in the source. The walk concentrates amplitude from the specified context nodes and returns the top K records by Born-rule probability. No auto-REINFORCE or eraser side-effects are applied; this is a pure query with no mass writes.

Auth: Pipeline key or user key

Request body:

Field	Type	Required	Description
source_id	string	Yes	Source to query
context_ids	array of string	Yes	Record identifiers to use as walk seed; must be non-empty
k	integer	No	Number of results to return; default 10, max 500

Response 200:

{
  "records": [
    {
      "record_id": "my-record-1",
      "source_id": "my-source",
      "signal_value": 0.82,
      "declared_upper_bound": 1.0,
      "timestamp": "2026-05-19T12:00:00Z"
    }
  ],
  "walk_mode": "combined",
  "context_ids": ["ctx-record-1", "ctx-record-2"],
  "k": 10
}

walk_mode reflects the active WALK_MODE configuration at query time.

Example:

# Run a context-seeded walk from two known high-quality records
curl -X POST http://localhost:8080/api/v1/query \
  -H "Authorization: Bearer your-read-only-key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "my-source",
    "context_ids": ["ctx-record-1", "ctx-record-2"],
    "k": 15
  }'

---

GET /api/v1/gravity/julia/text-query

Corpus-native text retrieval. Accepts a raw query string and returns the top K records ranked by Born-rule amplitude. No external embedding model is required: retrieval is driven by the corpus's own token co-occurrence graph, Laplacian eigenbasis, and mass field.

The query is tokenized by the amplitude-decaying substring tokenizer. Tokens are expanded one hop through corpus co-occurrence (density matrix query expansion), then projected into the graph's Laplacian eigenbasis as the walk seed state. Falls back to topology-only walk (uniform psi) when no query tokens match the corpus. Pure read path: no REINFORCE, no eraser, no mass writes.

Auth: Pipeline key or user key

Query parameters:

Parameter	Type	Default	Constraints	Description
q	string	Required	max 8192 chars	Query text
k	integer	10	min: 1, max: 500	Number of results to return

Response 200:

{
  "records": [
    {
      "record_id": "my-record-1",
      "source_id": "my-source",
      "signal_value": 0.82,
      "declared_upper_bound": 1.0,
      "timestamp": "2026-05-19T12:00:00Z",
      "julia_mass": 0.12
    }
  ],
  "walk_mode": "combined",
  "query_text": "high energy events in the eastern region",
  "k": 10
}

Example:

# Run a corpus-native text query without an embedding model
curl "http://localhost:8080/api/v1/gravity/julia/text-query?q=high+energy+events&k=5" \
  -H "Authorization: Bearer your-read-only-key"

---

POST /api/v1/query/abl

ABL (Aharonov-Bergmann-Lebowitz) post-selection query. Combines a forward walk seeded from context_ids with a backward walk anchored at target_id. The two walks are composed to produce a joint amplitude distribution that accounts for both the starting context and the desired target outcome.

Returns the top K records by ABL-corrected probability plus overhead metrics. The overhead_ratio answers the question of whether maintaining the backward state costs more than a second forward walk. The abl_correction_rms measures how much the target post-selection shifted the ranking relative to a forward-only walk.

Auth: Pipeline key or user key

Request body:

Field	Type	Required	Description
source_id	string	Yes	Source to query
context_ids	array of string	Yes	Forward walk seed; must be non-empty
target_id	string	Yes	Target record for backward walk post-selection
k	integer	No	Number of results to return; default 10, max 500

Response 200:

{
  "ranked_ids": ["my-record-3", "my-record-7"],
  "fwd_ns": 124000,
  "bwd_ns": 118000,
  "overhead_ratio": 0.95,
  "abl_correction_rms": 0.042,
  "n_nodes": 200
}

Field	Description
ranked_ids	Top-k record IDs by ABL-corrected probability
fwd_ns	Nanoseconds for the forward walk
bwd_ns	Nanoseconds for the backward walk
overhead_ratio	bwd_ns / fwd_ns; near 1.0 means backward walk costs no more than forward
abl_correction_rms	RMS shift between ABL probability and forward-only probability; 0.0 means post-selection had no effect
n_nodes	Graph size at query time

Example:

# Query with context seeded from two records, post-selected toward a target outcome
curl -X POST http://localhost:8080/api/v1/query/abl \
  -H "Authorization: Bearer your-read-only-key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "my-source",
    "context_ids": ["ctx-record-1", "ctx-record-2"],
    "target_id": "target-record-5",
    "k": 10
  }'

---

GET /api/v1/analysis

List analysis summaries for all sources.

The analysis worker recomputes summaries on each cycle (default: every 300 seconds). Returns the most recent summary per source.

Auth: Pipeline key or user key

Response 200:

[
  {
    "source_id": "my-source",
    "record_count": 200,
    "mean_signal": 0.74,
    "mean_mass": 0.12,
    "black_hole_count": 3,
    "computed_at": "2026-05-19T12:00:00Z"
  }
]

---

GET /api/v1/analysis/{source_id}

Return the most recent analysis summary for a single source.

Auth: Pipeline key or user key

Path parameters:

Parameter	Description
source_id	Source identifier

Response 200: Same shape as a single element from GET /api/v1/analysis.

Response 404: Returned when no summary has been computed for the source yet.

---

Gravity Field {#gravity-field}

The gravity field endpoints expose the live mass index and graph health metrics. All gravity endpoints accept either the pipeline key or the user key.

For a conceptual overview of the mass field and lensing, see the Gravity Field page.

---

GET /api/v1/gravity/julia/black-holes

Return records whose utility mass exceeds the Schwarzschild threshold M_s.

Query parameters:

Parameter	Type	Default	Description
epsilon	float	0.05	Amplitude suppression floor used to derive M_s
G	float	1.0	Lensing coupling constant used to derive M_s
K	integer	3	Chebyshev degree used to derive M_s

Response 200:

{
  "record_ids": ["my-record-5", "my-record-12"],
  "schwarzschild_threshold": 0.34,
  "count": 2
}

Example:

# List all records currently above the Schwarzschild threshold with default parameters
curl "http://localhost:8080/api/v1/gravity/julia/black-holes" \
  -H "Authorization: Bearer your-read-only-key"

---

GET /api/v1/gravity/julia/field

Return the full mass vector: all records and their current utility mass, sorted by mass descending.

Response 200:

{
  "masses": [
    {"record_id": "my-record-5", "mass": 0.83},
    {"record_id": "my-record-2", "mass": 0.41}
  ],
  "node_count": 200
}

---

GET /api/v1/gravity/julia/lensing-arcs

Return lensing arc deflection geometry per black hole node.

Query parameters: Same as /gravity/julia/black-holes (epsilon, G, K).

Response 200:

{
  "arcs": {
    "my-record-5": ["my-record-1", "my-record-3", "my-record-7"]
  },
  "bekenstein_entropies": {
    "my-record-5": 0.75
  },
  "black_hole_count": 1,
  "schwarzschild_threshold": 0.34
}

Field	Description
arcs	Object mapping each black hole record_id to an array of record_ids in its lensing arc (nodes reachable from the black hole's neighbours without crossing another black hole)
bekenstein_entropies	Object mapping each black hole record_id to its Bekenstein entropy estimate: arc_size / 4.0
black_hole_count	Number of black hole nodes detected
schwarzschild_threshold	Utility mass threshold used to classify black holes

---

GET /api/v1/gravity/julia/stats

Return graph statistics: node count, edge count, Schwarzschild threshold, and spectral gap.

Query parameters: Same as /gravity/julia/black-holes (epsilon, G, K).

Response 200:

{
  "node_count": 200,
  "edge_count": 980,
  "schwarzschild_threshold": 0.34,
  "spectral_gap": 0.21,
  "black_hole_count": 3
}

---

GET /api/v1/gravity/mesh

Return a live mesh health snapshot: SLEM, spectral gap, mixing time bound, and certainty parameter.

Query parameters: Same as /gravity/julia/black-holes (epsilon, G, K).

Response 200:

{
  "slem": 0.79,
  "spectral_gap": 0.21,
  "mixing_time_bound": 14,
  "certainty_parameter": 0.08,
  "node_count": 200,
  "black_hole_count": 3,
  "schwarzschild_threshold": 0.34
}

Field	Description
slem	Second Largest Eigenvalue Modulus; lower is better
spectral_gap	1 - slem; higher means faster walk convergence
mixing_time_bound	Upper bound on walk mixing time in steps
certainty_parameter	Inverse Participation Ratio of the wavefunction after walk; higher means more focused result

SLEM near 1.0

When slem > 0.9, the walk is near critical slowing down. The serial (exclusive write lock) query path activates automatically. Monitor this value; sustained slem > 0.9 indicates the graph topology needs more ingest diversity to increase the spectral gap.

---

GET /api/v1/gravity/mesh/history

Return the append-only SLEM trend log written by the analysis worker each cycle.

Query parameters:

Parameter	Type	Default	Constraints	Description
limit	integer	100	min: 1, max: 1000	Number of snapshots to return, newest first

Response 200:

[
  {
    "slem": 0.79,
    "spectral_gap": 0.21,
    "node_count": 200,
    "computed_at": "2026-05-19T12:00:00Z"
  }
]

---

Diagnostics

The diagnostic endpoints return field observables and spectral bounds derived from the current graph topology and mass field. All diagnostics are read-only and accept either the pipeline key or the user key. Most apply Hawking decay before computing so results reflect the current time-decayed mass field.

---

GET /api/v1/gravity/julia/dalembert-field

Return the discrete d'Alembertian (Box M) of the mass field at every node. Box M measures local mass curvature: positive values indicate nodes downstream of high-mass regions; negative values identify local mass peaks (black hole candidates). The RMS of Box M across all nodes is a convergence diagnostic: lower RMS means the mass field is approaching the quasicrystal equilibrium condition.

Auth: Pipeline key or user key

Response 200:

{
  "field": {"my-record-1": -0.14, "my-record-2": 0.03},
  "node_count": 200,
  "rms_deviation": 0.082
}

Field	Description
field	Map of record_id to Box M value
node_count	Number of nodes in the graph
rms_deviation	RMS of Box M across all nodes; approaches 0 at convergence

---

GET /api/v1/gravity/julia/quantum-speed-limit

Return the Mandelstam-Tamm quantum speed limit bounds for the current Hamiltonian. The QSL gives the minimum time the mesh state needs to undergo an orthogonal transition. Two Delta_E estimates are returned: the standard deviation of Hamiltonian diagonal entries (lower bound) and the half-width of the full spectrum (upper bound).

Auth: Pipeline key or user key

Response 200:

{
  "delta_e_diag": 0.42,
  "delta_e_width": 1.50,
  "tau_min_lower": 3.73,
  "tau_min_upper": 1.05,
  "n_nodes": 200
}

Field	Description
delta_e_diag	Energy spread from diagonal variance; lower bound on Delta_E
delta_e_width	Energy spread from full spectrum half-width; upper bound on Delta_E
tau_min_lower	(pi/2) / delta_e_width; lower bound on adaptation time
tau_min_upper	(pi/2) / delta_e_diag; upper bound on adaptation time
n_nodes	Graph size

null is returned for tau_min_lower or tau_min_upper when the corresponding Delta_E is zero (uniform Hamiltonian: no mass variance).

---

GET /api/v1/gravity/julia/bp-convergence

Return the Ihler-Fisher-Willsky spectral radius upper bound for Belief Propagation on the current factor graph topology. When rho_bound < 1.0, loopy BP is guaranteed to converge. The quasicrystal attractor hypothesis predicts that at convergence the graph is locally tree-like, driving rho_bound toward zero.

Auth: Pipeline key or user key

Response 200:

{
  "rho_bound": 0.83,
  "converges": true,
  "n_nodes": 200,
  "n_edges": 980,
  "max_node_id": 200
}

Field	Description
rho_bound	Spectral radius upper bound; < 1.0 guarantees convergence
converges	true when rho_bound < 1.0
n_nodes, n_edges	Graph size at compute time

---

GET /api/v1/gravity/julia/decoherence

Return the decoherence ratio: the fraction of edges with negative Ollivier-Ricci curvature (wormhole proxies from the Ricci cache). A higher wormhole_fraction indicates topology closer to the decoherent phase boundary.

Auth: Pipeline key or user key

Query parameters: Same as /gravity/julia/black-holes (epsilon, G, K).

Response 200:

{
  "wormhole_count": 86,
  "total_edges": 262,
  "wormhole_fraction": 0.328244,
  "decoherence_ratio": 0.328244,
  "schwarzschild_threshold": 0.34
}

wormhole_count uses the Ricci bottleneck cache from the most recent analysis worker cycle. It is 0 until the first analysis cycle completes.

---

GET /api/v1/gravity/julia/causal-cone

Compute the causal cone of a source node up to BFS depth d. Returns all nodes reachable within d hops (timelike and lightlike), their BFS distances, spacetime intervals (depth^2 - dist^2), and classifications. Nodes beyond d hops are spacelike and excluded from cone_nodes.

Auth: Pipeline key or user key

Query parameters:

Parameter	Type	Default	Constraints	Description
source_id	string	Required	—	Starting node; must be a known record_id
depth	integer	3	min: 1, max: 20	BFS depth

Response 200:

{
  "cone_nodes": ["my-record-1", "my-record-3"],
  "distances": {"my-record-1": 0, "my-record-3": 2},
  "spacetime_intervals": {"my-record-1": 9.0, "my-record-3": 5.0},
  "classifications": {"my-record-1": "timelike", "my-record-3": "timelike"},
  "spacelike_count": 185,
  "source_id": "my-record-1",
  "depth": 3
}

Field	Description
cone_nodes	Record IDs inside the causal cone (timelike + lightlike)
distances	BFS hop count from source_id per node
spacetime_intervals	depth^2 - dist^2; positive means timelike, zero means lightlike
classifications	"timelike" (dist < depth) or "lightlike" (dist == depth) per node
spacelike_count	Number of nodes outside the cone

Response 200 (source not found): Returns an empty cone_nodes list and an error field explaining the failure; does not return 404.

---

GET /api/v1/gravity/julia/spacetime-dilation

Return the gravitational time-dilation gamma factor for every node relative to its nearest black hole:

gamma(v) = 1 / sqrt(1 - (r_s / d)^2)

Where r_s = ceil(m_BH / M_s) is the integer-hop Schwarzschild radius and d is the BFS distance to the nearest black hole. Nodes inside or on the event horizon receive null (infinite gamma). Nodes with no reachable black hole receive gamma = 1.0.

Auth: Pipeline key or user key

Query parameters: Same as /gravity/julia/black-holes (epsilon, G, K).

Response 200:

{
  "gamma": {
    "my-record-1": 1.12,
    "my-record-5": null,
    "my-record-9": 1.0
  },
  "node_count": 200,
  "schwarzschild_params": {"epsilon": 0.05, "G": 1.0, "K": 3}
}

null in gamma means the node is inside or on the event horizon (gamma = Inf). 1.0 means no black hole is reachable from the node.

---

POST /api/v1/gravity/julia/reinforce

Push an explicit REINFORCE feedback signal for a record.

Use this endpoint when a caller has out-of-band quality signal not captured by ingest (for example: a downstream consumer determined the record was useful or harmful).

Auth: Pipeline key only

Request body:

Field	Type	Required	Description
record_id	string	Yes	Record to update
outcome	integer	Yes	+1 for reward (mass decreases); -1 for penalty (mass increases)
eta	float	No	Learning rate; default 1.0; must be positive

Response 200:

{"record_id": "my-record-1", "new_mass": 0.31}

Example:

# Apply an explicit penalty to a record that produced a bad downstream result
curl -X POST http://localhost:8080/api/v1/gravity/julia/reinforce \
  -H "Authorization: Bearer your-pipeline-key" \
  -H "Content-Type: application/json" \
  -d '{"record_id": "my-record-1", "outcome": -1}'

---

Configuration

PUT /api/v1/config/field-weights

Set per-field weights for IDF cosine similarity. Weights are applied immediately to all subsequent queries without re-ingesting records. An empty body resets all fields to equal weight (no scaling).

Auth: Pipeline key only

Request body:

{
  "lat_grid":    3.0,
  "lon_grid":    3.0,
  "energy_tier": 5.0,
  "quality":     1.0
}

All weights must be positive. Fields absent from the weight map default to 1.0 at query time. Sending an empty object {} removes all declared weights.

Response 200:

{"field_weights": {"lat_grid": 3.0, "lon_grid": 3.0, "energy_tier": 5.0, "quality": 1.0}}

Example:

# Declare geographic and energy fields as the primary similarity signal for this corpus
curl -X PUT http://localhost:8080/api/v1/config/field-weights \
  -H "Authorization: Bearer your-pipeline-key" \
  -H "Content-Type: application/json" \
  -d '{"lat_grid": 3.0, "lon_grid": 3.0, "energy_tier": 5.0, "quality": 1.0}'

---

GET /api/v1/config/field-weights

Return the current field weight map.

Auth: Pipeline key or user key

Response 200:

{"field_weights": {"lat_grid": 3.0, "energy_tier": 5.0}}

An empty field_weights object means all fields are weighted equally.

---

GET /health

Return the server status and current node count. No authentication required.

Response 200:

{"status": "ok", "node_count": 200}