> Finks API docs. Every page: https://finks.ai/llms.txt. The OpenAPI spec: https://finks.ai/docs/openapi.json. # Finks API docs Connect your app or agent to financial news and data. ## Connect Create a free account at https://dashboard.finks.ai/signin to get a key, and keep it in `FINKS_API_KEY`. - Agent, over MCP: https://mcp.data.finks.ai/mcp (streamable HTTP). Sign in with OAuth where the client supports it. A key (`Authorization: Bearer $FINKS_API_KEY`) is the fallback for CI, and for Cursor and VS Code for now. Client setup: https://finks.ai/docs/mcp.md. - App, over REST: base URL https://data.finks.ai, the same Bearer header on every request. Walkthrough: https://finks.ai/docs/quickstart.md. ## Endpoints - [Search](https://finks.ai/docs/reference/search.md): Find the news, filings and calls behind any market question. - [Records](https://finks.ai/docs/reference/records.md): Go from a search result to the full story. - [Screener](https://finks.ai/docs/reference/screener.md): Find the companies that match your criteria. - [Company and filings](https://finks.ai/docs/reference/filings.md): Follow a company's filings and news as they land. - [Account](https://finks.ai/docs/reference/account.md): Check your plan, your usage and what your key can reach. OpenAPI spec: https://finks.ai/docs/openapi.json. Every dataset: https://dashboard.finks.ai/data. --- > Finks API docs. Every page: https://finks.ai/llms.txt. The OpenAPI spec: https://finks.ai/docs/openapi.json. # Quickstart Go from a new key to your first result. ## Get a key [Create a free account](https://dashboard.finks.ai/signin). It comes with a key, and the console's Search and Screener run as it right away. For your own code, create or roll a key on [API keys](https://dashboard.finks.ai/keys): its secret is shown once. Every request your keys make draws from your account's credits. Every sample reads the key from `FINKS_API_KEY`: Terminal: ```bash export FINKS_API_KEY="fk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ``` ## Search One request searches news, filings and earnings calls, best match first. ```bash curl -sS "https://data.finks.ai/v1/search" \ -H "Authorization: Bearer $FINKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "Nvidia short interest, holders and insider selling", "limit": 10, "symbols": [ "NVDA" ] }' # Next page: the same body plus "cursor": , while "has_more" is true. ``` Example response (Illustrative): ```json { "results": [ { "id": "sample-brief-id", "type": "brief", "title": "Sample brief about Nvidia insider selling", "summary": "Sample text. A real brief carries a Finks-written summary here.", "url": "https://example.com/sample-brief", "publishers": ["newswire.example", "markets.example"], "symbols": ["NVDA"], "published_at": "2026-10-21T14:05:00Z" }, { "id": "sample-filing-id", "type": "filing", "title": "Sample 8-K current report", "summary": "Sample text. A real filing carries a summary of the event it reports.", "url": "https://example.com/sample-filing", "symbols": ["NVDA"], "published_at": "2026-10-20T21:30:00Z", "citation_id": "sample-citation-id", "excerpt": "Sample text, quoted word for word from the filing." } ], "has_more": true, "next_cursor": "sample-cursor", "ranking": "retrieval", "datasets": [ { "name": "brief", "state": "searched" }, { "name": "article", "state": "searched" }, { "name": "filing", "state": "searched" }, { "name": "transcript", "state": "searched" }, { "name": "sec_forms", "state": "searched" } ], "data": [ { "dataset": "sec_forms", "entity": "NVDA", "href": "/v1/companies/NVDA/events", "as_of": "2026-10-20", "results": [ { "id": "sample-filing-id", "type": "filing", "title": "Sample 8-K current report", "url": "https://example.com/sample-filing", "published_at": "2026-10-20T21:30:00Z" } ] } ] } ``` What comes back: - `results`: each with an `id`, `type` and `title`, and usually a `summary`, `url` and `symbols`. - `has_more` and `next_cursor`: for the next page. - `data`: company, fund and macro data for what the query names. ## Read the whole record Open a result's full record with its `id`: Terminal: ```bash export RESULT_ID="" ``` ```bash curl -sS "https://data.finks.ai/v1/content/$RESULT_ID" \ -H "Authorization: Bearer $FINKS_API_KEY" ``` ## Next - [Connect your agent over MCP](https://finks.ai/docs/mcp.md). - [Search reference](https://finks.ai/docs/reference/search.md): every filter. - [Screener](https://finks.ai/docs/reference/screener.md): screen and rank companies. - [Errors](https://finks.ai/docs/errors.md): what each code means. --- > Finks API docs. Every page: https://finks.ai/llms.txt. The OpenAPI spec: https://finks.ai/docs/openapi.json. # Authentication Keep your key safe and send it with every request. ## Send your key Send it from your server, never the browser. Header: ```text Authorization: Bearer $FINKS_API_KEY ``` ## Rotate and revoke A key is shown once. Rotate or revoke it in [API keys](https://dashboard.finks.ai/keys): a rotated key keeps working until you revoke it. Every key spends the same credit balance: your plan's credits, then overage on paid plans. --- > Finks API docs. Every page: https://finks.ai/llms.txt. The OpenAPI spec: https://finks.ai/docs/openapi.json. # MCP server Plug Finks into Claude, Cursor and any other agent. ## Endpoint Claude, ChatGPT, Claude Code, Codex, Grok and Hermes sign in with OAuth. Cursor and VS Code use a key for now. Create one on [API keys](https://dashboard.finks.ai/keys). A key is also the fallback for CI. MCP endpoint: ```text https://mcp.data.finks.ai/mcp ``` ## Add it to your client **Claude** (sign in, no key). No API key needed: sign in to Finks. 1. Open **Settings → Connectors** and choose **Add custom connector**. 2. Paste the server URL, then choose **Connect**. 3. Sign in using your Finks login. ```text https://mcp.data.finks.ai/mcp ``` **Claude Code** (CLI) (sign in, no key). Run this, then type /mcp, pick finks-api and sign in. Terminal: ```bash claude mcp add --transport http --scope user finks-api https://mcp.data.finks.ai/mcp ``` **CI / API key.** On a server or in CI, with no browser to sign in, create a key on [API keys](https://dashboard.finks.ai/keys), set it as `FINKS_API_KEY`, then: Run once in your project. Writes .mcp.json, which reads FINKS_API_KEY from your environment. Terminal: ```bash claude mcp add --transport http --scope project finks-api \ https://mcp.data.finks.ai/mcp \ --header 'Authorization: Bearer ${FINKS_API_KEY}' ``` **ChatGPT** (sign in, no key). No API key needed: sign in to Finks. 1. Turn on **developer mode** in ChatGPT's connector settings. 2. Add a connector with the server URL and authentication **OAuth**. 3. Sign in using your Finks login. ```text https://mcp.data.finks.ai/mcp ``` **Codex** (CLI) (sign in, no key). Run these. The second one opens Finks sign-in. Terminal: ```bash codex mcp add finks-api --url https://mcp.data.finks.ai/mcp codex mcp login finks-api ``` **CI / API key.** On a server or in CI, with no browser to sign in, create a key on [API keys](https://dashboard.finks.ai/keys), set it as `FINKS_API_KEY`, then: Add to the file. Reads FINKS_API_KEY from your environment. ~/.codex/config.toml: ```toml [mcp_servers.finks-api] url = "https://mcp.data.finks.ai/mcp" bearer_token_env_var = "FINKS_API_KEY" ``` **Grok** (sign in, no key). No API key needed: sign in to Finks. 1. Go to **grok.com/connectors** and choose **New Connector → Custom**. 2. Paste the server URL. 3. Sign in using your Finks login. ```text https://mcp.data.finks.ai/mcp ``` **Cursor** (key). Needs an API key. Add to `~/.cursor/mcp.json`. Reads FINKS_API_KEY from your environment. [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=finks-api&config=eyJ1cmwiOiJodHRwczovL21jcC5kYXRhLmZpbmtzLmFpL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciAke2VudjpGSU5LU19BUElfS0VZfSJ9fQ%3D%3D) ~/.cursor/mcp.json: ```json { "mcpServers": { "finks-api": { "url": "https://mcp.data.finks.ai/mcp", "headers": { "Authorization": "Bearer ${env:FINKS_API_KEY}" } } } } ``` **VS Code** (key). 1. Create a key on **API keys**. 2. Add this to `.vscode/mcp.json`. VS Code asks for your key once. 3. Check the connection. [Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%22finks-api%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.data.finks.ai%2Fmcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20%24%7Binput%3Afinks-api-key%7D%22%7D%2C%22inputs%22%3A%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22finks-api-key%22%2C%22description%22%3A%22Finks%20API%20key%22%2C%22password%22%3Atrue%7D%5D%7D) .vscode/mcp.json: ```json { "inputs": [ { "type": "promptString", "id": "finks-api-key", "description": "Finks API key", "password": true } ], "servers": { "finks-api": { "type": "http", "url": "https://mcp.data.finks.ai/mcp", "headers": { "Authorization": "Bearer ${input:finks-api-key}" } } } } ``` **Gemini CLI** (key). 1. Create a key on **API keys** and set it as `FINKS_API_KEY`. 2. Run this once in your terminal. 3. Check the connection. Terminal: ```bash gemini mcp add --scope user --transport http \ --header 'Authorization: Bearer ${FINKS_API_KEY}' \ finks-api https://mcp.data.finks.ai/mcp ``` **Hermes** (sign in, no key). No API key needed: sign in to Finks. 1. Add this to `~/.hermes/config.yaml`. 2. Run `hermes mcp login finks-api` and sign in using your Finks login. 3. In Hermes, run `/reload-mcp`. ~/.hermes/config.yaml: ```yaml mcp_servers: finks-api: url: https://mcp.data.finks.ai/mcp auth: oauth ``` ## CLI Claude Code, Codex and Gemini CLI. The commands are with each client above: Claude Code and Codex sign in, and Gemini CLI reads `FINKS_API_KEY`. - [Claude Code](#setup-claude-code) - [Codex](#setup-codex) - [Gemini CLI](#setup-gemini-cli) ## Tools Each tool calls one route with the same filters and limits as the API. - `finks_search` (POST /v1/search): Search briefs, articles, filings and earnings call transcripts with the same filters as the API. Its input schema is the live tool schema. - `finks_get_content` (GET /v1/content/{id}): The whole record behind any result id. - `finks_list_filing_events` (GET /v1/content): Filing events, newest first, after a summary header; filings sent together stay together. Page back with `older`. - `finks_account` (GET /v1/account): Your account, plan limits, usage and masked keys. Not metered. - `finks_account_usage` (GET /v1/account/usage): Usage for one month, the current UTC month by default. Not metered. - `finks_search_fields` (GET /v1/search/fields): The search catalog and the result fields your key can see. Not metered. - `finks_screener` (POST /v1/screener): Screen listed companies with a normalized query or in plain words. - `finks_screener_fields` (GET /v1/screener/fields): The screener's fields, operators, units and values. Not metered. - `finks_get_event` (GET /v1/events/{ledger_event_id}): One filing event by its ledger id. - `finks_datasets` (GET /v1/datasets): Every dataset Finks serves, with its routes and source, and whether your plan includes it. Not metered. - `finks_latest_filings` (GET /v1/companies/{symbol}/events?types=filing): A company's newest SEC filings, newest first. ## Errors A refused call returns a tool error with the API's error code and `request_id`. [Errors](https://finks.ai/docs/errors.md) lists the codes. --- > Finks API docs. Every page: https://finks.ai/llms.txt. The OpenAPI spec: https://finks.ai/docs/openapi.json. # Usage and limits Know what counts toward your plan before you scale. ## What is metered Each successful request to these routes counts one unit against your account's credits, whichever key sends it. Failed requests count nothing. - `search_standard`: One standard search: one page of POST /v1/search. - `search_deep`: Deep search is off on every plan right now, so `"depth": "deep"` is refused (400 request.out_of_plan). - `feed_page`: One page of a feed: GET /v1/content or a company's events. - `screener_search`: One screen: one page of POST /v1/screener, 10 credits on every plan. - `search_research`: One research answer, on plans that include research. Everything else is free: record reads and Search fields. ## Limits Your plan sets each limit, and each has its own error code. | Limit | What it counts | Refused with | | --- | --- | --- | | Rate limit | Requests per minute, on every route. | `429 rate_limit.exceeded`, with `Retry-After` | | Quota | The usage your plan includes each billing period, which starts on your signup date. | `429 quota.exceeded` | | Spend cap | The most the account may spend in a billing period, when one is set. | `429 spend_cap.exceeded`, with `details.resets_at` | | Page cap and history | The largest page and the earliest date your plan reads. | `400 request.out_of_plan` | Track usage on [Usage](https://dashboard.finks.ai/usage); prices are on [Pricing](https://finks.ai/api/pricing). --- > Finks API docs. Every page: https://finks.ai/llms.txt. The OpenAPI spec: https://finks.ai/docs/openapi.json. # Errors Handle failures and retry the right way. ## The envelope `details` adds context, such as the field at fault. Log `request_id` and quote it to Finks support. An error body: ```json { "error": { "code": "request.invalid", "message": "A sentence saying what was wrong.", "request_id": "The id to quote to Finks support", "details": { "field": "limit" } } } ``` ## Retries - Only `429 rate_limit.exceeded` sends `Retry-After`. Wait that many seconds, then retry. - The spend cap reports when it resets in `details.resets_at`. Retrying before then fails. - `503 content.unresolved` can succeed later. Retry a few times with exponential backoff. - Never retry a 400 or 401 unchanged: it fails the same way. ## Every code ### Fix the request - `400 request.invalid`: A parameter or body field is wrong. `details.field` names it when there is one. - `400 request.out_of_plan`: The request asks for more than your plan allows, such as a page size over the cap, dates before your history window, or `depth: "deep"` (deep search is off on every plan). `details` names the allowance. - `400 invalid_cursor`: The cursor belongs to another request or account, or the request changed beyond `limit`. Start again from page 1. - `400 cursor_expired`: The cursor is too old. Start again from page 1. - `400 invalid_filter`: A screener filter cannot run as written. - `400 unsupported_subject`: The screener cannot screen that subject. - `400 unsupported_field_for_subject`: The field does not exist for that subject. GET /v1/screener/fields lists the fields. - `400 unresolvable_query`: The screen could not be turned into a query the screener can run. - `413 request.too_large`: The request body is over the 2 MB limit. - `404 not_found`: No record with that id. - `410 withdrawn`: The record was withdrawn and is no longer served. ### Check the key or account - `401 auth.invalid_key`: The key is missing, mistyped or unknown. - `401 auth.revoked_key`: The key was revoked. Use another key. - `401 auth.expired_key`: The key expired. Use another key. - `401 auth.expired_token`: A sign-in token (an MCP app's) is past its 15 minutes. Your client gets a new one; sign in again if it cannot. - `403 account.not_ready`: The key is valid, but the account's plan limits are not set yet. Contact Finks. - `501 not_implemented`: Your plan does not include this route or feature, or it is not available yet. ### Wait, or raise a limit - `429 rate_limit.exceeded`: Too many requests this minute. Wait the seconds in the `Retry-After` header, then retry. - `429 quota.exceeded`: The account's monthly quota is used up. - `429 spend_cap.exceeded`: The account's monthly spend cap is reached. `details.resets_at` and `details.limit` say when it resets and what it was. - `503 content.unresolved`: A read behind the request did not resolve, so the whole request failed instead of answering in part. Retry later. --- > Finks API docs. Every page: https://finks.ai/llms.txt. The OpenAPI spec: https://finks.ai/docs/openapi.json. # Search Find the news, filings and calls behind any market question. Base URL: https://data.finks.ai. Send your key as `Authorization: Bearer $FINKS_API_KEY`. ## Search `POST /v1/search` (#post-v1-search) Searches briefs, articles, filings and earnings call transcripts, best match first. Read any result in full with GET /v1/content/{id}. - A deep search records `search_deep` instead of `search_standard`. - Page with `cursor`: resend the same body with the previous `next_cursor` (only `limit` may change) while `has_more` is true. A cursor from another request is `400 invalid_cursor`; an old one is `400 cursor_expired`. - Timestamps are RFC 3339 in UTC. `*_after` is inclusive (except `enriched_after`) and `*_before` exclusive. ### Request body - `query` (string, required): What to find, in plain words. - `as_of` (string, can be null): `YYYY-MM-DD`, point in time (behind the account flag `api_point_in_time`): the search as published by the end of that New York day. Results published at or after the start of the next New York day are not served, `reported_facts` reads only facts filed on or before it (each period's latest version filed by then), and every other data-block dataset is not read (`not_point_in_time`). Not after today. - `cursor` (string, can be null): The `next_cursor` of the previous page, sent with that search's body unchanged except `limit`. Leave it out for page 1. - `data` (string, can be null): `asked` (the default) or `all`: which company and fund datasets page 1's data block reads. One of `asked`, `all`. - `depth` (string, can be null): `standard` (the default) or `deep`, which also ranks each result by its best passage and returns it. Needs the `deep_search` plan right. One of `standard`, `deep`. - `enriched_after` (string, can be null): RFC 3339, exclusive: only items whose metadata was computed after this instant. Articles don't carry it yet, so this leaves them out. - `event_types` (array of string): Event-type slugs (`earnings`, `m_and_a`, ...): only items carrying any of them. - `exclude` (array of string): Pools (`brief`, `article`, `filing`, `transcript`) or related datasets to leave out. GET /v1/search/fields lists them. - `limit` (integer, can be null): Results per page, up to your plan's page cap. - `published_after` (string, can be null): RFC 3339, inclusive. - `published_before` (string, can be null): RFC 3339, exclusive. - `rerank` (boolean, can be null): Leave it out. `false` skips re-ranking, for comparisons. - `sort` (string, can be null): `relevance` (best match first, the default) or `newest`. One of `relevance`, `newest`. - `symbols` (array of string): Tickers: only items about any of them. - `types` (array of string): The pools to search. Prefer `exclude`; naming a pool in both is a 400. One of `brief`, `article`, `filing`, `transcript`, `regulator`. ### Response - `datasets` (array of object, required): What this search read, and why it skipped any. Later pages repeat page 1's. - `has_more` (boolean, required): True while another page follows. - `ranking` (string, required): `retrieval`; `jev` on accounts whose results are re-ranked; or `judge` when a deep search's judge ranked them. One of `jev`, `judge`, `retrieval`. - `results` (array of object, required): Ranked best first, at most `limit` items, may be empty. - `answer` (object, can be null): Deep search's `answer`: a quote of a result's own text, with offsets into the text `GET /v1/content/{result_id}` serves (a brief's or article's `body`, a filing's `text` of section `section_id`, a transcript's `body`). - `data` (array of one of several shapes, can be null): `asked` (the default) or `all`: which company and fund datasets page 1's data block reads. - `entities` (array of object, can be null): Page 1 only: what the data block is about, in query order: the companies and funds the query names, and the macro series it asks for. Absent on a later page. - `floor_note` (string, can be null): Only when a standard search dropped low-scoring results: how many. `results` can then be empty on a 200, meaning no confident match. - `interpretation` (object, can be null): How a search naming 2 or more companies was read, and what page 1 holds about each. - `next_cursor` (string, can be null): Opaque token for the next page of the same ranked set. `null` on the last page. - `point_in_time` (object, can be null): The cutoff a point-in-time search (`as_of`) applied. - `retrieval_note` (string, can be null): `depth: "standard"`, page 1 only: present when the query embedding did not answer within its 2.5 s budget and the page was ranked on keyword matching alone, without semantic similarity (and without filing excerpts). Absent otherwise. - `sort_note` (string, can be null): `sort: newest`, page 1 only: why the page holds fewer than `limit` results. Present when fewer than `limit` items matched the query and the read that fills the page with its best relevance matches did not complete (timed out or failed), so the page serves the matches alone. Absent otherwise. ### Statuses - 200: Ranked results, best first - 400: `request.invalid` naming the field, `request.out_of_plan` naming the allowed value, `invalid_cursor`, or `cursor_expired` - 401: Missing, unknown, revoked, or expired key - 413: `request.too_large`, the body is over the 2 MB limit - 429: Rate limited, quota denied, or spend cap reached - 501: The plan grants no serving limit - 503: `content.unresolved`, a pool `types` names, or every pool searched, could not answer ### Request ```bash curl -sS "https://data.finks.ai/v1/search" \ -H "Authorization: Bearer $FINKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "Nvidia short interest, holders and insider selling", "limit": 10, "symbols": [ "NVDA" ] }' # Next page: the same body plus "cursor": , while "has_more" is true. ``` Metered: one `search_standard` per answer. - Data: Market news, from Finks and financial publishers. Updates: daily. - Data: Earnings call transcripts, from Company earnings calls. Updates: after each call. - Data: SEC filings, from SEC EDGAR. Updates: as filed. - Data: 8-K events, from SEC EDGAR. Updates: as filed. - Data: Insider and ownership forms, from SEC EDGAR. Updates: as filed. - Data: IPOs and offerings, from SEC EDGAR. Updates: as filed. - Data: Proxy statements, from SEC EDGAR. Updates: as filed. - Data: Institutional holders, from SEC EDGAR (13F). Updates: quarterly. - Data: Free float, from Finks, from SEC ownership forms. Updates: as filed. - Data: Short interest, from FINRA. Updates: twice a month. - Data: Fund profiles and holdings, from SEC fund filings. Updates: as filed. - Data: Funds holding a stock, from SEC fund filings. Updates: as filed. - Data: Fund distribution sources, from SEC EDGAR (19a notices). Updates: with each payout. - Data: Private company profiles, from Finks, from public records and news. Updates: as sources update. - Data: Funding rounds, from SEC filings, Finks briefs and newsrooms. Updates: as filed or reported. - Data: Valuation claims, from Finks briefs and SEC filings. Updates: as reported. - Data: Private placements (Form D), from SEC EDGAR. Updates: as filed. - Data: US economic series, from BLS, BEA and Census. Updates: on each release. - Data: Economic calendar, from BLS, BEA, Census and the Federal Reserve. Updates: daily. - Data: FOMC statements and minutes, from The Federal Reserve. Updates: each meeting. - Data: Interest rates, from US Treasury, NY Fed and Bank of Canada. Updates: daily. - Data: Treasury yield curve, from US Treasury. Updates: daily. - Data: Energy spot prices, from EIA. Updates: daily. - Data: FDA actions, from openFDA. Updates: as published. - Data: Clinical trials, from ClinicalTrials.gov. Updates: daily. - Data: Federal Register, from Federal Register. Updates: daily. - Data: Federal contracts, from USAspending.gov. Updates: daily. - Data: Hiring filings, from USCIS and the Department of Labor. Updates: quarterly. ## Search fields `GET /v1/search/fields` (#get-v1-search-fields) What your key can search: pools, datasets, event types and result fields. `format=tool_schema` returns a ready tool definition. ### Parameters - `format` (string, query, can be null): `tool_schema` returns the catalog as a tool-call schema an agent framework registers directly. ### Response - `key_result_fields` (object, required) - `request_fields` (array of object, required) - `result_fields` (array of object, required) - `text_format` (string, required) - `types` (array of object, required): One entry per type whose pool is live right now, with its corpus depth. ### Statuses - 200: The field catalog, or the tool-call schema under `format=tool_schema` - 400: `request.invalid`, an unknown parameter or `format` value - 401: Missing, unknown, revoked, or expired key - 503: `content.unresolved`, no pool could report its depth ### Request ```bash curl -sS "https://data.finks.ai/v1/search/fields?format=tool_schema" \ -H "Authorization: Bearer $FINKS_API_KEY" ``` Not metered. --- > Finks API docs. Every page: https://finks.ai/llms.txt. The OpenAPI spec: https://finks.ai/docs/openapi.json. # Records Go from a search result to the full story. Base URL: https://data.finks.ai. Send your key as `Authorization: Bearer $FINKS_API_KEY`. ## Read a record `GET /v1/content/{id}` (#get-v1-content-id) The full record behind a result `id`: summary, evidence, body or transcript, and a filing's sections. ### Parameters - `id` (string, path, required): A search result's `id`. It is opaque: pass it as it came. ### Response - `id` (string, required): A search result's `id`. It is opaque: pass it as it came. - `symbols` (array of string, required) - `title` (string, required) - `type` (string, required) One of `brief`, `article`, `filing`, `transcript`, `regulator`. - `cik` (string, can be null) - `citation_id` (string, can be null): Filing: permanent identifier of the cited source span. - `confidence` (string, can be null) One of `unverified`, `low`, `medium`, `high`. - `earnings` (object, can be null) - `enriched_at` (string, can be null) - `event_subtype` (string, can be null) - `event_type` (string, can be null): Filing: the event's type, one of the event-type allowlist's slugs (`earnings`, `insider_transaction` for a Form 4, `insider_sale_notice` for a Form 144, `beneficial_ownership` for a Schedule 13D/13G, `periodic_report`, ...). Absent on other types and when the filing's type is not on the allowlist. - `excerpt` (string, can be null): Filing: verbatim text from the source document. - `excerpt_citation_id` (string, can be null): Filing, beside `excerpt` only: the excerpt passage's citation id. - `excerpt_sha256` (string, can be null): Filing, beside `excerpt` only: lower-hex SHA-256 of `excerpt` exactly as served (its UTF-8 bytes, no normalization). - `excerpt_url` (string, can be null): Filing, beside `excerpt` only: the excerpt passage's document URL. - `flags` (array of string, can be null) - `insider` (object, can be null) - `ledger_event_id` (string, can be null): Filing: the event ledger id (`le1:`) of the real-world event this filing proves, shared by an 8-K and its 8-K/As. Absent when the ledger holds no row for it. On a company-timeline brief or article: the event of the 8-K folded into it. - `matched` (string, can be null): Deep search: which half ranked a result. One of `card`, `passage`, `both`. - `passage` (object, can be null): Deep search: the passage of a result that best matches the query: a brief's or article's body, or one of a filing's sections. - `published_at` (string, can be null) - `publishers` (array of string, can be null): Brief, article: publisher domains behind the text. - `regulator` (object, can be null) - `related` (array of object) - `source_sha256` (string, can be null) - `sources` (array of string) - `summary` (string, can be null) - `url` (string, can be null) - `url_kind` (string, can be null): Transcript: what `url` links to, e.g. `sec_8k` (the SEC EDGAR index page of the earnings-release 8-K the call discusses), never a transcript page. Other values may appear: treat an unknown one as another kind of source link. Absent without a `url`. - `amended_by` (string, can be null) - `amends` (string, can be null) - `body` (string, can be null): Brief: the key facts as a CommonMark bullet list, each ending with its outlets, then the context sentence; the stored source-link list is never served. Article: the full article text. Transcript: the call's transcript, verbatim; absent until its text lands or where its rights are not `allow`. - `citations` (array of object, can be null) - `form` (string, can be null): Filing: the form as filed: `8-K`, `8-K/A`, `6-K`, `6-K/A`, a periodic report form (`10-K`, `10-K/A`, `10-KT`, `10-Q`, `10-Q/A`, `10-QT`, `20-F`, `20-F/A`, `40-F`, `40-F/A`), an offering or proxy form (`S-1`, `S-1/A`, `F-1`, `F-1/A`, `424B4`, `424B1`, `DEF 14A`), or another SEC form (`144`, `3`, `4`, `5`, `NT 10-K`, `25-NSE`, `15-12G`, `13F-HR`, `SCHEDULE 13D`, `SCHEDULE 13G`, ..., and their `/A`s). - `item` (string, can be null): Filing: the 8-K item (`2.02`). Absent on a 6-K, a periodic report, an offering or proxy filing or another SEC form. - `sections` (array of object, can be null) - `summary_evidence` (array of object): Filing: the verbatim filing quotes behind each sentence of `summary`. Absent when no sentence has one. ### Statuses - 200: The whole record - 400: `request.invalid`, not an id this API serves; `request.out_of_plan` naming `type`, the plan does not cover the id's pool - 401: Missing, unknown, revoked, or expired key - 410: `withdrawn`, no servable record carries this id - 429: Rate limited or quota denied - 503: `content.unresolved`, the read did not resolve ### Request ```bash # RESULT_ID: the id of a search result. curl -sS "https://data.finks.ai/v1/content/$RESULT_ID" \ -H "Authorization: Bearer $FINKS_API_KEY" ``` Not metered. - Data: Market news, from Finks and financial publishers. Updates: daily. - Data: Earnings call transcripts, from Company earnings calls. Updates: after each call. - Data: SEC filings, from SEC EDGAR. Updates: as filed. ## Filing event `GET /v1/events/{ledger_event_id}` (#get-v1-events-ledger-event-id) One real-world event across its 8-K and every 8-K/A, with the filing record that currently states its facts. An old event id answers with the event it now belongs to. ### Parameters - `ledger_event_id` (string, path, required): A filing's `ledger_event_id`, from a search result or the filing feed. ### Response - `anchor_event_ids` (array of string, required): Every filing event (`e1:`) that proves this event, oldest first: the 8-K, then each 8-K/A (a Form 4, then each 4/A; a 13F, then its amendments). - `current_event_id` (string, required): The filing event (`e1:`) whose facts are current: the newest anchor. - `event_type` (string, required) - `first_filed_at` (string, required): EDGAR acceptance of the first anchor filing, RFC 3339. - `last_filed_at` (string, required): EDGAR acceptance of the newest anchor filing, RFC 3339. - `ledger_event_id` (string, required): A filing's `ledger_event_id`, from a search result or the filing feed. - `subject` (object, required): Whom a ledger event happened to: the 8-K filer, a Form 4's or 13D/13G's issuer, a 13F's filer. - `event_subtype` (string, can be null): The 8-K item (`2.02`); a Form 4's transaction code (`S`, `P`, ...), a 13F's report kind (`report`, `restatement`, `new_holdings`), a 13D/13G's `activist` or `passive`. - `filing` (any, can be null) - `occurred_on` (string, can be null): `YYYY-MM-DD`: the 8-K's date of the earliest event reported; a Form 4's transaction date, a 13F's period end, a 13D/13G's date of the event requiring the filing. ### Statuses - 200: The event and its current filing - 400: `request.invalid`, not a ledger id; `request.out_of_plan`, the plan does not cover `filing` - 401: Missing, unknown, revoked, or expired key - 404: `not_found`, the ledger serves no event under this id - 429: Rate limited or quota denied - 503: `content.unresolved`, the ledger or the filing read did not resolve ### Request ```bash # LEDGER_EVENT_ID: a filing result's ledger_event_id. curl -sS "https://data.finks.ai/v1/events/$LEDGER_EVENT_ID" \ -H "Authorization: Bearer $FINKS_API_KEY" ``` Not metered. - Data: 8-K events, from SEC EDGAR. Updates: as filed. --- > Finks API docs. Every page: https://finks.ai/llms.txt. The OpenAPI spec: https://finks.ai/docs/openapi.json. # Screener Find the companies that match your criteria. Base URL: https://data.finks.ai. Send your key as `Authorization: Bearer $FINKS_API_KEY`. ## Screen companies `POST /v1/screener` (#post-v1-screener) Companies that pass your filters, ranked by any field. - Read GET /v1/screener/fields first: it lists every field's name, type, allowed values and operators. - `operation`: `rank` orders the matches by `ranking`; `filter` returns them by symbol. `subject`: `{ "subject_type": "company" }`. - `predicates`: each a `field`, an `operator` (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `between`, `in`, `not_in`) and a `value`: a number, text or true/false, a list for `in` and `not_in`, or `{ "lower", "upper" }` for `between`. - `ranking`: a list of `{ "field", "direction" }`, `asc` or `desc`. `requested_fields`: what each row returns. `limit`: rows per page, up to your plan's page cap. ### Parameters - `view` (string, query, can be null) ### Request body - `natural_language` (string, can be null): The screen in words (beta). `interpretation` says how it was read. - `query` (object, can be null): The screen. Send this or `natural_language`. ### Response - `coverage` (object, required): How many companies were evaluated and matched. - `data` (array of object, required): One row per company: `fields` maps each requested field to its `value`, with `as_of` and `basis` (`daily`, `ttm`, `fy`). - `normalized_query` (object, required) - `query_id` (string, required): Identity of this immutable run. - `query_version` (integer, required) - `usage` (object, required) - `interpretation` (object, can be null) - `next_cursor` (string, can be null): Send it as `query.cursor`, with the rest of the query unchanged, for the next page. Absent on the last page. - `total_count` (integer, can be null) ### Statuses - 200: One page of the screen, ordered by the ranking (or symbol), with coverage. A screen matching nothing is a 200 with empty `data`. A `natural_language` screen, or one leaving a default implicit, also carries `interpretation` (`defaults_applied`); `normalized_query` states every default and reruns the screen without a model. Under `view=compact`, a `CompactScreenerPage` (`results[]`), each row's `as_of` naming the values dated differently from the page. - 400: `request.invalid` naming the body field or the query parameter (`view`), `request.out_of_plan` naming the allowance (`query.limit` above the plan's screener cap: `screener_search`'s `page_cap`, Free 10 / Starter 50 / Pro 100 / Scale 100; `query.limit` above 100 is `request.invalid`), `invalid_filter`, `unsupported_subject`, `unsupported_field_for_subject` naming the field, `unresolvable_query` (an `as_of` other than the current snapshot, or `natural_language` that maps to nothing: `reason: nothing_mapped`), `invalid_cursor`, or `cursor_expired` (the snapshot was rebuilt) - 401: Missing, unknown, revoked, or expired key - 413: `request.too_large`, the body is over the 2 MB limit - 429: Rate limited, quota denied, or spend cap reached - 501: `natural_language` from an account it is not enabled for, an operation other than `filter` or `rank`, or the plan grants no serving limit - 503: `content.unresolved`, the screen could not be read, or `natural_language` could not be compiled (`reason: compile`) ### Request ```bash curl -sS "https://data.finks.ai/v1/screener" \ -H "Authorization: Bearer $FINKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": { "operation": "rank", "subject": { "subject_type": "company" }, "predicates": [ { "field": "sector", "operator": "eq", "value": "Technology" }, { "field": "ttm_price_to_earnings_ratio", "operator": "between", "value": { "lower": 0, "upper": 25 } } ], "ranking": [ { "field": "market_cap", "direction": "desc" } ], "requested_fields": [ "industry", "market_cap", "price", "revenue", "ttm_net_profit_margin", "sector", "ttm_price_to_earnings_ratio" ], "limit": 10 } }' ``` Metered: one `screener_search` per screen, 10 credits on every plan. - Data: US company screener, from Finks. Updates: daily, current snapshot. ## Screener fields `GET /v1/screener/fields` (#get-v1-screener-fields) Every field you can filter, rank or return. ### Response - `fields` (array of object, required) - `as_of` (string, can be null) ### Statuses - 200: Every screener field: type, unit, operators, basis, live enum values for text fields, freshness source, rights, and whether it is servable today - 401: Missing, unknown, revoked, or expired key ### Request ```bash curl -sS "https://data.finks.ai/v1/screener/fields" \ -H "Authorization: Bearer $FINKS_API_KEY" ``` Not metered. - Data: US company screener, from Finks. Updates: daily, current snapshot. --- > Finks API docs. Every page: https://finks.ai/llms.txt. The OpenAPI spec: https://finks.ai/docs/openapi.json. # Company and filings Follow a company's filings and news as they land. Base URL: https://data.finks.ai. Send your key as `Authorization: Bearer $FINKS_API_KEY`. ## Company timeline `GET /v1/companies/{symbol}/events` (#get-v1-companies-symbol-events) One company's filings and coverage, newest first. - A page can be short, even empty, before the end: keep paging while `has_more` is true. ### Parameters - `symbol` (string, path, required): The company's ticker. - `types` (string, query, can be null): Comma list of `brief`, `article`, `filing`. Default: every type the plan covers. - `event_types` (string, query, can be null): Comma list of event-type slugs (`earnings`, `m_and_a`, ...): only items carrying any of them. An item with no event type is excluded while it is set. Unset, the filings are the 8-Ks and the Form 4 (`insider_transaction`), Form 144 (`insider_sale_notice`) and Schedule 13D/13G (`beneficial_ownership`) filings; the other SEC form filings (`ownership_stake`, `initial_holding`, `insider_annual_transaction`, `late_filing_notice`, `delisting_notice`, `registration_termination`) are listed only when named here. - `published_after` (string, query, can be null): RFC 3339, inclusive. Default: the start of the plan's history window. - `published_before` (string, query, can be null): RFC 3339, exclusive. - `limit` (integer, query, can be null): Results per page: at least 1, at most your plan's page cap. Default 10, or the cap if lower. - `cursor` (string, query, can be null): The `next_cursor` of the previous page. Leave it out for the first page. ### Response - `has_more` (boolean, required) - `results` (array of object, required): Newest first by `published_at`, at most `limit` items, may be empty. - `symbol` (string, required): The company's ticker. - `symbols` (array of string, required): Every listing the timeline matched on: the symbol and the other classes of its issuer (`GOOGL` also matches `GOOG`), sorted. - `next_cursor` (string, can be null): Opaque keyset token for the next, older page. `null` on the last page. - `primary_symbol` (string, can be null): The issuer's primary ticker in SEC's ticker map (`GOOG` -> `GOOGL`, `BRK.A` -> `BRK-B`; a retired ticker of a still-listed issuer, `SQ` -> `XYZ`). Absent when no issuer SEC's map lists is found for the symbol. ### Statuses - 200: The company's items, newest first - 400: `request.invalid` naming the parameter, `request.out_of_plan` naming the allowance, or `invalid_cursor` - 401: Missing, unknown, revoked, or expired key - 404: `not_found`, no company is listed under this symbol - 429: Rate limited, quota denied, or spend cap reached - 501: The plan grants no serving limit - 503: `content.unresolved`, the company lookup or a pool could not answer ### Request ```bash curl -sS "https://data.finks.ai/v1/companies/NVDA/events?limit=10" \ -H "Authorization: Bearer $FINKS_API_KEY" # Next page: the same URL plus &cursor=, while "has_more" is true. A page can be short, even empty, before the end. ``` Metered: one `feed_page` per page. - Data: Market news, from Finks and financial publishers. Updates: daily. - Data: SEC filings, from SEC EDGAR. Updates: as filed. - Data: Company timeline, from Finks briefs and SEC filings. Updates: daily. ## Filing feed `GET /v1/content` (#get-v1-content) SEC filings, newest first, filtered by form, company and date. ### Parameters - `type` (string, query, can be null): `filing`, the type this route lists. - `symbols` (string, query, can be null): ANY within, AND across filters. - `entities` (string, query, can be null): Canonical entity ids. - `entity_match` (string, query, can be null): `any` (default) or `all`. Without `entities`, a 400. - `sectors` (string, query, can be null): Accepted and ignored: it filters nothing today. - `themes` (string, query, can be null): Taxonomy facet. - `event_types` (string, query, can be null): Matches the scalar `event_type` or the `event_types[]` array. Each slug must be on the event-type allowlist; any other is a 400. - `geos` (string, query, can be null): Taxonomy facet. - `form` (string, query, can be null) - `cik` (string, query, can be null) - `published_after` (string, query, can be null): RFC 3339, inclusive. Half-open interval with `published_before`. - `published_before` (string, query, can be null): RFC 3339, exclusive. - `min_confidence` (string, query, can be null) - `include_full_text` (boolean, query, can be null): Ask for the raw primary-document text. Not every document can be served in full: read `full_text_status` for the outcome. - `cursor` (string, query, can be null): The `next_cursor` of the previous page. Leave it out for the first page. - `limit` (integer, query, can be null): Results per page: at least 1, at most your plan's page cap. Default 10, or the cap if lower. - `view` (string, query, can be null): `full` (default): the full record. `compact`: one small `CompactFilingRecord` per filing (no evidence, citations, facets, versions or rights fields) and a `summary` block; the page is a `CompactContentPage`. Compact takes no `include_full_text=true`. - `order` (string, query, can be null): `asc` (default): oldest first. `desc`: newest first. The cursor binds the order. - `group_by` (string, query, can be null): `accession`, with `view=compact` only: filings sharing an accession on the page collapse into the first one's entry, the rest under its `parts`. ### Response - `data` (array of object, required) - `has_more` (boolean, required) - `next_cursor` (string, can be null): Opaque server-issued token. `null` when this is the last page. ### Statuses - 200: One page of filing records: a `ContentPage`, or a `CompactContentPage` under `view=compact` - 400: `request.invalid`, `invalid_cursor`, or `request.out_of_plan` naming `filing` - 401: Missing, unknown, revoked, or expired key - 429: Rate limited, quota denied, or spend cap reached - 501: A parameter this deployment cannot honestly answer - 503: `content.unresolved`, the read did not resolve ### Request ```bash curl -sS "https://data.finks.ai/v1/content?type=filing&form=8-K&limit=10" \ -H "Authorization: Bearer $FINKS_API_KEY" ``` Metered: one `feed_page` per page. - Data: SEC filings, from SEC EDGAR. Updates: as filed. - Data: 8-K events, from SEC EDGAR. Updates: as filed. --- > Finks API docs. Every page: https://finks.ai/llms.txt. The OpenAPI spec: https://finks.ai/docs/openapi.json. # Account Check your plan, your usage and what your key can reach. Base URL: https://data.finks.ai. Send your key as `Authorization: Bearer $FINKS_API_KEY`. ## Account `GET /v1/account` (#get-v1-account) Your account and its plan limits. ### Response - `account_id` (string, required) - `alert_thresholds` (one of several shapes, required) - `keys` (one of several shapes, required): The account's keys. The list is a query against an eventually-consistent secondary index, so a key minted or revoked moments ago may be missing or stale here while authentication, which is strongly consistent, already reflects it. - `metering` (one of several shapes, required): Whether usage is being counted. Always `on`: every billable response is recorded a few seconds after it is served, so the usage figures below include all billable usage except the last few seconds. - `period` (object, required) - `spend_cap` (one of several shapes, required) - `units` (array of object, required) - `agent_search_daily_jobs` (object, required, can be null): `GET /v1/account`'s `research_daily_jobs`: today's research jobs against the account's daily cap. - `features` (array of object, required) - `profile` (object, required, can be null) - `research_daily_jobs` (object, required, can be null): `GET /v1/account`'s `research_daily_jobs`: today's research jobs against the account's daily cap. ### Statuses - 200: The calling account's state for the current billing period, with its sign-up profile - 401: Missing, unknown, revoked, or expired key ### Request ```bash curl -sS "https://data.finks.ai/v1/account" \ -H "Authorization: Bearer $FINKS_API_KEY" ``` Not metered. ## Keys `GET /v1/account/keys` (#get-v1-account-keys) The account's keys, masked, with each one's environment and status. ### Response - `account_id` (string, required) - `keys` (one of several shapes, required): The account's keys. The list is a query against an eventually-consistent secondary index, so a key minted or revoked moments ago may be missing or stale here while authentication, which is strongly consistent, already reflects it. ### Statuses - 200: The calling account's masked keys - 401: Missing, unknown, revoked, or expired key ### Request ```bash curl -sS "https://data.finks.ai/v1/account/keys" \ -H "Authorization: Bearer $FINKS_API_KEY" ``` Not metered. ## Usage `GET /v1/account/usage` (#get-v1-account-usage) Usage for one month, the current UTC month by default, per billable unit. ### Parameters - `period` (string, query, can be null): The month, `YYYY-MM`. Default: the current UTC month. ### Response - `account_id` (string, required) - `metering` (one of several shapes, required): Whether usage is being counted. Always `on`: every billable response is recorded a few seconds after it is served, so the usage figures below include all billable usage except the last few seconds. - `period` (object, required): The month, `YYYY-MM`. Default: the current UTC month. - `units` (array of object, required) ### Statuses - 200: The calling account's recorded usage for one billing period - 400: `request.invalid`, a malformed or repeated `period` - 401: Missing, unknown, revoked, or expired key ### Request ```bash curl -sS "https://data.finks.ai/v1/account/usage" \ -H "Authorization: Bearer $FINKS_API_KEY" ``` Not metered. ## Datasets `GET /v1/datasets` (#get-v1-datasets) Every dataset Finks serves, with its routes and source, and whether your plan includes it. ### Response - `results` (array of object, required): The pools, then the data-block datasets, then the route-only names, each in vocabulary order. - `tier` (string, can be null): The tier the key's account resolves to. Absent when no entitlement can be proven; every `granted` is then `false`. ### Statuses - 200: Every pool, dataset and route-only name, and whether this key's plan includes it - 401: Missing, unknown, revoked, or expired key ### Request ```bash curl -sS "https://data.finks.ai/v1/datasets" \ -H "Authorization: Bearer $FINKS_API_KEY" ``` Not metered.