УвійтиСтворити акаунт безкоштовно

Довідник API

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

Огляд

Expense Budget Tracker надає один публічний API для машинного доступу за адресою:

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

Цю саму точку входу можна використовувати двома способами:

  1. Підключення AI-агента через 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.

Підключення AI-агента

Якщо ви хочете, щоб Claude Code, Codex, OpenClaw або інший агент підключився самостійно, почніть із початкової точки входу GET /v1/ і далі виконуйте дії, які сервер поверне у відповіді.

Як проходить автентифікація

  1. GET https://api.expense-budget-tracker.com/v1/
  2. Прочитайте send_code і bootstrapUrl, які поверне сервер
  3. Надішліть POST з email користувача на 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 автоматично збереже й використає саме його

Покрокову інструкцію для людини дивіться в Налаштування AI-агента.

Прямі HTTP-запити з наявним ключем

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

Автентифікація

Передавайте ключ у заголовку Authorization зі схемою 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 приймає обмежені сценарії з кількох операторів і застосовує їх атомарно; використовуйте його лише тоді, коли потрібна така атомарність

Заблоковані або відхилені конструкції:

  • кілька операторів на основних маршрутах /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 забезпечує ізоляцію робочих просторів на рівні бази даних
  • ключі можна будь-коли відкликати з інтерфейсу продукту
  • якщо видалити учасника робочого простору, усі його ключі буде автоматично відкликано