{"openapi":"3.0.3","info":{"title":"Syntalium Public API","version":"0.2.0","description":"Public same-origin API endpoints served by the Syntalium website and proxied to the co-located SignalX backend."},"servers":[{"url":"https://syntalium.com"}],"paths":{"/api/healthz":{"get":{"summary":"Service health check","operationId":"getHealthz","tags":["health"],"responses":{"200":{"description":"Service health payload","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"commit":{"type":"string","example":"a1b2c3d"},"time":{"type":"string","format":"date-time"}},"required":["status","time"]}}}}}}},"/api/release":{"get":{"summary":"Deployment provenance","operationId":"getReleaseProvenance","tags":["release"],"responses":{"200":{"description":"Release provenance payload","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string","example":"syntalium-site"},"domain":{"type":"string","example":"syntalium.com"},"commit":{"type":"string","example":"UNKNOWN_OR_SHA"},"branch":{"type":"string","example":"UNKNOWN_OR_NAME"},"buildId":{"type":"string","example":"UNKNOWN_OR_BUILD_ID"},"deployedAtUtc":{"type":"string","format":"date-time"},"runtimeGenerated":{"type":"boolean","example":true},"node":{"type":"string","example":"v20.16.0"}},"required":["service","domain","commit","branch","buildId","deployedAtUtc","runtimeGenerated","node"]}}}}}}},"/api/public/btc":{"get":{"summary":"Hourly BTC market-status contract","description":"Same-origin proxy endpoint that returns the latest published SignalX BTC hourly market-status row and its provenance fields.","operationId":"getPublicBtc","tags":["market"],"responses":{"200":{"description":"SignalX BTC hourly market-status payload","content":{"application/json":{"schema":{"properties":{"symbol":{"type":"string","example":"BTCUSDT"},"timeframe":{"type":"string","example":"1h"},"price":{"type":"number","example":67321.12},"timestamp_utc":{"type":"string","format":"date-time"},"market_state":{"type":"string","enum":["CLEAR","TENSE","WAIT","NO-TRADE","UNKNOWN"],"example":"WAIT"},"snap_id":{"type":"string","example":"2b5a02298029268847b0e73305f6fab07e3e102fa68fc9fe146f0f5724ffd52b"},"reasons":{"type":"array","items":{"type":"string"}},"key_metrics":{"type":"object","additionalProperties":true},"status_source":{"type":"string","example":"published_snapshots.payload_v2_json"},"status_selection_mode":{"type":"string","example":"classified_hourly_status"},"publish_kind":{"type":"string","example":"btc_hourly_status"},"publish_role":{"type":"string","example":"btc_hourly_free_visual"},"status_channel_id":{"type":"string","example":"free"},"published_at_utc":{"type":"string","format":"date-time"}},"required":["symbol","timeframe","timestamp_utc","market_state","snap_id","reasons","key_metrics","status_source","status_selection_mode","publish_kind","publish_role","status_channel_id","published_at_utc"]}}}},"502":{"description":"Upstream returned malformed or empty payload"},"503":{"description":"SignalX backend unavailable"}}}},"/api/public/markets":{"get":{"summary":"All tracked assets for one timeframe","description":"Same-origin proxy endpoint that returns closed-candle price, 24h change, market condition, and Syntalium Index summary for every tracked asset on one timeframe.","operationId":"getPublicMarkets","tags":["market"],"parameters":[{"name":"timeframe","in":"query","required":false,"schema":{"type":"string","enum":["15m","1h","4h","1d"],"default":"1h"},"description":"Candle timeframe. Defaults to 1h if omitted."}],"responses":{"200":{"description":"Per-asset market summary list for the requested timeframe","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"timeframe":{"type":"string","example":"1h"},"assets":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"symbol":{"type":"string","example":"BTCUSDT"},"latest_close":{"type":"number","nullable":true,"example":64784.7},"change_24h_pct":{"type":"number","nullable":true,"example":3.49},"market_state":{"type":"string","enum":["CLEAR","TENSE","WAIT","NO-TRADE","UNKNOWN"],"example":"NO-TRADE"},"index_score_0_100":{"type":"number","nullable":true,"example":46},"index_readiness":{"type":"string","example":"READY"},"freshness_status":{"type":"string","example":"FRESH"}}}}}}}}},"502":{"description":"Upstream returned malformed or empty payload"},"503":{"description":"Syntalium backend unavailable"}}}},"/api/public/market-dna":{"get":{"summary":"Per-asset Market DNA metrics","description":"Same-origin proxy endpoint that returns the decision-time-frozen Market DNA metrics (entropy, flow delta, taker ratio, trend strength, volume z-score, ATR%, BTC correlation), the derived market condition, and SNAP provenance for one exact symbol + timeframe. Never falls back to another asset's data: an unavailable combination returns an honest UNAVAILABLE status with null metrics, not another symbol's values.","operationId":"getPublicMarketDna","tags":["market-dna"],"parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string","example":"BTCUSDT"},"description":"Tracked asset symbol, e.g. BTCUSDT, ETHUSDT, SUIUSDT."},{"name":"timeframe","in":"query","required":true,"schema":{"type":"string","enum":["15m","1h","4h","1d"]},"description":"Candle timeframe."}],"responses":{"200":{"description":"Market DNA payload for the requested symbol + timeframe","content":{"application/json":{"schema":{"type":"object","properties":{"symbol":{"type":"string","example":"BTCUSDT"},"timeframe":{"type":"string","example":"1h"},"status":{"type":"string","enum":["AVAILABLE","PARTIAL","UNAVAILABLE"],"description":"AVAILABLE: all metrics present. PARTIAL: some metrics missing. UNAVAILABLE: no snapshot_metrics record exists yet for this symbol/timeframe.","example":"AVAILABLE"},"as_of_utc":{"type":"string","format":"date-time","nullable":true},"timestamp_ms":{"type":"number","nullable":true,"example":1752492300000},"age_seconds":{"type":"number","nullable":true,"example":300},"metrics":{"type":"object","description":"Any field may be null when that specific metric is not available. Values are never fabricated to fill a gap.","properties":{"entropy":{"type":"number","nullable":true,"example":0.8627},"flow_delta":{"type":"number","nullable":true,"example":-0.9075},"taker_ratio":{"type":"number","nullable":true,"example":0.52},"trend_strength":{"type":"number","nullable":true,"example":0.9453},"vol_z":{"type":"number","nullable":true,"example":-0.0468},"atr_pct":{"type":"number","nullable":true,"example":0.0057},"btc_corr":{"type":"number","nullable":true,"example":0.7867}},"required":["entropy","flow_delta","taker_ratio","trend_strength","vol_z","atr_pct","btc_corr"]},"market_condition":{"type":"object","properties":{"status":{"type":"string","enum":["CLEAR","TENSE","WAIT","NO-TRADE","UNKNOWN"],"example":"NO-TRADE"},"reason_codes":{"type":"array","items":{"type":"string"},"example":["ENTROPY_HIGH","ATR_OK","TREND_WEAK"]}},"required":["status","reason_codes"]},"snap":{"type":"object","properties":{"published_snapshot_found":{"type":"boolean","example":false},"snap_id":{"type":"string","nullable":true},"verify_path":{"type":"string","nullable":true,"description":"Backend verify API path. The public site builds its own /verify?snap_id=... page link rather than using this field directly."}},"required":["published_snapshot_found","snap_id","verify_path"]},"provenance":{"type":"object","properties":{"source_table":{"type":"string","example":"snapshot_metrics"},"decision_time_safe":{"type":"boolean","nullable":true,"description":"True when the metrics were frozen at snapshot creation time, not recomputed live."}},"required":["source_table","decision_time_safe"]}},"required":["symbol","timeframe","status","metrics","market_condition","snap","provenance"]}}}},"400":{"description":"Missing or invalid symbol/timeframe"}}}},"/api/public/stats":{"get":{"summary":"Signal activity stats snapshot","description":"Same-origin proxy endpoint for SignalX public stats.","operationId":"getPublicStats","tags":["stats"],"responses":{"200":{"description":"SignalX stats payload","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"signals_24h":{"type":"object","properties":{"signal_count":{"type":"number","example":14}}},"signals_all_time":{"type":"object","properties":{"signal_count":{"type":"number","example":998}}},"win_rate_24h":{"type":"object","additionalProperties":true},"win_rate_all_time":{"type":"object","additionalProperties":true},"open_positions":{"type":"number","example":3},"closed_positions":{"type":"number","example":7},"snapshot_stats":{"type":"object","properties":{"snapshot_count":{"type":"number","example":2230}}},"runtime_activity_summary":{"type":"object","additionalProperties":true}}}}}},"502":{"description":"Upstream returned malformed or empty payload"},"503":{"description":"SignalX backend unavailable"}}}},"/api/public/signals":{"get":{"summary":"Published signal lifecycle records","description":"Same-origin proxy endpoint for the public signal lifecycle feed (open/close events, proof status). Not a win-rate or PnL summary.","operationId":"getPublicSignals","tags":["signals"],"parameters":[{"name":"symbol","in":"query","required":false,"schema":{"type":"string","example":"BTCUSDT"},"description":"Optional symbol filter."},{"name":"timeframe","in":"query","required":false,"schema":{"type":"string","enum":["15m","1h","4h","1d"]},"description":"Optional timeframe filter."}],"responses":{"200":{"description":"Signal lifecycle records","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"count":{"type":"number","example":12},"signals":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"symbol":{"type":"string","example":"BTCUSDT"},"timeframe":{"type":"string","example":"1h"},"side":{"type":"string","nullable":true,"example":"LONG"},"status":{"type":"string","nullable":true},"snap_id":{"type":"string","nullable":true},"decision_proof_status":{"type":"string","nullable":true},"outcome_proof_status":{"type":"string","nullable":true}}}}}}}}},"502":{"description":"Upstream returned malformed or empty payload"},"503":{"description":"Syntalium backend unavailable"}}}},"/api/public/index":{"get":{"summary":"Syntalium Index history","description":"Same-origin proxy endpoint for the Syntalium Index point series for one symbol + timeframe. Only READY, non-interpolated points are included.","operationId":"getPublicIndex","tags":["market"],"parameters":[{"name":"symbol","in":"query","required":false,"schema":{"type":"string","example":"BTCUSDT"}},{"name":"timeframe","in":"query","required":false,"schema":{"type":"string","enum":["15m","1h","4h","1d"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"number","example":80},"description":"Maximum number of points to return."}],"responses":{"200":{"description":"Syntalium Index point series","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"points":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"timestamp_ms":{"type":"number","example":1752492300000},"index_score_0_100":{"type":"number","example":46},"index_status":{"type":"string","enum":["READY","BUILDING_CLEAN_HISTORY"],"example":"READY"}}}}}}}}},"502":{"description":"Upstream returned malformed or empty payload"},"503":{"description":"Syntalium backend unavailable"}}}},"/api/verify":{"get":{"summary":"Verify snapshot by query string","description":"Primary verify endpoint. The site proxy preserves SignalX verify statuses and HTTP codes without local reinterpretation.","operationId":"getVerifyByQuery","tags":["verify"],"parameters":[{"name":"snap_id","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9:_-]{1,128}$"},"description":"Snapshot identifier."}],"responses":{"200":{"description":"Verification payload from SignalX","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["VERIFIED","MISMATCH","NOT_FOUND","PAYLOAD_MISSING","INVALID_REQUEST"],"example":"VERIFIED"},"snap_id":{"type":"string","example":"2b5a02298029268847b0e73305f6fab07e3e102fa68fc9fe146f0f5724ffd52b"},"expected_sha256":{"type":"string","example":"2b5a02298029268847b0e73305f6fab07e3e102fa68fc9fe146f0f5724ffd52b"},"computed_sha256":{"type":"string","example":"2b5a02298029268847b0e73305f6fab07e3e102fa68fc9fe146f0f5724ffd52b"},"payload_present":{"type":"boolean","example":true},"evidence_present":{"type":"boolean","example":true},"verification_reason":{"type":"string","example":"snap_hash_match"},"symbol":{"type":"string","example":"BTCUSDT"},"timeframe":{"type":"string","example":"1h"},"timestamp_ms":{"type":"number","example":1700000000000},"timestamp_utc":{"type":"string","format":"date-time"},"hash_algo":{"type":"string","example":"sha256"},"snap_version":{"type":"number","example":3}},"required":["status","snap_id","expected_sha256","computed_sha256","payload_present","evidence_present","verification_reason","symbol","timeframe","timestamp_utc","hash_algo","snap_version"]}}}},"400":{"description":"Invalid request as returned by SignalX"},"502":{"description":"Upstream returned malformed or empty payload"},"503":{"description":"SignalX backend unavailable"}}}},"/api/verify/{snap_id}":{"get":{"summary":"Verify snapshot by path (compatibility alias)","description":"Path-style alias for compatibility. Internally maps to /api/verify?snap_id=<id>.","operationId":"getVerifyBySnapId","tags":["verify"],"parameters":[{"name":"snap_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9:_-]{1,128}$"},"description":"Snapshot identifier."}],"responses":{"200":{"description":"Verification payload from SignalX","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid snap_id format"},"502":{"description":"Upstream returned malformed or empty payload"},"503":{"description":"SignalX backend unavailable"}},"x-status":"compatibility-alias"}},"/api/market/btc":{"get":{"summary":"Legacy placeholder endpoint","description":"Legacy contract retained for backward compatibility.","operationId":"getMarketBtc","tags":["market"],"responses":{"501":{"description":"Legacy placeholder response"}}}}}}