{ "openapi": "3.1.0", "info": { "title": "Navstone API", "version": "1.0.0", "description": "Keyless REIT data and valuation endpoints behind navstone.vercel.app. Live data from SEC EDGAR and FRED; nothing is filled in when a source fails. Not investment advice. By Saga Dog Corp \u00b7 Research-driven AI from Miami.", "contact": { "name": "Saga Dog Corp", "url": "https://ecoquipr.com" } }, "servers": [ { "url": "https://navstone.vercel.app" } ], "paths": { "/api/reit": { "get": { "summary": "Live SEC snapshot for a ticker", "description": "Company, industry code, latest XBRL shares outstanding, annual dividend per share and reported debt, plus up to 8 recent 10-K/10-Q/8-K filings. CDN-cached 1 hour.", "parameters": [ { "name": "ticker", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z.\\-]{1,10}$", "default": "PLD" }, "example": "O" } ], "responses": { "200": { "description": "Snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReitSnapshot" } } } }, "400": { "description": "Invalid ticker", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "example": { "error": "invalid ticker" } } } }, "404": { "description": "Ticker not in SEC EDGAR", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "example": { "error": "Ticker XYZQ not found in SEC EDGAR" } } } }, "502": { "description": "SEC EDGAR unreachable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "example": { "error": "SEC EDGAR unavailable: TimeoutError" } } } } } } }, "/api/macro": { "get": { "summary": "Live FRED rate series", "description": "Last 60 observations of a supported series from FRED's public CSV. CDN-cached 1 hour.", "parameters": [ { "name": "series", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "DGS10", "DGS2", "MORTGAGE30US", "DFF" ], "default": "DGS10" }, "description": "Case-insensitive" } ], "responses": { "200": { "description": "Series", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MacroSeries" } } } }, "400": { "description": "Unsupported series", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "supported": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "502": { "description": "FRED unreachable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } } } }, "/api/value": { "post": { "summary": "Bull/base/bear fair value", "description": "Runs the Navstone valuation engine on your inputs. All fields optional; missing numbers count as 0 (shares_outstanding as 1). Not cached.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValueInputs" }, "example": { "sector": "net_lease", "price": 57, "nav_per_share": 55, "forward_affo_per_share": 4.2, "forward_ffo_per_share": 4.3, "annual_dividend_per_share": 3.2, "shares_outstanding": 900000000, "net_debt": 26000000000, "debt_due_2y": 4000000000 } } } }, "responses": { "200": { "description": "Scenarios", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValueResult" } } } }, "400": { "description": "Body is not JSON or a number field isn't numeric", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "example": { "error": "invalid JSON inputs" } } } } } } } }, "components": { "schemas": { "ReitSnapshot": { "type": "object", "required": [ "ticker", "name", "cik", "sic", "is_reit_sic", "facts", "filings", "source" ], "properties": { "ticker": { "type": "string" }, "name": { "type": "string" }, "cik": { "type": "string", "description": "10-digit, zero-padded" }, "sic": { "type": [ "string", "null" ] }, "is_reit_sic": { "type": "boolean" }, "facts": { "type": "object", "description": "Each key is present only if SEC has that XBRL fact", "properties": { "shares_outstanding": { "type": "object", "required": [ "value", "stale" ], "properties": { "value": { "type": "number" }, "as_of": { "type": "string", "format": "date" }, "form": { "type": "string" }, "stale": { "type": "boolean", "description": "True when the date is more than 2 years old" } } }, "annual_dividend_per_share": { "type": "object", "required": [ "value", "stale" ], "properties": { "value": { "type": "number" }, "period_end": { "type": "string", "format": "date" }, "tag": { "type": "string", "enum": [ "CommonStockDividendsPerShareCashPaid", "CommonStockDividendsPerShareDeclared" ] }, "stale": { "type": "boolean", "description": "True when the date is more than 2 years old" } } }, "reported_debt": { "type": "object", "required": [ "value", "stale" ], "properties": { "value": { "type": "number" }, "as_of": { "type": "string", "format": "date" }, "tag": { "type": "string" }, "stale": { "type": "boolean", "description": "True when the date is more than 2 years old" } } } } }, "filings": { "type": "array", "maxItems": 8, "items": { "type": "object", "properties": { "form": { "type": "string", "enum": [ "10-K", "10-Q", "8-K" ] }, "filed": { "type": "string", "format": "date" }, "accession": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } }, "source": { "type": "string" } } }, "MacroSeries": { "type": "object", "required": [ "series_id", "label", "observations", "latest", "source" ], "properties": { "series_id": { "type": "string" }, "label": { "type": "string" }, "observations": { "type": "array", "maxItems": 60, "items": { "$ref": "#/components/schemas/Obs" } }, "latest": { "oneOf": [ { "$ref": "#/components/schemas/Obs" }, { "type": "null" } ] }, "source": { "type": "string" } } }, "Obs": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "value": { "type": "number" } } }, "ValueInputs": { "type": "object", "properties": { "sector": { "type": "string", "enum": [ "industrial", "apartment", "office", "net_lease", "default" ], "default": "default", "description": "Unknown sectors use default assumptions" }, "price": { "type": "number", "description": "Share price; enables upside_pct" }, "nav_per_share": { "type": "number", "description": "" }, "forward_affo_per_share": { "type": "number", "description": "" }, "forward_ffo_per_share": { "type": "number", "description": "" }, "annual_dividend_per_share": { "type": "number", "description": "" }, "shares_outstanding": { "type": "number", "description": "" }, "net_debt": { "type": "number", "description": "" }, "debt_due_2y": { "type": "number", "description": "Debt maturing within 2 years" } } }, "ValueResult": { "type": "object", "properties": { "scenarios": { "type": "array", "items": { "type": "object", "properties": { "scenario": { "type": "string", "enum": [ "bull", "base", "bear" ] }, "nav_value": { "type": "number" }, "affo_value": { "type": "number" }, "ffo_value": { "type": "number" }, "yield_value": { "type": "number" }, "risk_discount": { "type": "number", "description": "Fraction, e.g. 0.048" }, "fair_value": { "type": "number" }, "upside_pct": { "type": "number", "description": "Only when price was given" } } } }, "inputs": { "type": "object", "description": "The parsed inputs actually used" } } } } } }