{ "openapi": "3.0.3", "info": { "title": "FinanceSec API Reference", "version": "0.4.0", "description": "Deterministic SEC EDGAR fact and quantitative risk API. No LLM in the fact path. Numeric claims come from lattice recall with provenance, or an honest `SAFE_REFUSAL`.\n\n**Agent ingest:** [llms.txt](/llms.txt) · **MCP:** https://finsec.caleralabs.com/mcp · **Keys:** https://dashboard.caleralabs.com/dashboard?domain=finsec\n\n## Auth\nHeader `X-License-Key`. Every authenticated request counts as one quota unit. HTTP 429 means the current tier is exhausted.\n\n## Surface\n- `POST /api/query` — natural-language SEC facts. Optional `low_tokens` for compact JSON.\n- `POST /api/packs/valuation-inputs` — 12 EDGAR-only valuation packs.\n- `POST /v1/finsec/scenario/stress-test` — multi-regime portfolio stress.\n- `POST /v1/finsec/firewall/verify-payload` — verify LLM financial text.\n- `POST /v1/finsec/hft/verify-route` — pre-trade child-order gate (sub-500µs). HTTP 422 if refused.\n- `POST /v1/hft/arbitrage/validate`, `POST /v1/hft/liquidity/betti`, `POST /v1/hft/orderbook/settle` — microstructure.\n- `POST /api/watchlist/{cik}` — real-time filing ingest (Startup+).\n\n## Primary MCP Tool Schema\n```json\n{\n \"name\": \"query_financial_sec\",\n \"version\": \"1.2.0\",\n \"description\": \"Certified SEC fact query. Returns verified values with provenance or SAFE_REFUSAL. Does not invent numbers. Treat SAFE_REFUSAL as success-of-honesty, not a tool failure. Monetary answers default to the filer's reporting currency; request FX conversion via target_currency / usd_only or natural-language 'in USD'.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"query\": {\n \"type\": \"string\",\n \"description\": \"Natural language financial question. Append 'in USD' (or another supported ISO code) to convert foreign reporting currencies after verified recall.\"\n },\n \"target_currency\": {\n \"type\": \"string\",\n \"description\": \"Optional ISO 4217 code (e.g. USD, EUR) for post-recall FX conversion using audited annual-average rates. Provenance records original_unit, fx_rate, and fx_converted.\"\n },\n \"usd_only\": {\n \"type\": \"boolean\",\n \"description\": \"When true, forces monetary answers into USD.\"\n }\n },\n \"required\": [\n \"query\"\n ]\n },\n \"annotations\": {\n \"title\": \"Query Certified SEC Facts\",\n \"readOnlyHint\": true\n }\n}\n```\n\nTreat `SAFE_REFUSAL` as success-of-honesty. Do not invent numbers." }, "servers": [ { "url": "https://financesec.api.caleralabs.com", "description": "Production API Server" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/api/health": { "get": { "summary": "Check API health", "operationId": "checkApiHealth", "description": "Returns the current health status, version, port, system timestamp, and TTND stage breakdown per CIK (Freshness SLA: \u226430m p95).", "security": [], "responses": { "200": { "description": "API is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/api/watchlist/{cik}": { "post": { "summary": "Register CIK for real-time monitoring and pre-warming", "operationId": "addWatchlistCIK", "description": "Registers a CIK for real-time SEC filing detection, priority queue processing, and lattice pre-warming (Freshness SLA: \u226430m p95).", "security": [], "parameters": [ { "name": "cik", "in": "path", "description": "10-digit zero-padded SEC Central Index Key (CIK)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CIK successfully registered for RT pipeline", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "cik": { "type": "string", "example": "0000320193" }, "rt_active": { "type": "boolean", "example": true }, "prewarmed": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "CIK 0000320193 registered for RT pipeline and pre-warming initiated" } } } } } } } } }, "/api/companies": { "get": { "summary": "Retrieve supported companies", "operationId": "getCompanies", "description": "Get the list of all supported companies in the SEC EDGAR universe. Can be filtered by query prefix.", "security": [], "parameters": [ { "name": "q", "in": "query", "description": "Optional search prefix matching ticker or company name", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of companies", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } } } } } } }, "/api/tiers": { "get": { "summary": "Get subscription tiers comparison", "operationId": "getTiers", "description": "Returns pricing, support, SLA, and feature configurations for all FinanceSec subscription tiers.", "security": [], "responses": { "200": { "description": "Subscription tiers information", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TierComparisonEntry" } } } } } } } }, "/api/stats": { "get": { "summary": "Get API statistics", "operationId": "getStats", "description": "Returns active metrics on answer rates, known companies count, coverage indices, and diagnostic run hashes.", "responses": { "200": { "description": "Diagnostic and operational statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsResponse" } } } }, "402": { "description": "License Key Required" }, "429": { "description": "Rate limit exceeded" } } } }, "/api/query": { "post": { "summary": "Submit single SEC query", "operationId": "submitQuery", "description": "Queries the VLN lattice for factual answers to questions regarding SEC 10-K, 10-Q, and 8-K filings.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" } } } }, "responses": { "200": { "description": "Query response containing grounding results or Refusal metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" } } } }, "402": { "description": "License Required" }, "429": { "description": "Rate Limit Reached" } } } }, "/api/packs/valuation-inputs": { "post": { "summary": "Retrieve valuation-inputs pack", "operationId": "getValuationInputsPack", "description": "Returns structured, EDGAR-certified valuation input cells and compositions for the specified company, period, and pack enum. EDGAR-only scope; excludes market price multiples (P/E, trading EV) and macro indicators (Buffett Indicator).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValuationPackRequest" } } } }, "responses": { "200": { "description": "Valuation pack response payload with cell & composition provenance and EDGAR-only disclaimer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValuationPackResponse" } } } }, "402": { "description": "License Required" } } } }, "/api/provenance/{id}": { "get": { "summary": "Retrieve fact provenance", "operationId": "getProvenance", "description": "Fetch detailed provenance trace and verification hashes for a specific grounded entity fact.", "parameters": [ { "name": "id", "in": "path", "description": "Unique ID of the provenance record", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Provenance details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvenanceResponse" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Provenance record not found" } } } }, "/api/trends": { "get": { "summary": "Get multi-year financial trends", "operationId": "getTrends", "description": "Collects multi-year comparative lists of core metrics (Revenue, Net Income, and Operating Margins) for a company.", "parameters": [ { "name": "company", "in": "query", "description": "Ticker symbol of the target company", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trends datasets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrendsResponse" } } } }, "401": { "description": "Unauthorized" } } } }, "/api/batch": { "post": { "summary": "Submit async batch job", "operationId": "submitBatchJob", "description": "Queue up to 100 queries for background processing. Available for Professional and Enterprise tiers only.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" } } } }, "responses": { "202": { "description": "Batch job queued successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchJob" } } } }, "400": { "description": "Invalid batch payload or batch size exceeded" }, "401": { "description": "Unauthorized" }, "403": { "description": "Endpoint access forbidden for active tier" } } } }, "/api/batch/{batch_id}": { "get": { "summary": "Retrieve batch status and results", "operationId": "getBatchJob", "description": "Check current status and download query results of a queued batch processing job.", "parameters": [ { "name": "batch_id", "in": "path", "description": "Unique identifier of the submitted batch job", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch job details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchJob" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Batch job not found" } } } }, "/api/xbrl/ingest": { "post": { "summary": "Ingest custom XBRL filings", "description": "Allows Enterprise customers to upload and ingest custom SEC-style XBRL filings to build/query their private lattice instance.", "operationId": "ingestCustomXbrl", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XbrlIngestRequest" } } } }, "responses": { "200": { "description": "Filing ingested successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XbrlIngestResponse" } } } }, "202": { "description": "Filing upload accepted for asynchronous ingestion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XbrlIngestResponse" } } } }, "400": { "description": "Invalid payload or parsing failure" }, "401": { "description": "Unauthorized" }, "403": { "description": "Endpoint access forbidden for active tier" } } } }, "/api/keys": { "get": { "summary": "List API keys", "description": "Returns all API keys associated with the user's organization.", "operationId": "listApiKeys", "responses": { "200": { "description": "A list of API keys" } } }, "post": { "summary": "Create API key", "description": "Generates a new API key for the organization.", "operationId": "createApiKey", "responses": { "201": { "description": "API key created" } } } }, "/api/webhooks": { "get": { "summary": "List webhook endpoints", "description": "Returns all registered webhook endpoints for the organization.", "operationId": "listWebhooks", "responses": { "200": { "description": "A list of webhook endpoints" } } }, "post": { "summary": "Create webhook endpoint", "description": "Registers a new webhook endpoint for event notifications.", "operationId": "createWebhook", "responses": { "201": { "description": "Webhook endpoint created" } } } }, "/api/audit/export": { "get": { "summary": "Export audit logs", "description": "Downloads the organization audit trail in JSON Lines format.", "operationId": "exportAuditLogs", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Exported audit logs" } } } }, "/api/org/create": { "post": { "summary": "Create organization", "description": "Creates a new multi-seat organization.", "operationId": "createOrg", "responses": { "201": { "description": "Organization created" } } } }, "/v1/finsec/scenario/stress-test": { "post": { "summary": "Multi-regime portfolio stress test", "operationId": "scenarioStressTest", "description": "Stress portfolio positions across superposed macro regimes. Returns covenant breach flags and SEC filing provenance per holding. List regimes via GET /api/regime/scenarios.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScenarioStressTestRequest" } } } }, "responses": { "200": { "description": "Scenario stress test execution completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScenarioStressTestResponse" } } } } } } }, "/v1/finsec/firewall/verify-payload": { "post": { "summary": "Verify LLM financial text against the lattice", "operationId": "firewallVerifyPayload", "description": "Intercept generated financial text. If hallucination_detected is true, use verified_payload and persist audit_trail_sha256. compliance_strictness: FAIL_CLOSED | STRICT | PERMISSIVE.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirewallVerifyRequest" } } } }, "responses": { "200": { "description": "Verification results with provenance corrections and audit trail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirewallVerifyResponse" } } } } } } }, "/v1/finsec/hft/verify-route": { "post": { "summary": "Pre-trade HFT route certification", "operationId": "hftVerifyRoute", "description": "Certify a child order before it hits the matching engine. Execute only if status is APPROVED. HTTP 422 if REFUSED. Solver SLA < 500\u00b5s. Aliases: /v1/hft/verify-route.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HftVerifyRouteRequest" } } } }, "responses": { "200": { "description": "Route certification stability verdict with recommended split", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HftVerifyRouteResponse" } } } }, "422": { "description": "Route refused \u2014 do not send the child order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HftVerifyRouteResponse" } } } } } } }, "/v1/hft/arbitrage/validate": { "post": { "summary": "Cross-venue arbitrage validation", "operationId": "hftValidateArbitrage", "description": "Evaluate cross-venue mid-price loops. Read arbitrage_executable, gross_spread_bps, net_arbitrage_bps.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HftArbitrageRequest" } } } }, "responses": { "200": { "description": "Arbitrage validation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HftArbitrageResponse" } } } } } } }, "/v1/hft/liquidity/betti": { "post": { "summary": "Liquidity topology (Betti numbers)", "operationId": "hftLiquidityBetti", "description": "Persistent-homology liquidity invariants for a symbol. Also accepts GET ?symbol=.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "symbol": { "type": "string", "example": "NVDA" } } } } } }, "responses": { "200": { "description": "Betti / spectral-gap snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HftLiquidityBettiResponse" } } } } } } }, "/v1/hft/orderbook/settle": { "post": { "summary": "Settle an order-book snapshot", "operationId": "hftSettleOrderBook", "description": "Hopfield well settlement on a venue book. Empty body uses the engine fallback book.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderBookSnapshot" } } } }, "responses": { "200": { "description": "Settled book with support/resistance wells", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HftSettleResponse" } } } } } } }, "/api/regime/scenarios": { "get": { "summary": "List stress-test regimes", "operationId": "listRegimeScenarios", "description": "Available superposition regime identifiers for POST /v1/finsec/scenario/stress-test.", "security": [], "responses": { "200": { "description": "Regime catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "example": 3 }, "scenarios": { "type": "array", "items": { "type": "string" } } } } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-License-Key", "description": "FinanceSec license key. Create keys at https://dashboard.caleralabs.com/dashboard?domain=finsec" } }, "schemas": { "ValuationPackRequest": { "type": "object", "required": [ "company", "period", "pack" ], "properties": { "company": { "type": "string", "example": "AAPL" }, "period": { "type": "string", "example": "FY2023" }, "pack": { "type": "string", "enum": [ "equity_screen", "ev_bridge", "quality_of_earnings", "segment_mix", "returns_screen", "leverage_screen", "piotroski_f", "altman_z_prime", "beneish_m_score", "dupont_5step", "working_capital_efficiency", "dcf_valuation_inputs" ], "example": "leverage_screen" } } }, "ValuationPackResponse": { "type": "object", "properties": { "pack_id": { "type": "string", "example": "leverage_screen" }, "company": { "type": "string", "example": "AAPL" }, "period": { "type": "string", "example": "FY2023" }, "pack_status": { "type": "string", "enum": [ "COMPLETE", "PARTIAL", "DEADLINE" ], "example": "COMPLETE" }, "cells": { "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string" }, "status": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" }, "provenance": { "type": "object", "properties": { "accession": { "type": "string" }, "xbrl_concept": { "type": "string" }, "audit_hash": { "type": "string" } } }, "reason": { "type": "string" } } } }, "compositions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "value": {}, "formatted": { "type": "string" }, "reason": { "type": "string" }, "provenance": { "type": "object", "properties": { "accession": { "type": "string" }, "xbrl_concept": { "type": "string" }, "audit_hash": { "type": "string" } } } } } }, "disclaimer": { "type": "string", "example": "Market price, trading EV, P/E, and macro gauges (e.g. Buffett Indicator) are not provided by FINSEC. Packs are EDGAR-certified inputs only." } } }, "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "domain": { "type": "string", "example": "Calera FinanceSec \u2014 SEC Filing QA" }, "version": { "type": "string", "example": "v0.1.10" }, "api_version": { "type": "string", "example": "v0.1.10" }, "platform_version": { "type": "string", "example": "v0.3.2" }, "port": { "type": "string", "example": "8080" }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-07-09T23:02:04Z" }, "ttnd_breakdown": { "type": "object", "description": "Per-CIK TTND stage latency breakdown and total detect-to-materialize timing", "additionalProperties": { "type": "object", "properties": { "cik": { "type": "string", "example": "0000320193" }, "accession": { "type": "string", "example": "0000320193-26-000013" }, "detected_at": { "type": "string", "format": "date-time" }, "queued_at": { "type": "string", "format": "date-time" }, "fetched_at": { "type": "string", "format": "date-time" }, "trained_at": { "type": "string", "format": "date-time" }, "visible_at": { "type": "string", "format": "date-time" }, "total_ttnd_ms": { "type": "integer", "example": 240000 } } } } } }, "Company": { "type": "object", "properties": { "ticker": { "type": "string", "example": "MMM" }, "name": { "type": "string", "example": "3M" }, "sector": { "type": "string", "example": "Industrials" } } }, "TierComparisonEntry": { "type": "object", "properties": { "id": { "type": "string", "example": "professional" }, "name": { "type": "string", "example": "Professional" }, "price": { "type": "string", "example": "$5000/mo" }, "queriesPerDay": { "type": "integer", "example": 5000 }, "filings": { "type": "array", "items": { "type": "string" }, "example": [ "10-K", "10-Q", "8-K" ] }, "conns": { "type": "integer", "example": 10 }, "audit": { "type": "integer", "example": 90 }, "sla": { "type": "string", "example": "99.95%" }, "support": { "type": "string", "example": "Slack + Email" }, "color": { "type": "string", "example": "#ef5350" } } }, "StatsResponse": { "type": "object", "properties": { "lattice_coverage_index": { "type": "number", "format": "float", "example": 0.95 }, "training_ms": { "type": "integer", "example": 120 }, "fixture_items": { "type": "integer", "example": 150 }, "known_companies": { "type": "integer", "example": 10000 }, "version": { "type": "string", "example": "v0.1.2" }, "domain_version": { "type": "string", "example": "v0.1.2" }, "answer_rate_pct": { "type": "number", "format": "float", "description": "Accuracy percentage on the FinanceBench 150-question evaluation benchmark set.", "example": 92.0 }, "correct_count": { "type": "integer", "example": 150 }, "total_questions": { "type": "integer", "example": 150 }, "segment_dimension_support": { "type": "boolean", "example": true }, "quarterly_10q_support": { "type": "boolean", "example": true }, "novel_nlu_categories": { "type": "integer", "example": 5 }, "domain_relevant_detectors": { "type": "integer", "example": 14 }, "battery_sha256": { "type": "string", "example": "d222effd29c2..." }, "answerRate": { "type": "number", "format": "float", "description": "Overall answer rate float (0.0 to 1.0) across all incoming queries including safety refusals.", "example": 0.793 }, "total_queries": { "type": "integer", "example": 250 } } }, "QueryRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "The natural language query about SEC filings.", "example": "WiMi Hologram Cloud Inc. net income 2025" }, "target_currency": { "type": "string", "description": "Optional ISO 4217 target currency code (e.g. 'USD') to convert foreign reporting currencies.", "example": "USD" }, "currency": { "type": "string", "description": "Alias for target_currency.", "example": "USD" }, "usd_only": { "type": "boolean", "description": "When true, forces response values to be output in USD.", "example": true }, "low_tokens": { "type": "boolean", "description": "When true, returns compact JSON (MCP and compact REST). Serializer only \u2014 not a second engine.", "example": true } } }, "QueryResponse": { "type": "object", "properties": { "query_id": { "type": "string", "example": "q_000181" }, "status": { "type": "string", "enum": [ "VERIFIED_SUCCESS", "TENTATIVE_MATCH", "SAFE_REFUSAL", "EVENT_ACK_PENDING_FACTS", "EARNINGS_DAY_EMPTY", "OUT_OF_UNIVERSE", "SCHEDULE_NOT_IN_ONTOLOGY", "FILING_EVENT_SET" ], "example": "VERIFIED_SUCCESS", "description": "EVENT_ACK_PENDING_FACTS: 8-K Item 2.02 seen; certified metrics pending (see filing_event). EARNINGS_DAY_EMPTY / OUT_OF_UNIVERSE / SCHEDULE_NOT_IN_ONTOLOGY: typed honest silences (UX-SILENCE-TYPED-1). FILING_EVENT_SET: EDGAR-observed earnings-day set recall (Class B)." }, "source": { "type": "string", "enum": [ "LATTICE_RECALL", "ANALYTICAL_GATE", "TEMPORAL_GATE", "ENTITY_GATE", "CONFIDENCE_GATE", "FILING_EVENT_GATE", "CAPABILITY_GATE", "COVERAGE_GATE", "ONTOLOGY_GATE" ], "example": "LATTICE_RECALL" }, "coverage": { "type": "object", "description": "Public coverage bound for earnings-day answers and typed silences. Never implies full-market calendar coverage.", "properties": { "universe_description": { "type": "string", "example": "Cohort0 + active watchlists" }, "universe_size": { "type": "integer", "example": 12 }, "model_generation": { "type": "integer", "example": 7 }, "promoted_at": { "type": "string", "format": "date-time", "example": "2026-07-24T15:00:00Z" } } }, "answer": { "type": "object", "properties": { "value": { "type": "number", "example": 1577 }, "unit": { "type": "string", "example": "USD" }, "formatted": { "type": "string", "example": "$1,577.00" } } }, "filing_event": { "type": "object", "description": "Structured 8-K event metadata (Item codes from SEC submissions). Present on EVENT_ACK_PENDING_FACTS. Never contains invented monetary values.", "properties": { "form_type": { "type": "string", "example": "8-K" }, "items": { "type": "array", "items": { "type": "string" }, "example": [ "2.02", "9.01" ] }, "event_type": { "type": "string", "example": "earnings_release" }, "event_types": { "type": "array", "items": { "type": "string" }, "example": [ "earnings_release", "exhibit_filing" ] }, "cik": { "type": "string", "example": "0001652044" }, "ticker": { "type": "string", "example": "GOOGL" }, "accession": { "type": "string", "example": "0001652044-26-000066" }, "filing_date": { "type": "string", "example": "2026-07-22" }, "next_check": { "type": "string", "example": "companyfacts_or_10q" } } }, "confidence_score": { "type": "number", "format": "float", "example": 1 }, "method": { "type": "string", "example": "FuzzyAnswerLookup" }, "provenance": { "type": "object", "properties": { "entity_id": { "type": "string", "example": "fin:3M_3M_2018_10K" }, "source_filing": { "type": "string", "example": "fin:3M_2018_10K" }, "company": { "type": "string", "example": "3M" }, "xbrl_concept": { "type": "string", "example": "us-gaap:PaymentsToAcquirePropertyPlantAndEquipment" }, "doc_period": { "type": "string", "example": "FY2018" }, "audit_hash": { "type": "string", "example": "452b9177..." }, "original_value": { "type": "string", "description": "Formatted reporting-currency value before FX conversion.", "example": "\u00a51843388870.00 CNY" }, "original_unit": { "type": "string", "description": "ISO reporting currency before FX conversion.", "example": "CNY" }, "fx_rate": { "type": "string", "description": "Audited annual-average FX rate applied at inference time.", "example": "1 CNY = 0.1389 USD" }, "fx_converted": { "type": "boolean", "description": "True when the answer was converted from the filer's reporting currency.", "example": true } } }, "decomposition": { "type": "object", "properties": { "steps": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "example": "Gross Profit" }, "value": { "type": "string", "example": "$8,156M" } } } }, "operator": { "type": "string", "example": "\u00f7" }, "result": { "type": "string", "example": "12.50%" } } }, "reason": { "type": "string", "description": "Human-readable refusal, typed silence, or pending-facts explanation. EVENT_ACK_PENDING_FACTS and UX-SILENCE-TYPED-1 classes use fixed product copy (not scraped from press HTML).", "example": "No crystallized evidence for this query." } } }, "ProvenanceResponse": { "type": "object", "properties": { "entity_id": { "type": "string", "example": "fin:3M_3M_2018_10K" }, "source_filing": { "type": "string", "example": "fin:3M_2018_10K" }, "xbrl_concept": { "type": "string", "example": "us-gaap:PaymentsToAcquirePropertyPlantAndEquipment" }, "company": { "type": "string", "example": "3M" }, "doc_period": { "type": "string", "example": "FY2018" }, "document_location": { "type": "object", "properties": { "page": { "type": "integer", "example": 45 } } }, "audit_hash": { "type": "string", "example": "452b9177..." } } }, "TrendsResponse": { "type": "object", "properties": { "company": { "type": "string", "example": "3M" }, "revenue": { "type": "array", "items": { "type": "number" }, "example": [ 32184, 34229, 34268 ] }, "netIncome": { "type": "array", "items": { "type": "number" }, "example": [ 5349, 5821, 5777 ] }, "opMargin": { "type": "array", "items": { "type": "number" }, "example": [ 21.4, 22, 20.8 ] }, "periods": { "type": "array", "items": { "type": "string" }, "example": [ "FY2021", "FY2022", "FY2023" ] } } }, "BatchRequest": { "type": "object", "required": [ "queries" ], "properties": { "queries": { "type": "array", "items": { "type": "string" }, "example": [ "What is Tesla's FY22 gross margin?", "What is Amazon's FY23 operating margin?" ] } } }, "BatchJob": { "type": "object", "properties": { "batch_id": { "type": "string", "example": "batch_abc123" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ], "example": "COMPLETED" }, "total_queries": { "type": "integer", "example": 2 }, "processed_queries": { "type": "integer", "example": 2 }, "queries": { "type": "array", "items": { "type": "string" }, "example": [ "What is Tesla's FY22 gross margin?", "What is Amazon's FY23 operating margin?" ] }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/QueryResponse" } }, "created_at": { "type": "string", "format": "date-time", "example": "2026-07-09T23:00:00Z" }, "completed_at": { "type": "string", "format": "date-time", "example": "2026-07-09T23:01:00Z" }, "error": { "type": "string", "example": "None" } } }, "XbrlIngestRequest": { "type": "object", "required": [ "ticker", "company_name", "filing_type", "xbrl_data" ], "properties": { "ticker": { "type": "string", "description": "The ticker symbol of the company.", "example": "AAPL" }, "company_name": { "type": "string", "description": "The full name of the company.", "example": "Apple Inc." }, "filing_type": { "type": "string", "enum": [ "10-K", "10-Q", "8-K" ], "description": "The type of filing.", "example": "10-K" }, "fiscal_year": { "type": "string", "description": "The fiscal year for the filing.", "example": "2025" }, "xbrl_data": { "type": "string", "description": "Base64-encoded XML or raw XBRL JSON payload.", "example": "..." } } }, "XbrlIngestResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "INGESTED" }, "job_id": { "type": "string", "example": "job_xbrl_183204" }, "companies_added": { "type": "integer", "example": 1 } } }, "ScenarioStressTestRequest": { "type": "object", "required": [ "portfolio_id", "positions", "macro_shock_vector", "superposition_regimes" ], "properties": { "portfolio_id": { "type": "string", "example": "global_credit_fund_alpha" }, "positions": { "type": "array", "items": { "type": "object", "required": [ "ticker", "exposure_usd" ], "properties": { "ticker": { "type": "string", "example": "ORCL" }, "exposure_usd": { "type": "number", "example": 50000000 } } } }, "macro_shock_vector": { "type": "object", "properties": { "us10y_yield_delta_bps": { "type": "number", "example": 150 }, "wti_crude_oil_pct": { "type": "number", "example": 25.0 }, "us_dollar_index_delta_pct": { "type": "number", "example": 4.5 }, "credit_spread_widening_bps": { "type": "number", "example": 85 } } }, "superposition_regimes": { "type": "array", "items": { "type": "string" }, "example": [ "regime:basin:stagflation_2026", "regime:basin:liquidity_crisis", "regime:basin:baseline_soft_landing" ] } } }, "ScenarioStressTestResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "COMPLETED" }, "solver_latency_ms": { "type": "number", "example": 3.42 }, "zero_hallucination_proof": { "type": "string", "example": "a4_hodge_betti_certified_d222eff" }, "portfolio_summary": { "type": "object", "properties": { "weighted_interest_expense_surge_usd": { "type": "number", "example": 12840000 }, "covenant_breach_risk_score": { "type": "number", "example": 0.742 }, "most_vulnerable_holding": { "type": "string", "example": "ORCL" }, "vulnerability_rationale": { "type": "string", "example": "Floating rate debt ratio is 42.8% per 2025 10-K p.64, exceeding peer median (18.2%)." } } }, "position_stress_breakdown": { "type": "array", "items": { "type": "object", "properties": { "ticker": { "type": "string", "example": "ORCL" }, "metric_evaluated": { "type": "string", "example": "Interest Coverage Ratio" }, "baseline_value": { "type": "number", "example": 4.12 }, "shocked_value": { "type": "number", "example": 2.18 }, "covenant_threshold": { "type": "number", "example": 2.5 }, "breach_projected": { "type": "boolean", "example": true }, "provenance": { "type": "object", "properties": { "filing": { "type": "string", "example": "ORCL_10K_2025" }, "accession": { "type": "string", "example": "0001564590-25-012345" }, "xbrl_concept": { "type": "string", "example": "us-gaap:LongTermDebtNoncurrent" } } } } } } } }, "FirewallVerifyRequest": { "type": "object", "required": [ "client_app_id", "generated_text", "compliance_strictness" ], "properties": { "client_app_id": { "type": "string", "example": "morgan_stanley_wealth_copilot" }, "generated_text": { "type": "string", "example": "Apple reported total revenue of $412.5 billion in FY2025, driven by iPhone sales of $220.1 billion and Services growth of 14.2%." }, "compliance_strictness": { "type": "string", "enum": [ "FAIL_CLOSED", "STRICT", "PERMISSIVE" ], "example": "FAIL_CLOSED" }, "required_entities": { "type": "array", "items": { "type": "string" }, "example": [ "AAPL" ] } } }, "FirewallVerifyResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "TAMPER_DETECTED_AND_CORRECTED" }, "latency_ms": { "type": "number", "example": 2.15 }, "hallucination_detected": { "type": "boolean", "example": true }, "audit_trail_sha256": { "type": "string", "example": "8f3b20a1c9e84712ad910c2834b76e5d9f10a82b45e761928347162983471629" }, "verified_payload": { "type": "string", "example": "Apple reported total revenue of $391.0 billion in FY2025, driven by iPhone sales of $201.2 billion and Services revenue of $96.2 billion (growth of 12.8%)." }, "corrections": { "type": "array", "items": { "type": "object", "properties": { "claim": { "type": "string", "example": "$412.5 billion revenue" }, "verdict": { "type": "string", "example": "FABRICATED" }, "ground_truth": { "type": "string", "example": "$391.0 billion" }, "provenance": { "type": "string", "example": "AAPL_10K_2025_XBRL:Revenues" } } } } } }, "HftVerifyRouteRequest": { "type": "object", "required": [ "desk_id", "instrument", "order_type", "order_size_shares", "target_venues", "max_slippage_tolerance_bps" ], "properties": { "desk_id": { "type": "string", "example": "quant_execution_desk_04" }, "instrument": { "type": "string", "example": "NVDA" }, "order_type": { "type": "string", "example": "TWAP_CHILD_SWEEP" }, "order_size_shares": { "type": "integer", "example": 15000 }, "target_venues": { "type": "array", "items": { "type": "string" }, "example": [ "NASDAQ", "BATS", "ARCA", "IEX" ] }, "max_slippage_tolerance_bps": { "type": "number", "example": 1.2 } } }, "HftVerifyRouteResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "APPROVED" }, "routing_stability": { "type": "string", "example": "OPTIMAL" }, "latency_microseconds": { "type": "integer", "example": 348 }, "projected_slippage_bps": { "type": "number", "example": 0.38 }, "liquidity_manifold": { "type": "object", "properties": { "betti_0_fragmentation": { "type": "integer", "example": 1 }, "betti_1_vortex_risk": { "type": "integer", "example": 0 }, "flash_crash_potential": { "type": "string", "example": "NEGLIGIBLE" } } }, "recommended_split": { "type": "object", "properties": { "NASDAQ": { "type": "number", "example": 0.45 }, "IEX": { "type": "number", "example": 0.3 }, "ARCA": { "type": "number", "example": 0.25 } } } } }, "HftArbitrageRequest": { "type": "object", "properties": { "symbol": { "type": "string", "example": "NVDA" }, "venues": { "type": "array", "items": { "type": "string" }, "example": [ "NASDAQ", "BATS", "ARCA" ] } } }, "HftArbitrageResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "VALIDATED" }, "symbol": { "type": "string", "example": "NVDA" }, "evaluated_venues": { "type": "array", "items": { "type": "string" } }, "venue_mid_prices": { "type": "object", "additionalProperties": { "type": "number" } }, "gross_spread_bps": { "type": "number", "example": 3.1 }, "net_arbitrage_bps": { "type": "number", "example": 1.9 }, "arbitrage_executable": { "type": "boolean", "example": true }, "latency_us": { "type": "integer", "example": 40 } } }, "HftLiquidityBettiResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "COMPUTED" }, "symbol": { "type": "string", "example": "NVDA" }, "betti_0_components": { "type": "integer", "example": 1 }, "betti_1_cycles": { "type": "integer", "example": 1 }, "spectral_gap": { "type": "number", "example": 0.842 }, "flash_crash_risk_state": { "type": "string", "example": "STABLE" }, "latency_us": { "type": "integer", "example": 20 } } }, "OrderBookSnapshot": { "type": "object", "properties": { "venue": { "type": "string", "example": "NASDAQ" }, "symbol": { "type": "string", "example": "NVDA" }, "timestamp_nano": { "type": "integer", "example": 0 }, "bids": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "number" }, "volume": { "type": "number" } } } }, "asks": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "number" }, "volume": { "type": "number" } } } }, "mid_price": { "type": "number", "example": 120.15 }, "spread_bps": { "type": "number", "example": 8.3 }, "queue_imbalance": { "type": "number", "example": 0.12 }, "micro_price": { "type": "number", "example": 120.16 } } }, "HftSettleResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "SETTLED" }, "symbol": { "type": "string" }, "venue": { "type": "string" }, "mid_price": { "type": "number" }, "hopfield_support_well": { "type": "number" }, "hopfield_resist_well": { "type": "number" }, "latency_us": { "type": "integer" } } } } } }