{ "openapi": "3.1.0", "info": { "title": "TENK/calls API", "version": "1.0.0", "summary": "SEC-grounded fundamentals, quality scores and AI research calls over REST.", "description": "The engine behind the app, as an API: normalized SEC XBRL fundamentals, the TENK Score (0–100 quality composite), SEC filing & 8-K event feeds, and AI research calls — for any US-listed ticker. JSON, key-authenticated, CORS-enabled.\n\n**Auth:** send `Authorization: Bearer tk_live_…` (create a key at /developers). **Envelope:** successful responses are `{ \"data\": … }`; errors are `{ \"error\": { \"code\", \"message\" } }`. **Rate limits:** every response carries `X-RateLimit-Limit/Remaining/Reset`; exceeding the per-minute burst or monthly quota returns `429` with `Retry-After`.\n\n**Data licensing:** SEC data and our derived analytics are yours to use under your plan. Live market data is third-party licensed and not redistributed — `/quote` is bring-your-own-key (`x-data-key`).\n\nEDGAR® is a trademark of the U.S. SEC. TENK/calls is not affiliated with or approved by the SEC.", "license": { "name": "Terms at /developers" } }, "servers": [ { "url": "/", "description": "This deployment" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Reference", "description": "Universe lookup" }, { "name": "SEC analytics", "description": "Fundamentals, score, filings, events — ours to serve" }, { "name": "AI", "description": "AI research calls (Pro)" }, { "name": "Market data", "description": "Quotes — bring-your-own-key" } ], "paths": { "/api/v1/search": { "get": { "tags": [ "Reference" ], "summary": "Search the universe", "description": "Ticker/name lookup across ~52k US securities.", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search query; an empty or missing q returns an empty result set.", "example": "apple" } ], "responses": { "200": { "description": "Matches", "headers": { "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" } }, "content": { "application/json": { "example": { "data": { "query": "apple", "results": [ { "ticker": "AAPL", "name": "Apple Inc" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/fundamentals/{ticker}": { "get": { "tags": [ "SEC analytics" ], "summary": "Normalized SEC fundamentals", "description": "Multi-year XBRL digest: ~20 line items (current + YoY + prior-year + history) and derived ratios (margins, ROE, debt/equity).", "parameters": [ { "$ref": "#/components/parameters/Ticker" } ], "responses": { "200": { "description": "Fundamentals digest", "content": { "application/json": { "example": { "data": { "ticker": "AAPL", "cik": "0000320193", "name": "Apple Inc.", "fundamentals": { "latestFiscalYear": 2024, "metrics": { "revenue": { "value": 391035000000, "fiscalYear": 2024 }, "netIncome": { "value": 93736000000, "fiscalYear": 2024 } }, "derived": { "netMargin": 0.24, "returnOnEquity": 1.57 } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/score/{ticker}": { "get": { "tags": [ "SEC analytics" ], "summary": "TENK Score", "description": "Our 0–100 quality composite + factor sub-scores (value, growth, profitability, health, momentum) with letter grades and a pass/fail checklist.", "parameters": [ { "$ref": "#/components/parameters/Ticker" } ], "responses": { "200": { "description": "Score", "content": { "application/json": { "example": { "data": { "ticker": "AAPL", "cik": "0000320193", "name": "Apple Inc.", "score": { "composite": 78, "grade": "B+", "factors": { "value": 35.5, "growth": 75, "profitability": 95, "health": 67.3, "momentum": null }, "factorGrades": { "value": "F", "growth": "B+", "profitability": "A+" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/filings/{ticker}": { "get": { "tags": [ "SEC analytics" ], "summary": "Recent SEC filings", "parameters": [ { "$ref": "#/components/parameters/Ticker" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 12, "maximum": 50 } } ], "responses": { "200": { "description": "Filings", "content": { "application/json": { "example": { "data": { "ticker": "AAPL", "filings": [ { "form": "10-K", "filed": "2024-11-01", "url": "https://www.sec.gov/..." } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/events/{ticker}": { "get": { "tags": [ "SEC analytics" ], "summary": "Material events (8-K)", "description": "Events parsed from 8-K filings (item codes, date, link).", "parameters": [ { "$ref": "#/components/parameters/Ticker" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 8, "maximum": 40 } } ], "responses": { "200": { "description": "Events", "content": { "application/json": { "example": { "data": { "ticker": "AAPL", "events": [ { "filed": "2025-01-30", "items": [ "2.02" ], "url": "https://www.sec.gov/..." } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/call/{ticker}": { "get": { "tags": [ "AI" ], "summary": "AI research call (Pro)", "description": "Rating, conviction, thesis, risks, catalysts and price target — grounded in SEC fundamentals. Requires the Pro plan.", "parameters": [ { "$ref": "#/components/parameters/Ticker" } ], "responses": { "200": { "description": "Call", "content": { "application/json": { "example": { "data": { "ticker": "AAPL", "name": "Apple Inc.", "call": { "rating": "buy", "conviction": 4, "timeHorizon": "long", "priceTarget": 260, "summary": "…", "thesis": "…", "keyRisks": [ "…" ], "catalysts": [ "…" ] }, "score": { "composite": 78, "grade": "B+" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/UpgradeRequired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/quote/{ticker}": { "get": { "tags": [ "Market data" ], "summary": "Live quote (bring-your-own-key)", "description": "Live/last quote. Market data is third-party licensed and not redistributed under our plan — pass your own EODHD token via the `x-data-key` header and we proxy under your entitlement.", "parameters": [ { "$ref": "#/components/parameters/Ticker" }, { "name": "x-data-key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your EODHD API token." } ], "responses": { "200": { "description": "Quote", "content": { "application/json": { "example": { "data": { "ticker": "AAPL", "quote": { "close": 299.24, "change_p": 0.87, "previousClose": 296.42, "volume": 37342135 }, "source": "eodhd (byo-key)" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "Market data unlicensed — pass x-data-key.", "content": { "application/json": { "example": { "error": { "code": "market_data_unlicensed", "message": "Live market data is third-party licensed. Pass your own EODHD token via the x-data-key header." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "tk_live_…", "description": "Your API key. Create one at /developers." } }, "parameters": { "Ticker": { "name": "ticker", "in": "path", "required": true, "schema": { "type": "string" }, "example": "AAPL" } }, "headers": { "RateLimitRemaining": { "description": "Requests remaining this month.", "schema": { "type": "integer" } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "responses": { "Unauthorized": { "description": "Missing/invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing or invalid API key." } } } } }, "UpgradeRequired": { "description": "Endpoint requires a higher plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "upgrade_required", "message": "This endpoint requires the \"pro\" plan or higher." } } } } }, "NotFound": { "description": "Ticker not found in the SEC company list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Ticker not found in the SEC company list." } } } } }, "RateLimited": { "description": "Rate limit or monthly quota exceeded. Includes Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded — slow down." } } } } } } } }