A calmer control plane.

A clear resource model

An integration should work with explicit server identifiers, regions, images, plans and operations. Creation and reinstall requests should return an operation that can be checked to completion. A successful HTTP request is not the same thing as a machine being ready.

Credentials with a limited job

API tokens should be independently revocable and restricted to the minimum resources and actions needed. Store them in a secret manager or protected environment. Never send a token to the browser just to avoid writing a small backend.

Retries must be safe

Network timeouts can occur after an operation has been accepted. Use an idempotency key for creation and payment-sensitive requests, inspect the operation state and respect rate limits. A retry should resolve uncertainty, not create an extra billable server.

Check compatibility before integration

Check the released API version, authentication model, error formats, pagination, rate limits and token scopes before building an integration. Use only published KoalaVPS SDK packages from verified release links.

API roadmap

The API roadmap covers catalogue discovery, authentication, account state, crypto billing, server lifecycle, public SSH keys and webhooks. The routes below describe the interface contract; production access is not yet available.

Authentication and account routes

The API contract separates login sessions and API keys. Check response schemas, errors, token lifetimes and supported recovery actions against the version released for your integration.

• POST /v1/auth/register
• POST /v1/auth/login
• POST /v1/auth/login/totp
• POST /v1/auth/token/refresh
• POST /v1/auth/recover
• GET /v1/auth/sessions
• DELETE /v1/auth/sessions/{token_id}
• POST /v1/auth/totp/setup
• POST /v1/auth/totp/enable
• POST /v1/auth/totp/disable
• POST /v1/auth/password
• POST /v1/auth/api-keys
• GET /v1/auth/api-keys
• DELETE /v1/auth/api-keys/{key_id}
• GET /v1/account
• PATCH /v1/account
• GET /v1/account/usage
• GET /v1/account/audit-log

Catalogue and billing routes

Catalogue reads should not require a payment. Payment creation needs a restricted billing scope, clear invoice state and idempotent handling. Confirmation must complete before service activation.

• GET /v1/catalog
• GET /v1/catalog/vps
• GET /v1/catalog/dedicated
• GET /v1/catalog/regions
• GET /v1/catalog/images
• GET /v1/catalog/{code}
• GET /v1/billing/coins

Server and access routes

The lifecycle needs explicit confirmation for cancellation and reinstall operations. Private SSH keys belong on the client; the service only needs their public counterparts.

• POST /v1/servers
• GET /v1/servers
• GET /v1/servers/{order_number}
• PATCH /v1/servers/{order_number}
• DELETE /v1/servers/{order_number}
• POST /v1/ssh-keys
• GET /v1/ssh-keys
• GET /v1/ssh-keys/{id}
• DELETE /v1/ssh-keys/{id}

Events and public information

Webhooks need verifiable signatures, bounded retries and replay protection. Public trust endpoints should return real dated evidence rather than synthetic assurances.

• POST /v1/webhooks
• GET /v1/webhooks
• DELETE /v1/webhooks/{id}
• POST /v1/webhooks/{id}/test
• GET /v1/transparency/canary
• GET /v1/transparency/peering
• GET /v1/transparency/status
• GET /v1/agents/directory
• POST /v1/agents/directory

Authorisation and traffic limits

A candidate scope model is read, servers, billing and full, with a maximum of ten active keys per account. The API contract proposes request budgets of 120 per minute and 3,000 per hour for an API key, and 30 per minute for public traffic. Check HTTP 429, Retry-After and the enforcement window in the released API documentation; these roadmap budgets are not a production capacity commitment.

• POST /v1/oauth/register
• POST /v1/oauth/token
• POST /v1/oauth/revoke
• GET /v1/oauth/introspect

SDK and protocol releases

The integration roadmap includes REST, a hosted MCP endpoint, a versioned stdio package, SDKs and a CLI. Check release availability, supported runtimes, checksums and API compatibility before installing a client. Production downloads are not yet available.

API resources, grouped by responsibility

The intended API separates account access, catalogue reading, billing, server lifecycle, SSH keys and callbacks. Read-only calls should not create an order, and a billing credential should not automatically authorise account security changes. This describes the integration contract. A production provisioning endpoint and released SDK are not available through this site.

• Account: sessions, usage and security audit events
• Catalogue: plans, regions and available images
• Servers: create, inspect, change and cancel
• SSH keys: register public material and revoke obsolete keys
• Webhooks: register, inspect, test and remove signed callbacks

A server request should stay small

Choose a standard plan identifier, region, OS image and hostname. The intended hostname limit is 64 characters. A live service can generate an administrator secret privately or accept an enrolled SSH public key. Arbitrary disk, GPU, NIC and IP additions are not implied by a standard plan request. Reject unsupported fields rather than silently charging for a guessed upgrade.

{
  "plan": "KV-D3",
  "region": "hel",
  "image": "ubuntu-24",
  "hostname": "private-node-01"
}
// Example request schema; validate against a released API before integration.

Scopes and key limits are part of the contract

The proposed privilege groups are read, servers, billing and full account administration. A key should be displayed once when created, stored privately and revoked independently of the user’s password. The intended account limit is ten active keys. Before publishing an implementation, verify that each operation rejects a key without the required scope.

Publish rate limits and retry behavior together

The proposed limits are 120 requests per minute and 3,000 per hour for an API key, and 30 requests per minute for unauthenticated public catalogue requests. These are planned policy values, not measured API capacity. A live implementation needs a consistent 429 response, Retry-After guidance and bounded client backoff. Creation and payment requests also need stable idempotency keys.

Webhooks are messages that can arrive more than once

A callback receiver should verify the signature over the original body, reject timestamps outside its allowed window and remember processed event identifiers. Persist the event before acknowledging it, then apply the change idempotently. Keep delivery attempts and a manual replay path visible. A callback is an observation about an operation, not permission to execute unrelated instructions contained in a payload.

Audit without turning logs into a secret store

Record the actor identifier, operation type, affected resource, result and time where needed for account security. Avoid recording passwords, bearer tokens, private keys or full payment and application request bodies by default. Keep retention, access and customer-visible history explicit. A security audit trail and a claim to inspect customer application contents are different things.

Release artifacts only when they exist

A public API launch should include a versioned OpenAPI document, authentication instructions, error examples and a deprecation process. A future CLI, Python package, TypeScript client or MCP server needs an actual release, checksums and maintained documentation. A KoalaVPS provisioning package or production management endpoint is not released through this site.

A little more clarity.