ВойтиСоздать аккаунт бесплатно

Справочник по API

Подключение агентов и справочник по SQL API для программного доступа к финансовым данным.

Обзор

Expense Budget Tracker предоставляет один публичный API для программного доступа:

https://api.expense-budget-tracker.com/v1/

С этим API можно работать двумя способами:

  1. Через нативное подключение агента, начиная с GET /v1/
  2. Через прямые HTTP-запросы с уже существующим долгоживущим ApiKey

Для всех запросов применяется тот же механизм Postgres Row Level Security, что и в веб-приложении.

Если ваш клиент поддерживает MCP, используйте размещенный MCP-коннектор по адресу https://mcp.expense-budget-tracker.com/mcp и авторизуйте его через OAuth в браузере. Эта страница описывает отдельное подключение через Agent API и прямой HTTP-контракт с долгоживущим ApiKey.

Точка входа, исходный код и runtime-схема

Начинайте здесь:

https://api.expense-budget-tracker.com/v1/

Ответ этой точки входа подсказывает агенту, как начать аутентификацию и какие вызовы выполнять дальше. Он также содержит ссылки на README и исходный код реализации. API предоставляет:

  • GET /v1/schema
  • GET /v1/openapi.json и GET /v1/swagger.json как адреса совместимости, которые сообщают, что OpenAPI недоступен, и направляют клиента к discovery и исходному коду

Используйте schema, если вам нужен точный список разрешенных таблиц, представлений и столбцов, доступных через /v1/sql/query, /v1/sql/execute и совместимый маршрут /v1/sql.

Нативное подключение агента

Если вы хотите, чтобы Claude Code, Codex, OpenClaw или другой агент подключился самостоятельно, начните с GET /v1/ и следуйте инструкциям, которые вернет сервер.

Поток аутентификации

  1. GET https://api.expense-budget-tracker.com/v1/
  2. Прочитайте действие send_code и значение bootstrapUrl, которые вернет сервер
  3. Отправьте POST с адресом электронной почты пользователя на https://auth.expense-budget-tracker.com/api/agent/send-code
  4. Получите otpSessionToken
  5. Запросите у пользователя 8-значный код из письма
  6. Отправьте POST с code, otpSessionToken и label на https://auth.expense-budget-tracker.com/api/agent/verify-code
  7. Получите долгоживущий ApiKey
  8. Сохраните этот ключ вне чата, в отдельном хранилище
  9. GET https://api.expense-budget-tracker.com/v1/me
  10. GET https://api.expense-budget-tracker.com/v1/workspaces
  11. При необходимости создайте рабочее пространство через POST https://api.expense-budget-tracker.com/v1/workspaces
  12. POST https://api.expense-budget-tracker.com/v1/workspaces/{workspaceId}/select
  13. GET https://api.expense-budget-tracker.com/v1/schema
  14. Читайте данные через POST https://api.expense-budget-tracker.com/v1/sql/query, а одобренные изменения отправляйте через POST https://api.expense-budget-tracker.com/v1/sql/execute

Заголовок аутентификации

  • Authorization: ApiKey <key>

Работа с рабочими пространствами

  • POST /v1/workspaces/{workspaceId}/select сохраняет рабочее пространство по умолчанию для этого API-ключа
  • после этого в запросах к /v1/sql/query, /v1/sql/execute и совместимому /v1/sql можно не передавать X-Workspace-Id
  • X-Workspace-Id: <workspaceId> по-прежнему поддерживается, если нужно переопределить сохраненное рабочее пространство для одного запроса
  • если у пользователя ровно одно рабочее пространство и для ключа еще не сохранен выбор, API автоматически сохранит и будет использовать именно его

Пошаговое руководство для человека см. в разделе Настройка ИИ-агента.

Прямое использование HTTP с существующим ключом

Скрипты, cron-задачи, дашборды и собственные приложения могут напрямую обращаться к тому же API, если у них уже есть долгоживущий ApiKey.

Аутентификация

Передавайте ключ в заголовке авторизации ApiKey:

curl -X POST https://api.expense-budget-tracker.com/v1/sql/query \
  -H "Authorization: ApiKey ebta_your_key_here" \
  -H "X-Workspace-Id: workspace-id" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT * FROM ledger_entries ORDER BY ts DESC LIMIT 10"}'

X-Workspace-Id нужен только в двух случаях: если для ключа еще не сохранено рабочее пространство по умолчанию или если вы хотите переопределить уже сохраненное рабочее пространство для этого запроса.

  • Authorization: ApiKey ebta_your_key_here
  • X-Workspace-Id: <workspaceId> при необходимости

Краткая сводка по эндпоинтам

  • GET /v1/ — публичный документ для обнаружения API
  • GET /v1/openapi.json и GET /v1/swagger.json — адреса совместимости для discovery исходного кода, а не спецификации API
  • GET /v1/me — сведения о текущей аутентифицированной учетной записи
  • GET /v1/workspaces — список рабочих пространств, доступных владельцу ключа
  • POST /v1/workspaces — создание рабочего пространства
  • POST /v1/workspaces/{workspaceId}/select — сохранение рабочего пространства по умолчанию для этого ключа
  • GET /v1/schema — просмотр доступных для SQL таблиц, представлений и столбцов
  • POST /v1/sql/query — выполнение одного запроса SELECT или WITH ... SELECT только для чтения
  • POST /v1/sql/execute — выполнение одного одобренного запроса INSERT, UPDATE или DELETE
  • POST /v1/sql — совместимый маршрут для атомарных скриптов из нескольких выражений

Политика SQL

Основные маршруты намеренно разделяют чтение и запись:

  • POST /v1/sql/query принимает ровно один запрос только для чтения: SELECT или WITH ... SELECT
  • POST /v1/sql/execute принимает ровно одно изменение INSERT, UPDATE или DELETE, включая поддерживаемые формы с WITH
  • совместимый POST /v1/sql принимает ограниченные скрипты из нескольких выражений и применяет их атомарно; используйте его только тогда, когда нужна такая атомарность

Блокируются или отклоняются:

  • несколько SQL-запросов на основных маршрутах /v1/sql/query и /v1/sql/execute
  • DDL-команды, такие как CREATE, DROP и ALTER
  • транзакционные обертки, такие как BEGIN, COMMIT и ROLLBACK
  • set_config()
  • SQL-комментарии
  • идентификаторы в кавычках
  • строки с синтаксисом dollar-quoting

Сервер также ограничивает перечень объектов базы данных, к которым разрешен доступ. Перед генерацией SQL используйте /v1/schema, чтобы посмотреть доступные таблицы, представления и столбцы.

Сейчас доступны следующие объекты базы данных:

  • ledger_entries
  • budget_lines
  • workspace_settings
  • account_metadata
  • accounts (только чтение)
  • fx_rates_raw (только чтение)
  • fx_rates_daily (только чтение)

Ограничения

  • не более 100 возвращаемых строк на запрос
  • не более 100 затронутых строк на выражение изменения и на запрос
  • общий лимит времени SQL-запроса: 25 секунд
  • 10 запросов в секунду и 10 000 запросов в день на один ключ

Безопасность

  • API-ключи хранятся в виде SHA-256-хэшей, открытый текст никогда не сохраняется
  • RLS обеспечивает изоляцию рабочих пространств на уровне базы данных
  • ключи можно отозвать в любой момент прямо в продукте
  • при удалении участника рабочего пространства все его ключи автоматически отзываются