newsmetry
enвойтиначать

документация · версия 1.0 · rest · json

newsmetry api

новости рынков одним api: лента без задержки, полный текст, ссылка на оригинал и время публикации.

01обзор

базовый адрес всех методов: https://api.newsmetry.xyz/api/v1

лента приходит в api сразу, как только новость собрана целиком. на сайте newsmetry те же события открываются с задержкой 15 минут.

спецификация openapi и интерактивная консоль: swagger ↗

02быстрый старт

  1. получите ключ: запросите его в личном кабинете. ключ выглядит как nag_… и показывается один раз — сохраните его.
  2. передайте ключ в заголовке Authorization: Bearer <ключ>.
  3. запросите ленту — и всё.
curl
curl -H "Authorization: Bearer $NEWS_API_KEY" \
     "https://api.newsmetry.xyz/api/v1/news?limit=5"
python
import os, requests

API = "https://api.newsmetry.xyz/api/v1"
headers = {"Authorization": f"Bearer {os.environ['NEWS_API_KEY']}"}
r = requests.get(API + "/news?limit=5", headers=headers, timeout=30)
r.raise_for_status()
print(r.json())
javascript
const API = "https://api.newsmetry.xyz/api/v1";
const res = await fetch(API + "/news?limit=5", {
  headers: { Authorization: `Bearer ${process.env.NEWS_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.message);
console.log(await res.json());

03ключ и авторизация

каждый запрос, кроме /health, требует ключ. подойдёт любой из двух заголовков:

Authorization: Bearer nag_…
X-API-Key: nag_…

отправляйте ключ только с сервера, никогда из браузера.

04лимиты и тарифы

каждый ключ ограничен тремя способами. все три видны в заголовках ответа, превышение — ответ 429 с заголовком Retry-After.

rate limitзапросов в секунду и в минуту, окна скользящие.
throttlingсколько запросов с одного ключа может выполняться одновременно.
квотазапросов к ленте за сутки. сброс в 00:00 utc.
тарифквота / суткив секундув минутуодновременноновостей на страницу
Freeпробный доступ: 5 запросов в сутки515150
Proрабочий доступ: 1000 запросов в сутки1 00051204500

квоту тратят только запросы к новостям (/news, /news/{id}). /me и /health — бесплатно. если сервер ответил ошибкой 5xx, запрос квоте возвращается.

05страницы и опрос новинок

лента листается курсором, а не номером страницы: в ответе есть next_cursor — передайте его параметром cursor, чтобы получить следующую порцию. пока has_more = true, есть ещё.

чтобы забирать только новое, читайте с order=asc и сохраняйте next_cursor — он отдаётся и на последней странице. в следующий раз начните с него: придут только новости, появившиеся после.

python — опрос раз в минуту
import os, time, requests

API = "https://api.newsmetry.xyz/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['NEWS_API_KEY']}"
cursor = None  # храните между запусками — в файле или базе

while True:
    params = {"order": "asc", "limit": 50}
    if cursor:
        params["cursor"] = cursor
    r = session.get(f"{API}/news", params=params, timeout=30)
    if r.status_code == 429:  # лимит или квота — ждём, сколько сказали
        time.sleep(int(r.headers.get("Retry-After", "60")))
        continue
    r.raise_for_status()
    page = r.json()
    for item in page["items"]:
        print(item["published_at"], item["title"])
    cursor = page["next_cursor"] or cursor
    if not page["has_more"]:
        time.sleep(60)

новость попадает в ленту и получает id, когда готова целиком — с полным текстом. если текста у новости нет и не будет (короткая молния), она приходит с body_status = "empty".

06объект новости

id stringидентификатор новости. растёт с каждой новой новостью — по нему идёт курсор.
title stringзаголовок.
summary string | nullлид или краткое описание.
body string | nullполный текст.
body_status stringfull — текст есть; empty — текста нет и не будет (короткая молния).
url string | nullссылка на оригинал.
image_url string | nullкартинка.
lang string | nullязык: en, ru.
tags string[]рубрики.
published_at iso 8601время публикации, utc.
collected_at iso 8601когда новость появилась в newsmetry.
updated_at iso 8601последнее изменение записи.
{
  "id": "48213",
  "title": "Fed holds rates steady, signals two cuts in 2027",
  "summary": "The Federal Reserve left its benchmark rate unchanged on Wednesday…",
  "body": "WASHINGTON — The Federal Reserve held interest rates steady…",
  "body_status": "full",
  "url": "https://www.reuters.com/markets/us/fed-holds-rates-2026-10-12/",
  "image_url": "https://www.reuters.com/resizer/…/fed.jpg",
  "lang": "en",
  "tags": [],
  "published_at": "2026-10-12T18:02:11Z",
  "collected_at": "2026-10-12T18:07:40Z",
  "updated_at": "2026-10-12T18:07:40Z"
}

все id — строки: числа такой длины javascript теряет. время — iso 8601 в utc с суффиксом Z.

07ошибки

любая ошибка — json одного вида:

{
  "error": {
    "code": "quota_exceeded",
    "message": "суточная квота исчерпана (1000 запросов), сброс в 00:00 UTC"
  }
}
400 invalid_parameterневерный параметр: в message — какой и что ожидалось, в details — список полей.
401 unauthorizedключа нет, он неизвестен или перевыпущен.
403 forbiddenдоступ отключён администратором или истёк срок ключа.
404 not_foundнет такой новости или такого пути.
429 rate_limitedслишком часто: превышен лимит в секунду или в минуту. подождите Retry-After секунд.
429 throttledслишком много одновременных запросов с одного ключа. повторите через секунду.
429 quota_exceededсуточная квота исчерпана. сброс в 00:00 utc, до него — Retry-After секунд.
503 unavailableвременная недоступность. повторите через Retry-After секунд.

08заголовки ответа

X-RateLimit-Limitлимит запросов в минуту по тарифу.
X-RateLimit-Remainingсколько ещё можно в текущей минуте.
X-RateLimit-Resetкогда освободится окно (unix-время, секунды).
X-Quota-Limitсуточная квота (только у запросов, которые её тратят).
X-Quota-Remainingостаток квоты на сегодня.
X-Quota-Resetсброс квоты — ближайшая полночь utc (unix-время).
Retry-Afterчерез сколько секунд повторять — у ответов 429 и 503.

09лента новостей

GET/newsтратит квоту

новости, свежие первыми.

limit integer · по умолчанию 50сколько новостей вернуть: от 1 до потолка тарифа.
cursor stringnext_cursor из предыдущего ответа — следующая страница.
order desc | asc · по умолчанию descdesc — от новых к старым, asc — от старых к новым (для опроса «что нового»).
lang stringязык: en, ru.
q stringподстрока заголовка, без учёта регистра (до 200 символов).
from iso 8601опубликовано не раньше, например 2026-10-12T00:00:00Z.
to iso 8601опубликовано не позже.
curl
curl -H "Authorization: Bearer $NEWS_API_KEY" \
     "https://api.newsmetry.xyz/api/v1/news?limit=5"
пример ответа · 200
{
  "items": [
    {
      "id": "48213",
      "title": "Fed holds rates steady, signals two cuts in 2027",
      "summary": "The Federal Reserve left its benchmark rate unchanged on Wednesday…",
      "body": "WASHINGTON — The Federal Reserve held interest rates steady…",
      "body_status": "full",
      "url": "https://www.reuters.com/markets/us/fed-holds-rates-2026-10-12/",
      "image_url": "https://www.reuters.com/resizer/…/fed.jpg",
      "lang": "en",
      "tags": [],
      "published_at": "2026-10-12T18:02:11Z",
      "collected_at": "2026-10-12T18:07:40Z",
      "updated_at": "2026-10-12T18:07:40Z"
    }
  ],
  "has_more": true,
  "next_cursor": "48213",
  "meta": {
    "quota_limit": 1000,
    "quota_remaining": 987
  }
}

10одна новость

GET/news/{id}тратит квоту

новость по id.

id string · обязательныйидентификатор новости из ленты.
curl
curl -H "Authorization: Bearer $NEWS_API_KEY" \
     "https://api.newsmetry.xyz/api/v1/news/48213"
пример ответа · 200
{
  "id": "48213",
  "title": "Fed holds rates steady, signals two cuts in 2027",
  "summary": "The Federal Reserve left its benchmark rate unchanged on Wednesday…",
  "body": "WASHINGTON — The Federal Reserve held interest rates steady…",
  "body_status": "full",
  "url": "https://www.reuters.com/markets/us/fed-holds-rates-2026-10-12/",
  "image_url": "https://www.reuters.com/resizer/…/fed.jpg",
  "lang": "en",
  "tags": [],
  "published_at": "2026-10-12T18:02:11Z",
  "collected_at": "2026-10-12T18:07:40Z",
  "updated_at": "2026-10-12T18:07:40Z"
}

11мой ключ и квота

GET/meквоту не тратит

тариф, лимиты и сколько запросов осталось на сегодня. квоту не тратит — удобно для мониторинга.

curl
curl -H "Authorization: Bearer $NEWS_API_KEY" \
     "https://api.newsmetry.xyz/api/v1/me"
пример ответа · 200
{
  "id": "17",
  "name": "Trading bot",
  "key_prefix": "nag_q8Jx2LmA",
  "key_expires_at": null,
  "plan": {
    "code": "pro",
    "name": "Pro",
    "daily_quota": 1000,
    "rate_per_second": 5,
    "rate_per_minute": 120,
    "max_concurrency": 4,
    "max_page_size": 500,
    "unlimited": false
  },
  "quota": {
    "used": 13,
    "remaining": 987,
    "reset_at": "2026-10-13T00:00:00Z"
  }
}

12состояние сервиса

GET/healthбез ключа

работает ли api и идёт ли сбор. ключ не нужен.

curl
curl "https://api.newsmetry.xyz/api/v1/health"
пример ответа · 200
{
  "status": "ok",
  "service": "newsmetry",
  "version": "1.0",
  "time": "2026-10-12T18:08:12Z",
  "db": "ok",
  "redis": "ok",
  "worker": "running"
}