> 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": <next_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.