API: Overview

API v2 is the public HTTP interface of the Control Plane for managing your account, tenants, and databases.

Base URL

https://provisioner.spg99.ru/v2

If your team has been given a separate environment, use the CP_URL from Console, CLI, or the invitation you received. In the documentation below, the default assumption is the main managed environment spg99.ru.

What the API does and what Gateway does

It is important to separate two kinds of work:

• API v2 — creating and deleting resources, reading state, tokens, profile, and usage;
• Gateway — regular PostgreSQL application connections by DSN on :5432.

In other words:

• the Control Plane API is responsible for account / tenant / database lifecycle;
• Gateway is responsible for client PostgreSQL connections.

Typical API scenarios

API v2 is usually used to do the following:

• create a tenant;
• create a database inside a tenant;
• get the list of tenants and databases;
• read the state of a specific database;
• retrieve tenant credentials again;
• view the account profile and usage;
• delete a database or a tenant;
• subscribe to /v2/events if you are building your own UI or integrator.

The main rule of the managed scenario

In the public managed contract, manual start, stop, and scale for a database are intentionally disabled. The normal user path is:

create tenant -> save credentials -> create db -> connect the application through Gateway

After that, the platform works on its own:

• the database starts automatically on the first connection through Gateway;
• the database stops automatically after a period of inactivity;
• when the writer profile changes, the platform performs a controlled handoff between compute generations.

What is now especially important in the database response

In addition to the usual state, size, current_scale, and target_scale fields, the API now returns new profile and autoscaler runtime fields:

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

These fields are needed to distinguish between:

• a normal cold start;
• an idle stop;
• a controlled handoff between L1 and L2;
• a failed autoscale transition.

Authentication

Use the following for API calls:

Authorization: Bearer <api-key>

Do not use pg_user / pg_password for the API. These secrets belong only to the PostgreSQL DSN.

When the API is especially useful

The API is convenient if you need to:

• automate database provisioning in CI/CD;
• embed SPG99 into a back office or internal portal;
• run health checks and resource inventory;
• manage access and tokens without doing everything manually in Console;
• track autoscale handoff programmatically through scale_state and the profile fields.