Войти

API: обзор

Stable

Назначение API v2, базовые правила аутентификации и новые runtime‑поля БД для autoscaler и profile handoff.

Обновлено: 21 марта 2026 г.

API v2 — это публичный HTTP‑интерфейс Control Plane для управления аккаунтом, tenants и базами данных.

Base URL

https://provisioner.spg99.ru/v2

Если вашей команде выдан отдельный контур, используйте CP_URL из Console, CLI или приглашения. По умолчанию в документации ниже подразумевается основной managed‑контур spg99.ru.

Что делает API, а что делает Gateway

Важно разделять два типа работы:

  • API v2 — создание и удаление ресурсов, чтение состояния, токены, профиль, usage;
  • Gateway — обычные PostgreSQL‑подключения приложений по DSN на :5432.

Иначе говоря:

  • Control Plane API отвечает за account / tenant / database lifecycle;
  • Gateway отвечает за клиентские PostgreSQL‑соединения.

Типовые сценарии через API

Через API v2 обычно делают следующее:

  • создать tenant;
  • создать базу внутри tenant;
  • получить список tenants и БД;
  • прочитать состояние конкретной БД;
  • повторно получить tenant credentials;
  • посмотреть профиль аккаунта и usage;
  • удалить БД или tenant;
  • подписаться на /v2/events, если вы строите свой UI или интегратор.

Главное правило managed‑сценария

В публичном managed‑контракте ручные start, stop и scale для базы намеренно отключены. Нормальный пользовательский путь такой:

создать tenant -> сохранить credentials -> создать db -> подключить приложение через Gateway

Дальше платформа работает сама:

  • база запускается автоматически при первом подключении через Gateway;
  • база останавливается автоматически после простоя;
  • при смене профиля writer платформа делает controlled handoff между поколениями compute.

Что теперь особенно важно в ответе БД

Помимо обычных полей state, size, current_scale и target_scale, API возвращает новые runtime‑поля профиля и autoscaler:

  • current_profile
  • target_profile
  • candidate_profile
  • candidate_worker_id
  • candidate_writer_term
  • scale_state
  • freeze_new_checkouts
  • autoscale_cooldown_until
  • scale_failure_reason

Эти поля нужны, чтобы различать:

  • обычный cold start;
  • idle stop;
  • controlled handoff между L1 и L2;
  • failed autoscale.

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

Для вызова API используйте:

Authorization: Bearer <api-key>

Не используйте pg_user / pg_password для API. Эти секреты относятся только к PostgreSQL‑DSN.

Когда API особенно полезен

API удобен, если вам нужно:

  • автоматизировать выдачу баз в CI/CD;
  • встроить SPG99 в backoffice или внутренний портал;
  • делать health‑checks и inventory ресурсов;
  • управлять доступами и токенами без ручной работы в Console;
  • программно отслеживать autoscale handoff по scale_state и profile‑полям.
Почему SPG99АрхитектураПлан развитияДокументацияБлог