# Hubvix

> Hubvix hosts customer-owned bots, APIs, and web applications. The agent API lets an authorized CI job or AI agent deploy and manage only the account owner's hosting resources.

## Developer documentation

- [Agent API guide](https://hubvix.ru/developers): public overview, setup, access scopes, deployment flow, retries, and security.
- [Full agent API guide](https://hubvix.ru/llms-full.txt): concise machine-readable workflow and endpoint reference.
- [Filtered Agent API OpenAPI](https://api.hubvix.ru/api/v1/openapi.json): authoritative machine-readable list of routes available to agent keys. Each operation includes its required scope.

## API basics

- API base URL: `https://api.hubvix.ru`.
- Authentication: `Authorization: Bearer hvx_…`; send keys in headers only.
- Account check: `GET /api/v1/me` returns `id` and `balance_kopeks`.
- Key creation, listing, and revocation are human dashboard actions at `https://hubvix.ru/dashboard/profile/api`; raw keys are shown once. Key creation requires a verified email, completed registration, and accepted agreement.
- Scopes are independent: `read`, `deploy`, and `manage`. `deploy` includes project/service deploy and start/stop/restart; `manage` includes configuration, hosting resources, tariff changes, and available deletes. The dashboard's Deploy profile grants `read` + `deploy`; Full Access grants all three. Check each operation's `x-required-scope` in OpenAPI.
- `read` includes source files, logs, and runtime metadata, so read-only keys are sensitive. A password change invalidates existing agent keys.
- Expiration is 60 to 31,536,000 seconds, or `null` for a manually revocable key. The account can have up to 100 active keys.
- Project operations use the same ownership, agreement, billing, tariff, region, and resource rules as the dashboard.
- Expired or revoked keys cannot authorize new requests. Already accepted background jobs may finish, and running applications continue to incur their normal charges.
- An owner must accept the current user agreement in the dashboard. The agent API does not expose admin, payment, account password, or key-minting operations.

## First deployment

1. Read `GET /api/v1/billing/balance` and `GET /api/v1/projects/tariffs`.
2. Check `GET /api/v1/projects/create-check?tariff_id={id}&region_group=ru` or `eu`; proceed only when `can_create`, `can_allocate`, and `enough_balance` are all true.
3. Create `POST /api/v1/projects/` with name, tariff_id, region_group and explicit services, for example `{"name":"web","language":"html","service_type":"web"}`. No draft or files required. Reuse X-HUBVIX-Idempotency-Key only for the same operation/body.
4. Poll `GET /api/v1/projects/{id}` until `creating` becomes `stopped` with `source_pending: true`: reserved workspace ready, no application running. Reserved resources remain billable.
5. Upload multipart files with `POST /api/v1/projects/{id}/files/upload`, field `files`. Inspect runtime and configure dependencies/commands as needed (configuration updates require manage scope).
6. Launch `POST /api/v1/projects/{id}/deploy` with `{}` and poll deployments until running. source_pending clears after successful first deploy.
7. The older draft-upload + draft_id creation flow remains supported for existing integrations.

The full guide documents multi-service projects, add-ons, env files, routes, logs, errors, and Python/cURL examples. Do not send account passwords to agents; operations requiring password confirmation stay in the dashboard.

A key covers every hosting project owned by the account, including already-owned preview deployments. Project-specific restriction is not available. Internal Studio order-linked creation, contracts, payments, team and chat workflows are human-only, even when the key owner is a staff member.