Документация API: REST и MCP

Доступ по ключу API

Ключ передаётся в заголовке каждого запроса. Выпускается в кабинете после оформления подписки или пробного доступа и показывается один раз. До пяти ключей на аккаунт, лимит строк общий. Потеряли ключ: отзовите его в кабинете и выпустите новый.

Authorization: Bearer tbz_live_...

Получить пробный доступ

Попробовать API без регистрации можно с демо-ключом из раздела «Быстрый старт».

Когда подписка закончится, запросы перестанут проходить; после продления тот же ключ снова заработает.

REST API

Адрес запроса: https://api.tebiz.ru/v1/<набор>. Ответ приходит в JSON: {"data":[...],"next_cursor":...}.

Фильтры

Фильтр записывается как ?поле=оператор.значение, несколько фильтров объединяются по И. Фильтровать можно только поля с меткой «фильтр», а доступные операторы зависят от типа поля: то и другое указано на странице набора.

curl -G "https://api.tebiz.ru/v1/financials" \
  -d "year=eq.2025" \
  -d "select=year,inn,name,okved,2110" \
  -d "limit=5" \
  -H "Authorization: Bearer tbz_live_..."

Выбор полей и лимит

select=a,b,c вернёт только эти поля. limit=N задаёт размер страницы, не больше максимума набора. В одном запросе до 50 фильтров, в списке in до 1000 значений.

Пагинация курсором

API отдаёт данные страницами. Сортировки нет: строки идут по полям курсора, они указаны на странице набора. Если в ответе next_cursor не null, повторите запрос с теми же фильтрами и cursor=<значение>. Повторяйте, пока не придёт null.

Первый запрос к большому набору (больше 2 млн строк) делайте с фильтром, например ?year=eq.2024. Без фильтра и курсора такой запрос вернёт ошибку 400 с подсказкой.

cursor = None
while True:
    params = {"year": "eq.2024", "limit": 500}
    if cursor:
        params["cursor"] = cursor
    body = requests.get(URL, headers=HEADERS, params=params).json()
    process(body["data"])
    cursor = body["next_cursor"]
    if not cursor:            # null: данные закончились
        break

Лимиты в заголовках

MCP для ИИ-агентов

Адрес MCP-сервера: https://api.tebiz.ru/mcp/. Транспорт Streamable HTTP, ключ тот же, что для REST API, в заголовке Authorization: Bearer tbz_live_.... Имя сервера в конфигах: tebiz-data.

Подключение

claude mcp add --transport http tebiz-data https://api.tebiz.ru/mcp/ \
  --header "Authorization: Bearer tbz_live_..."

{
  "mcpServers": {
    "tebiz-data": {
      "url": "https://api.tebiz.ru/mcp/",
      "headers": {
        "Authorization": "Bearer tbz_live_..."
      }
    }
  }
}

{
  "servers": {
    "tebiz-data": {
      "type": "http",
      "url": "https://api.tebiz.ru/mcp/",
      "headers": {
        "Authorization": "Bearer ${input:tebiz-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "tebiz-key",
      "description": "Ключ Tebiz Data",
      "password": true
    }
  ]
}

{
  "mcpServers": {
    "tebiz-data": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.tebiz.ru/mcp/",
        "--header",
        "Authorization:${TEBIZ_AUTH}"
      ],
      "env": {
        "TEBIZ_AUTH": "Bearer tbz_live_..."
      }
    }
  }
}

# pip install -U mcp httpx
import asyncio

import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client


async def main():
    headers = {"Authorization": "Bearer tbz_live_..."}
    async with httpx.AsyncClient(headers=headers, timeout=60) as http:
        async with streamable_http_client("https://api.tebiz.ru/mcp/", http_client=http) as (read, write, _):
            async with ClientSession(read, write) as session:
                await session.initialize()
                result = await session.call_tool("list_resources", {})
                print(result.content[0].text)


asyncio.run(main())

Вместо tbz_live_... подставьте свой ключ из кабинета или демо-ключ из быстрого старта.

ChatGPT и веб-версия Claude.ai пока не подключатся: их коннекторы требуют вход через OAuth, а сервер Tebiz Data принимает ключ в заголовке. Используйте клиенты выше или свой агент на MCP SDK.

Инструменты

Если не работает

• [missing_key] или 401: ключ не дошёл до сервера. Проверьте заголовок Authorization: Bearer tbz_live_... и перезапустите клиент после правки конфига.
• [not_found]: такого набора нет или он не выдан ключу. Вызовите list_resources.
• Пустой ответ с полем note: ключ видит только образец данных (демо-ключ или пробный доступ), значений из фильтра в нём нет. Это не значит, что данных нет вообще.
• [bad_request]: фильтр по полю без метки «фильтр» или неподходящий оператор. Поля и операторы показывает describe_resource.

Для ИИ-кодинга: схема REST в формате OpenAPI /openapi.json, документация в Markdown /guide.md, сводка для LLM /llms.txt. Примеры кода и конфиг для Claude Desktop есть в репозитории на GitHub ↗.

Наборы данных

Поля, типы и примеры запросов на странице набора.

Коды ошибок

При ошибке API возвращает JSON {"error":"...","detail":"..."}. Поле error стабильно, по нему удобно ветвить код. В detail написано по-русски, что случилось и что сделать, со ссылкой, если нужен кабинет.

Ошибки в MCP

Инструменты MCP возвращают ошибку текстом с тем же кодом в квадратных скобках и тем же объяснением, что поле detail в REST, например:

[subscription_expired] Подписка закончилась 14.10.2026. Продлите её в личном кабинете: https://api.tebiz.ru/account. После продления этот же ключ снова заработает.

Коды те же, что в таблице выше; у ошибок 401 вместо unauthorized стоит причина из reason. Кроме них бывает [not_found]: набора нет или он не выдан ключу, вызовите list_resources.