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

Справочник по 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, что и в веб-приложении.

Точка входа и опубликованные спецификации

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

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

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

  • GET /v1/openapi.json
  • GET /v1/swagger.json
  • GET /v1/schema

Используйте schema, если вам нужен точный список разрешенных таблиц, представлений и столбцов, доступных через /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. Выполняйте SQL через POST https://api.expense-budget-tracker.com/v1/sql

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

  • Authorization: ApiKey <key>

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

  • POST /v1/workspaces/{workspaceId}/select сохраняет рабочее пространство по умолчанию для этого API-ключа
  • после этого в запросах к /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 \
  -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 — опубликованные спецификации API
  • GET /v1/me — сведения о текущей аутентифицированной учетной записи
  • GET /v1/workspaces — список рабочих пространств, доступных владельцу ключа
  • POST /v1/workspaces — создание рабочего пространства
  • POST /v1/workspaces/{workspaceId}/select — сохранение рабочего пространства по умолчанию для этого ключа
  • GET /v1/schema — просмотр доступных для SQL таблиц, представлений и столбцов
  • POST /v1/sql — выполнение одного SQL-запроса в рамках установленных ограничений

Политика SQL

POST /v1/sql принимает ровно один SQL-запрос на каждый HTTP-запрос.

Разрешенные типы запросов:

  • SELECT
  • WITH
  • INSERT
  • UPDATE
  • DELETE

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

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

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

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

  • ledger_entries
  • accounts
  • budget_lines
  • budget_comments
  • workspace_settings
  • account_metadata
  • exchange_rates

Ограничения

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

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

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