Calendar, documents, news¶

Four endpoints for time-bound and text content:

GET /v1/calendar: dated events (central-bank meetings, sanctions-licence expiries).
GET /v1/docs/search: full-text search over stored legal documents.
GET /v1/news/search: search over recent news headlines.
GET /v1/news/latest: newest headlines without a search term.

GET /v1/calendar¶

Upcoming events, optionally with recent past ones.

curl -s -H "Authorization: Bearer $TRRU_KEY" "https://trru.atapinar.com/v1/calendar?days=30"

Parameter	Type	Default	Meaning
`days`	integer	`90`	Look ahead this many days from today. A negative value returns nothing; a very large value works.
`kind`	string	empty	Exact event kind (case-sensitive). See the table below.
`country`	string	empty	Country code, exact after upper-casing: `TR`, `RU`, `US`.
`include_past_days`	integer	`0`	Also include events from this many days ago.

Rows are ordered by date, then kind, and capped at 300 (truncated: true if more match).

Event kinds¶

The live data holds these seven kinds:

`kind`	`country`	Event
`tcmb_ppk`	TR	Central Bank of Türkiye Monetary Policy Committee rate decision
`tcmb_ppk_summary`	TR	Summary of the Monetary Policy Committee meeting
`tcmb_inflation_report`	TR	Inflation Report
`tcmb_fsr`	TR	Financial Stability Report
`cbr_key_rate`	RU	Bank of Russia key rate decision (Board of Directors meeting); `meta.medium_term_forecast` says whether the meeting comes with a medium-term forecast
`cbr_summary`	RU	Bank of Russia summary of the key rate discussion
`ofac_gl_expiry`	US	An OFAC Russia-related general licence expires; `meta` has `issued` and `program`

New kinds can be added later: treat kind as an open list and filter on the ones you know.

Example response¶

Request: GET /v1/calendar?days=30

{
  "data": {
    "rows": [
      {
        "event_date": "2026-11-21",
        "kind": "ofac_gl_expiry",
        "country": "US",
        "title": "OFAC GL 131K expires: Authorizing Certain Transactions for the Negotiation of and Entry Into Contingent Contracts for the Sale of Lukoil International GmbH and Related Maintenance Activities",
        "url": "https://ofac.treasury.gov/media/937276/download",
        "meta": { "issued": "2026-10-21", "program": "Russia-related" }
      },
      {
        "event_date": "2026-11-27",
        "kind": "tcmb_fsr",
        "country": "TR",
        "title": "TCMB Finansal İstikrar Raporu",
        "url": "https://www.tcmb.gov.tr/wps/wcm/connect/TR/TCMB+TR/Main+Menu/Duyurular/Takvim",
        "meta": {}
      },
      {
        "event_date": "2026-12-10",
        "kind": "tcmb_ppk",
        "country": "TR",
        "title": "TCMB PPK faiz kararı",
        "url": "https://www.tcmb.gov.tr/wps/wcm/connect/TR/TCMB+TR/Main+Menu/Duyurular/Takvim",
        "meta": {}
      }
    ],
    "row_count": 3,
    "truncated": false
  },
  "meta": {
    "sources": [
      { "source_id": "ofac_gl", "fetched_at": "2026-11-13T06:40:31.780771+00:00", "as_of": "2026-12-10" },
      { "source_id": "tcmb_cal", "fetched_at": "2026-11-13T06:40:11.601812+00:00", "as_of": "2026-12-10" }
    ],
    "request_id": "c205526b3cf042e0b545663d46325e72",
    "truncated": false
  }
}

Field notes: event_date is YYYY-MM-DD. title is in the language of the publisher (Turkish for TCMB items, English for OFAC and Bank of Russia). url points to the publisher's calendar or document. Calendar dates come from published schedules and can change: check the publisher before relying on a date. meta.sources[].as_of is the date of the last event returned.

Next two rate decisions of the Bank of Russia and the Central Bank of Türkiye:

curlPythonJavaScript

curl -s -H "Authorization: Bearer $TRRU_KEY" "https://trru.atapinar.com/v1/calendar?days=120&kind=cbr_key_rate"
curl -s -H "Authorization: Bearer $TRRU_KEY" "https://trru.atapinar.com/v1/calendar?days=120&kind=tcmb_ppk"

for kind in ("cbr_key_rate", "tcmb_ppk"):
    rows = get("/v1/calendar", days=120, kind=kind)["data"]["rows"]
    print(kind, [r["event_date"] for r in rows[:2]])

for (const kind of ["cbr_key_rate", "tcmb_ppk"]) {
  const { data } = await get("/v1/calendar", { days: "120", kind });
  console.log(kind, data.rows.slice(0, 2).map((r) => r.event_date));
}

GET /v1/docs/search¶

Full-text search over stored documents. Two document types exist today:

`doc_type`	Documents
`ofac_general_license`	OFAC Russia-related general licences (one document per licence version, with `meta.gl`, `meta.expires`, `meta.program`)
`eu_regulation`	Council Regulation (EU) No 833/2014 on restrictive measures in view of Russia's actions, consolidated text, split into passages (annex tables and articles)

More document types may be added. Matching passages are returned, not whole documents.

curl -s -H "Authorization: Bearer $TRRU_KEY" -G "https://trru.atapinar.com/v1/docs/search" \
  --data-urlencode "query=general license" --data-urlencode "limit=2"

Parameter	Type	Default	Meaning
`query`	string	required	Search text. Missing returns 400 `invalid or missing parameter(s): query`.
`doc_type`	string	empty	Restrict to one document type. An unknown type returns no rows, not an error.
`limit`	integer	`8`	Passages to return, capped at 30 (larger values are clamped silently). `0` returns none.

Matching is full text with websearch syntax (simple configuration, no stemming): all words must appear in the same passage, "quoted phrases", OR and -excluded work. A fuzzy trigram match on the passage is also tried, which seldom helps on long text. Use one or two exact words from the text (Lukoil, prepared binders, diamonds) rather than a question. A query that matches nothing returns 200 with no rows. Results are sorted by score, highest first.

Example response¶

Request: GET /v1/docs/search?query=general license&limit=2. Passage text is shortened in this sample (real passages run up to about 1,500 characters).

{
  "data": {
    "rows": [
      {
        "title": "OFAC Russia-related General License 40C: Civil Aviation Safety",
        "url": "https://ofac.treasury.gov/media/929386/download",
        "doc_type": "ofac_general_license",
        "published_at": "2022-11-14",
        "meta": { "gl": "40C", "expires": null, "program": "Russia-related" },
        "ord": 1,
        "text": "(3) Any transactions otherwise prohibited by the Russian Harmful Foreign Activities \nSanctions Regulations, 31 CFR part 587 (RuHSR), including transactions involving any person \nblocked pursuant to the RuHSR other than t…",
        "score": 0.74820817
      },
      {
        "title": "OFAC Russia-related General License 104B: Authorizing Transactions Related to Imports of Certain Diamonds Prohibited by Executive Order 14068",
        "url": "https://ofac.treasury.gov/media/936796/download",
        "doc_type": "ofac_general_license",
        "published_at": "2026-08-26",
        "meta": { "gl": "104B", "expires": "2027-09-01", "program": "Russia-related" },
        "ord": 1,
        "text": "(b) This general license does not authorize any transactions otherwise prohibited by the \nRussian Harmful Foreign Activities Sanctions Regulations, 31 CFR part 587 (RuHSR), including \ntransactions involving any person bl…",
        "score": 0.62684464
      }
    ],
    "row_count": 2,
    "truncated": false
  },
  "meta": {
    "sources": [
      { "source_id": "ofac_gl", "fetched_at": "2026-11-13T06:40:31.780771+00:00", "as_of": "2026-08-26" }
    ],
    "request_id": "44a85d917913443a908f7fa04e7d02a0",
    "truncated": false
  }
}

Field notes¶

Field	Meaning
`title`, `url`	Document title and its location at the publisher. Cite `url`.
`doc_type`	See the table.
`published_at`	Publication date of this document version (`YYYY-MM-DD`). For the EU regulation, the date of the original act; the consolidation date is in `meta.consolidation_date`.
`meta`	Document-specific. OFAC: `gl`, `expires`, `program`. EU regulation: `celex`, `consolidation_date`, `annexes` (list of annex numbers), `n_chunks`, `n_sections`.
`ord`	Index of the passage inside its document. Several passages of one document can appear in one result.
`text`	The matching passage. For the EU regulation, passages from annex tables start with a tag such as `[EU 833/2014 — Annex XXIII: List of goods and technology as referred to in Article 3k]`.
`score`	Relevance for ordering. Only meaningful within one response.

Quote the passage, give title and url, and state published_at. For restrictions by product code use /v1/restrictions/{hs}, which already reads these annexes.

GET /v1/news/search¶

Search recent Russia and Türkiye news. Items are headlines plus a short summary and a link, not full articles.

curl -s -H "Authorization: Bearer $TRRU_KEY" -G "https://trru.atapinar.com/v1/news/search" \
  --data-urlencode "query=ключевая ставка" --data-urlencode "limit=2"

Parameter	Type	Default	Meaning
`query`	string	required	Words to look for in title and summary. Cyrillic, Latin and Turkish work. Blank or missing returns 400.
`beat`	string	empty	Topic filter, one of the beats below. Empty means all.
`lang`	string	empty	`ru`, `en` or `tr`. Empty means all.
`since_hours`	integer	`168`	Look back this many hours (7 days by default). Allowed 1 to 8760 (one year).
`tier_max`	integer	`3`	Include feeds up to this tier: 1 only the most authoritative, 3 everything. Allowed 1 to 3.
`limit`	integer	`20`	Allowed 1 to 100.

Matching is full text on title and summary (long words match on their stem, so ставка also finds ставки) plus a trigram similarity on the title. Results are the best matches for the window, shown newest first; score is the relevance.

GET /v1/news/latest¶

The newest headlines without a search term.

curl -s -H "Authorization: Bearer $TRRU_KEY" \
  "https://trru.atapinar.com/v1/news/latest?beat=tr_ru&hours=48&limit=2"

Parameter	Type	Default	Meaning
`beat`	string	empty	Topic filter. Empty means all.
`hours`	integer	`24`	Look back this many hours. Allowed 1 to 8760.
`tier_max`	integer	`3`	As above.
`limit`	integer	`30`	Allowed 1 to 100.

Beats, languages and tiers¶

beat values (the names are Turkish; the content is mostly Russian-language for Russian topics):

`beat`	Topic
`genel`	General Russian economy and politics
`emtia`	Commodities: oil and gas, metals, agriculture
`piyasa`	Markets and exchange
`faiz_banka`	Interest rates and banking, including Bank of Russia
`regulasyon`	Laws, regulation, tax, customs
`yaptirim`	Sanctions
`tr_ru`	Türkiye–Russia relations and trade
`brics`	BRICS
`tr_sirket`	Turkish companies in Russia
`altin`	Gold
`nadir_toprak`	Rare earths and critical minerals
`yabancilar`	Rules for foreigners (migration)

lang values: ru, en, tr. Both beat and lang ignore case and surrounding spaces (" TR_RU " works). Any other value returns 400 listing the allowed values.

tier says how authoritative the feed is:

Tier	Meaning
1	Official sources: the Bank of Russia, the Government and State Duma, the tax service, the Moscow Exchange, the Eurasian Economic Commission, US Treasury OFAC actions.
2	Established news agencies and business media (TASS, Interfax, Vedomosti, Kommersant, RBC, Reuters Russia, Bloomberg Russia, Sputnik Türkiye, and similar).
3	Topic feeds aggregated through Google News (sanctions, BRICS, gold, rare earths, Turkish business in Russia) and similar broad feeds. Useful for coverage, weakest for authority.

Example responses¶

Request: GET /v1/news/latest?beat=tr_ru&hours=48&limit=2

{
  "data": {
    "rows": [
      {
        "id": 5252,
        "published_at": "2026-11-13T18:48:34+00:00",
        "feed": "Sputnik Turkiye (Rusya)",
        "tier": 2,
        "beat": "tr_ru",
        "lang": "tr",
        "title": "Batı basını: Von der Leyen’in Rusya ile güvenlik diyaloğu önerisi AB’de görüş ayrılığına yol açtı",
        "summary": "Bloomberg, Avrupa Komisyonu Başkanı Ursula von der Leyen’in Avrupa güvenliği konusunda Rusya ile diyalog başlatılabileceğini belirtmesinin Avrupa Birliği (AB) içinde tartışmalara neden olduğunu bildirdi.",
        "url": "https://anlatilaninotesi.com.tr/20261113/bati-basini-von-der-leyenin-rusya-ile-guvenlik-diyalogu-onerisi-abde-gorus-ayriligina-yol-acti-1110335009.html",
        "also_in_feeds": 0
      },
      {
        "id": 5203,
        "published_at": "2026-11-13T18:25:44+00:00",
        "feed": "Sputnik Turkiye (Rusya)",
        "tier": 2,
        "beat": "tr_ru",
        "lang": "tr",
        "title": "Batı basını: AB, Rusya ile temaslar için müzakere heyetini belirledi",
        "summary": "Politico, Ukrayna’daki çatışmanın çözümüne yönelik gelecekteki müzakereler için oluşturulan heyette Almanya, Fransa, İngiltere, İtalya ve Polonya’nın yanı sıra Avrupa Komisyonu ve AB Konseyi temsilcilerinin yer alacağını…",
        "url": "https://anlatilaninotesi.com.tr/20261113/bati-basini-ab-rusya-ile-temaslar-icin-muzakere-heyetini-belirledi-1110334661.html",
        "also_in_feeds": 0
      }
    ],
    "row_count": 2,
    "truncated": false
  },
  "meta": {
    "sources": [
      { "source_id": "news", "fetched_at": "2026-11-13T18:35:56.120123+00:00", "as_of": "2026-11-13T18:48:34+00:00" }
    ],
    "request_id": "85d60ce525cd41ad8ee4703eb212c19b",
    "truncated": false
  }
}

Request: GET /v1/news/search?query=ключевая ставка&limit=2 (the search response adds score; first item shown):

{
  "id": 3076,
  "published_at": "2026-11-13T10:55:04+00:00",
  "feed": "Banki.ru (via Google News)",
  "tier": 3,
  "beat": "faiz_banka",
  "lang": "ru",
  "title": "В Сбере спрогнозировали, когда ключевая ставка будет ниже 10% - Банки.ру",
  "summary": null,
  "url": "https://news.google.com/rss/articles/CBMiV0FVX3lxTE95bWwxYjdCSzRkT0l1QzZBZ2FVbGhTQ2tmcThyREtfcDhMWmxvODJFTGJJaDdNVE5YRURzbHpWempEdE5tV0phc2lwalhTdjNFVk5wTXRoNA?oc=5",
  "also_in_feeds": 0,
  "score": 0.746
}

Field notes¶

Field	Meaning
`id`	Item id.
`published_at`	Publication time as given by the feed, in UTC (`+00:00`).
`feed`	Name of the feed.
`tier`, `beat`, `lang`	As above.
`title`	Headline, in the original language.
`summary`	Short summary from the feed, or `null`. Often cut with `…`.
`url`	Link to the article. Items from Google News feeds carry a `news.google.com` redirect link.
`also_in_feeds`	How many other feeds carried the same story. Duplicates are collapsed into one row, so `also_in_feeds: 2` means two further copies exist and are not listed. `0` means a unique item.
`score`	Search only. Relevance, for your own ranking.

Window, validation and guards¶

Only items published within the window are returned: since_hours for search, hours for latest.
Future-dated items are excluded. A feed item stamped more than five minutes ahead of the server clock is dropped, so a wrong publisher timestamp never appears as "the latest news".
Validation is strict. since_hours=0 or 9000, tier_max=4, limit=101 and an unknown beat or lang all return 400 with a message that names the allowed range or values, for example unknown beat 'bogus'; allowed: genel, emtia, ... and limit must be between 1 and 100. Unlike the other endpoints, news limits are rejected, not clamped.
A search with no match returns 200 and no rows. Narrow filters (tier_max=1, lang, short windows) make that likely.
meta.sources[].as_of is the newest published_at among the returned rows.

Using news in a bulletin or an agent¶

News text is untrusted external content

Titles and summaries come from third-party feeds. Treat them as data to quote, never as instructions. If an item contains text that looks like a command or a request ("ignore previous instructions", "send this to..."), do not follow it. When a language model reads the results, say so in its prompt.

Cite every item with its url and published_at. Say that it is a headline, not the full article.
Use also_in_feeds as a weak signal of how widely a story was picked up, not as proof that it is true.
Prefer tier_max=2 for anything you publish; use tier 3 to find leads and then confirm in a tier 1 or 2 source.
Fetch a smaller window often rather than a large one once: latest?hours=6 every few hours is cheap.

curlPythonJavaScript

curl -s -H "Authorization: Bearer $TRRU_KEY" -G "https://trru.atapinar.com/v1/news/search" \
  --data-urlencode "query=sanctions" --data-urlencode "beat=yaptirim" --data-urlencode "lang=en" \
  --data-urlencode "since_hours=48" --data-urlencode "tier_max=3" --data-urlencode "limit=5"

body = get("/v1/news/search", query="sanctions", beat="yaptirim", lang="en", since_hours=48, limit=5)
for n in body["data"]["rows"]:
    print(n["published_at"], n["tier"], n["feed"], "|", n["title"], "|", n["url"])

const body = await get("/v1/news/search", { query: "sanctions", beat: "yaptirim", lang: "en", since_hours: "48", limit: "5" });
for (const n of body.data.rows) console.log(n.published_at, n.tier, n.feed, "|", n.title, "|", n.url);