Edge intelligence appliance running on Pi Zero 2 W. Explore 98 API endpoints below, or open the User Guide for setup and usage instructions.
In the RVF store, dim=8
Witness chain entries
Since last boot
On-disk RVF file
Returns device ID, uptime, vector count, store size, dimension, witness chain length, and pairing state. This is the primary health-check endpoint.
Returns the device's unique identity: UUID, Ed25519 public key (hex), current epoch, firmware version, and vector dimension. Used for pairing verification and attestation.
Returns whether the device is currently paired, whether the pairing window is open, and how many seconds remain. The pairing window opens when the physical button is pressed (or always open in virtual mode).
Pairs your client with the Seed. Requires the pairing window to be open (press physical button or use virtual mode). Once paired, you can use all write endpoints (ingest, delete, config updates, OTA). Send client_name to identify this client.
Returns total vectors (live + deleted), file size on disk, current epoch, dimension, and witness chain length. The epoch increments on every write operation.
Append vectors to the RVF store. Each entry is [id, [f32...]] where id is a u64 and the array must match the store dimension (default 8). Duplicate IDs overwrite. Triggers a witness chain entry and increments the epoch.
Find the k most similar vectors using cosine similarity. Returns ranked results with IDs, distances, and the query vector. Uses BinaryHeap with O(n log k) complexity and pre-computed L2 norms for fast dot-product scoring.
Mark vectors as deleted by ID. Deleted vectors are excluded from queries but remain on disk until compaction. Increments epoch and adds a witness entry.
Returns all live (non-deleted) vectors with their IDs and data. Used for seed-to-host replication. Response includes the current epoch for conflict detection.
O(1) lookup of a single vector by its u64 ID. Returns the vector data, metadata, slot position, and deletion status. Returns 404 if ID not found.
Update metadata for an existing vector without re-ingesting the vector data. Appends a META_ONLY entry to the RVF file. Requires pairing.
Triggers immediate compaction: rewrites the RVF file excluding deleted vectors. Returns bytes reclaimed, vectors surviving, and new epoch. Runs synchronously (< 5s for 20k vectors).
Returns the set of soft-deleted vector IDs that have not yet been compacted. Useful for sync clients to detect deletions.
Returns kNN graph statistics: node count, edge count, average degree, orphan/boundary/core classification, mean max similarity, and pending inserts.
Returns the k=16 nearest neighbors of a vector from the kNN graph. Each neighbor includes its ID and quantized similarity score.
Returns the append-only witness hash chain. Each entry links to the previous via SHA-256, creating a tamper-evident log of all write operations (ingest, delete, compact).
Walks the entire witness chain and verifies every hash link. Returns valid: true if the chain is intact, or the index of the first broken link.
Returns the monotonic epoch counter. The epoch increments on every write operation and is included in witness entries for ordering.
Returns the boot attestation chain: device ID, public key, boot timestamp, firmware version, and a signed attestation proving the device booted with its identity key.
Appends a new entry to the witness chain. The entry is hashed with the previous chain head, creating a tamper-evident link. Use event to describe the witnessed action.
Signs the provided data using the device's Ed25519 private key. Returns the hex-encoded signature. Verify with /custody/verify using the device's public key from /identity.
Verifies that the given signature matches the data using the device's public key. Returns valid: true/false. Use a signature obtained from /custody/sign.
Returns the optimizer's current state: last run timestamp, total optimizations performed, whether a run is in progress, and store metrics. The optimizer runs every 10s in the background, performing compaction and kNN graph rebuilds when changes are detected.
Detailed metrics from the last optimization cycle: vectors compacted, bytes reclaimed, kNN graph nodes rebuilt, total run time, and cumulative statistics.
Requests an immediate optimization run (compaction + kNN rebuild) outside the normal 10s schedule. Useful after bulk ingestion or deletion. The run happens asynchronously.
Returns the structural fragility analysis of the vector store's kNN graph. Includes fragility score (0.0=solid, 1.0=fragile), min-cut value, partition sizes, and SHA-256 boundary hash. Fragility drives the thermal governor's demand level for DVFS decisions.
Flags the boundary for recomputation on the next optimizer cycle. Boundary analysis is event-gated (only runs when changes_since_boundary exceeds threshold), so this forces a fresh run regardless.
Lists all active sensor channels with their names, driver types, sample rates, and health status. Default configuration: 6 synthetic channels at 10 Hz (temperature, humidity, pressure, vibration, power, compound).
Returns the most recent sensor samples from each channel: raw value, quality code (0=good, 1=saturated, 2=timeout, 3=error), and timestamp. Updated at the driver's sample rate (default 10 Hz).
Returns statistics about the sensor embedding store: total embeddings ingested, window buffer depth, and embedding dimension (5C + C*(C-1)/2 = 45-dim for 6 channels).
Returns the most recent sensor embedding: a 45-dimensional vector computed from the sliding window of raw samples. Components: 5 statistics per channel (mean, std, min, max, slope) + all pairwise cross-correlations.
Returns the embedding pipeline config: window size, hop size, normalization method (EMA), and feature extraction parameters.
Returns drift detection status from three detectors: Page-Hinkley (mean shift), ADWIN (distribution change), and Reservoir ESN (64-neuron echo state network for nonlinear drift). Reports drift_detected, severity, and per-detector state.
Returns the ring buffer of recent drift events: which detector fired, when, severity, and affected channels. Useful for diagnosing sensor degradation over time.
Lists all configured actuator outputs (GPIO, PWM) with their current state (active/inactive), duty cycle, and recent event history. Actuators are fired by reflex rules in response to sensor conditions.
Returns the reflex arc rules that map sensor conditions to actuator actions. Rules have triggers (threshold, drift, fragility), actions (fire, release, PWM), cooldown periods, and priority ordering. Safety-first: fragility checks run before boundary analysis.
Returns the HD gate coprocessor status: 1024-bit hyperdimensional hash baseline, popcount-based anomaly threshold, and gate pass/fail statistics. The HD gate screens sensor embeddings before they reach the main store.
Returns the GPIO pin map: which pins are assigned to sensors (input) vs actuators (output), their current direction, pull-up/down state, and driver association.
Returns the temporal coherence score (0.0=incoherent, 1.0=perfectly coherent), computed from time-slice similarity across the kNN graph. Includes slice count, profile age, and cold-start status (partial profile from 3+ slices, full at 60).
Returns the profile history ring buffer (max 10 entries). Each entry has a coherence score and timestamp, enabling trend analysis. Profiles are recomputed every 5 time slices (configurable).
Returns detected phase boundaries in the temporal profile. Boundaries must persist across N consecutive recomputes to be reported (prevents false positives). Each boundary includes its time index, magnitude, and persistence count.
Lists vectors that have no connections in the kNN graph (orphans). These vectors are structurally isolated and may indicate data quality issues or the need for compaction.
Updates the coherence subsystem config. slices_per_recompute controls how often the profile is rebuilt (lower = more responsive, higher = more stable).
Returns real-time thermal state: SoC temperature (millidegrees on Linux, simulated on other platforms), thermal zone (Cool/Warm/Hot/Critical), current CPU frequency in MHz, temperature derivative (heating/cooling rate), and firmware throttle flags.
Returns the governor's last decision: current demand level (Idle/Background/Boost/TurboBurst/QueryActive), target frequency step, thermal ceiling, and whether a turbo burst is active. The governor runs at 1 Hz and makes 5-step decisions: firmware veto, thermal ceiling, predictive preemption, demand target, turbo management.
Returns the last N governor ticks with full state at each tick: temperature, zone, frequency, demand level, and decision reason. Useful for diagnosing thermal behavior and frequency transitions over time.
Returns the silicon characterization profile: for each frequency step [600, 1000, 1200, 1300 MHz], the number of test runs, pass/fail results, and the maximum stable frequency for this specific chip. Characterization runs 10x boundary analysis at each step and compares SHA-256 hashes.
Compares boundary analysis results at stock frequency vs boosted frequency. If mismatch exceeds 1%, recommends downgrading max frequency. Tracks baseline and boosted min-cut values in rolling windows.
Returns the learned DVFS profile: voltage map per frequency step, recommended over-voltage settings, stable boot count, and whether the profile suggests voltage reduction is safe. Persisted to /var/lib/cognitum/dvfs-profile.json.
Returns the turbo burst scheduler state: whether a burst is active, remaining ticks, cooldown status, and queued work items. Turbo bursts temporarily overclock for intensive operations (kNN rebuild, characterization) with automatic cooldown.
Returns the temporal-overclock coherence analysis: permutation test results checking whether CPU frequency changes correlate with phase boundary detection artifacts. Helps distinguish real phase transitions from overclock-induced noise.
Returns all governor config parameters: tick interval (ms), thermal EMA alpha, cool holdoff (seconds), max turbo duration (ticks), cooldown duration (ticks), demand holdoff thresholds, and hysteresis settings.
Cumulative session statistics: time spent in each thermal zone, frequency step distribution, total transitions, peak/min temperatures, turbo burst count and total turbo ticks. Resets on restart.
Triggers a full silicon characterization: runs 10x boundary analysis at each of the 4 frequency steps [600, 1000, 1200, 1300 MHz], comparing SHA-256 partition hashes to determine the maximum stable overclock for this specific chip. Takes ~30s. Results are persisted.
Requests a manual turbo burst for the specified number of ticks (1 tick = 1 second). The governor will boost to max stable frequency if thermal conditions allow. Automatically enters cooldown afterward. Max burst: 120 ticks.
Updates governor configuration. Supports: tick_ms (governor tick interval), thermal_alpha (EMA smoothing), max_turbo_ticks, cooldown_ticks, and demand holdoff thresholds. Changes take effect on the next tick.
Returns the running firmware version, build target (e.g. arm-unknown-linux-gnueabihf), binary path on disk, and whether browser-mediated upgrade is supported on this platform (Linux only).
Accepts a raw binary upload (Content-Type: application/octet-stream, up to 16 MB). On Linux: validates ELF header, verifies Ed25519 signature if build key is provisioned, atomically replaces the binary, and schedules systemctl restart after 2 seconds.
Returns current firmware version, build target, network connectivity, build key status, and available OTA methods. Used by remote update tooling to determine if the device can receive updates.
Returns recent delta events: each ingest, delete, or compaction operation with timestamp, affected IDs, and epoch. Useful for building incremental sync clients that only fetch changes since a known epoch.
Returns the complete delta history since the agent started. Each entry includes the operation type, affected vector count, epoch before and after, and wall-clock timestamp.
Returns metadata about the current store as a deliverable image: total vectors, dimension, file size, content hash, and epoch. Used by the delivery pipeline to package the store for distribution.
Lists available optimization profiles. Profiles define different compaction strategies and kNN parameters for different workload types.
Lightweight coherence check: returns a simple ratio of live vectors to total capacity, vector count, and a pass/fail health indicator. Faster than the full temporal profile.
Generates and ingests 100 random vectors for testing. Useful for quickly populating the store to test queries, boundary analysis, and temporal coherence without writing a client.
Returns the cognitive container's current state: epoch number, total ticks completed, latest spectral coherence score (SCS), and whether the receipt chain is valid. The container runs a cognitive tick every 30 seconds.
Returns a complete snapshot of the cognitive container: spectral graph edges, accumulated evidence vectors, current SCS scores, slab memory usage, and configuration. Useful for debugging and offline analysis.
Returns the most recent cognitive receipt from the secondary witness chain (SipHash-2-4). Includes the receipt hash, parent hash, tick number, SCS at that tick, and chain verification status.
Returns all retained cognitive receipts (up to max_receipts, default 1000). Each receipt links to the previous via SipHash-2-4, forming a tamper-evident chain independent of the RVF store's XOR/add chain.
Forces an immediate cognitive tick outside the normal 30-second schedule. Computes spectral coherence on the current kNN graph, accumulates evidence, and appends a new receipt to the cognitive witness chain. Useful for testing or after bulk operations.
Returns the cognitive container's configuration: whether it is enabled, tick interval (in optimizer cycles), slab size in bytes, and maximum retained receipts.
Updates the cognitive container configuration. Supports: enabled (bool), tick_every_n_cycles (how often to tick relative to the optimizer loop), slab_size (memory slab in bytes), and max_receipts (receipt chain cap).
Imports vectors from an .rvf file on the filesystem. The file must be placed on the Pi first (via SCP or USB drive). Validates dimension match (rejects with 409 on mismatch) and deduplicates by content hash. Returns imported/rejected counts.
Exports the current vector store as a new .rvf file at the specified path. Only live (non-deleted) vectors are included. The exported file can be imported by another Cognitum Seed or used for backup.
Returns the list of supported import formats (currently .rvf only), the store's current dimension, and total vector count. Use this to verify compatibility before importing.
Returns comprehensive security status: authentication method (pairing/mTLS), witness hash algorithm (sha256), build key presence, rate limiter state, path validation, and boot integrity overview.
Returns whether a build key is configured and the hex-encoded public key. When configured, firmware updates require a valid Ed25519 signature matching this key.
Provision the Ed25519 public key used to verify firmware signatures. Requires both bearer token auth AND localhost access (physical USB). Body: {"public_key_hex":"...64 hex chars..."}. Once set, all OTA updates must be signed with the matching private key.
Opens a 30-second pairing window, replacing the physical button press. Only accessible from localhost (127.0.0.1). After the window opens, call POST /pair to complete pairing.
Returns firmware slot layout (A/B), current active slot, boot count, and whether automatic rollback is available. Part of the sealed appliance (ADR-045) firmware management.
Upload new firmware binary with Ed25519 signature verification. Two modes: (1) detached signature via X-Signature header (hex-encoded), or (2) inline with X-Signed: true header where last 64 bytes are the signature. Writes to inactive slot and reboots.
Returns SHA-256 measurements of boot components (kernel, rootfs, agent binary) for software-based measured boot. Allows verification that the running system matches expected hashes.
Returns vectors added and IDs deleted since the given epoch. Omit since_epoch for a full sync (backward compatible). Response includes is_delta: true, vectors, deletions, and current_epoch.
Push vectors and deletions from a peer device. Accepts vectors, deletions, source_device_id, and source_epoch. Ingests via batch, applies deletions, records peer sync state.
Returns the swarm status: device ID, number of known peers, whether discovery is active, current epoch, total vectors, and uptime.
Returns all known peers with their addresses, last-seen timestamps, and sync state. Alias for /api/v1/peers.
Returns current WiFi connection status, SSID, signal strength, and IP address if connected.
Scans for visible WiFi networks and returns SSIDs, signal strength, and security type. Returns empty list in virtual mode.
Connect to a WiFi network by SSID and password. Requires pairing. On success, the device will be reachable at cognitum.local via mDNS.