The Kovara Provider API is a small interface a GPU provider implements so Kovara can read its inventory, show what is available now, and launch on its platform. The provider implements it; Kovara calls it.
A provider connects it once, in the Provider portal under Connect → Connect your platform (/supplier/launch-api). Once Kovara has approved the connection, the provider's availability appears on Kovara within five minutes.
Machine-readable description: /api/public/v1/provider-api/openapi.json (OpenAPI 3.1).
Basics
- JSON over HTTPS, on a public host name. IP addresses are not called and redirects are not followed.
- Authentication: Kovara sends
Authorization: Bearer <token>. The token is one the provider issues to Kovara and pastes in the portal, where it is stored encrypted in Supabase Vault. A wrong token must get 401 (or 403). - Kovara also sends
Kovara-Provider-API-Version: 1. - Errors use one shape:
{"error": {"code": "capacity_unavailable", "message": "No capacity for this SKU right now."}}. - Time limits: 15 seconds per request; answers up to 8 MB.
Endpoints
| Method | Path | What it returns |
|---|---|---|
GET | /v1/capabilities | api_version "1", provider_name, features {instances, usage, webhooks}, optional test_mode |
GET | /v1/inventory | generated_at and items: every SKU Kovara may show (up to 2,000) |
POST | /v1/instances | Launches one instance; 201 with the instance, 409 capacity_unavailable when there is none |
GET | /v1/instances/{id} | One instance; 404 for an unknown id |
DELETE | /v1/instances/{id} | Terminates (idempotent); 202 |
GET | /v1/usage?since=… | Billed usage of the instances Kovara launched |
A SKU
{
"sku_id": "h100-sxm-8x.fra",
"gpu_model": "NVIDIA H100 SXM 80GB",
"gpu_memory_gb": 80,
"gpu_count": 8,
"vcpus": 208,
"ram_gb": 1800,
"storage_gb": 20000,
"region": { "code": "fra-1", "city": "Frankfurt", "country_iso2": "DE" },
"price": { "amount": 19.92, "currency": "USD", "unit": "instance_hour", "contract": "on_demand" },
"available_count": 3
}available_countis how many instances of this SKU can be launched now. Use0for none, andnullwhen you cannot say. Kovara showsnullas unknown, never as available.- Prices stay in your currency and unit. Kovara works out a USD price per GPU-hour only for USD prices and never converts currencies here.
Launching
POST /v1/instances with sku_id, region_code, ssh_public_key, client_token and optional name, image and labels. A retry with the same client_token (also sent as Idempotency-Key) must return the same instance, not a second one.
An instance moves through pending → provisioning → running → stopping → terminated; failed can happen at any point. Once running, it must carry connection {host, port, username}.
Connecting, step by step
- Connect: enter the base URL (Kovara appends
/v1/...) and the token. Protocol check: Kovara checks five things and launches nothing:
capabilitiesis readable;- a wrong token is refused;
inventoryparses and lists at least one SKU;- an unknown instance gets
404in the error format; usageparses, if you offer it.
Every failing field is named, for example
items[3].price.unit must be "instance_hour" or "gpu_hour".- Choose what to sell: map each SKU you want on Kovara to the Kovara GPU and the specific Kovara region it really is. Unmapped SKUs are never shown, and a SKU cannot be mapped to a placeholder region such as "Unspecified".
- Test launch (optional): Kovara starts one instance of a SKU you choose, waits until it is running with connection details, terminates it, and confirms it is terminated.
- Kovara sends a public SSH key whose private half it never kept, so nobody can log in.
- Termination is always requested, even when a step fails.
- At most 5 test launches per day, one at a time. Use a test mode or a free tier if your platform has one.
- Kovara review: a Kovara operator checks the mappings and approves the connection. From then on, while selling is on:
- Kovara reads your inventory every 5 minutes;
- it publishes each mapped SKU as live availability (grade B, fresh for 15 minutes), the same way as Kovara's own live connectors.
You can switch selling off at any time; Kovara then shows nothing of yours at once. You can also cap how many instances Kovara may run. Changing the base URL or token resets certification and approval. Changing what you sell sends a live connection back for review.
What Kovara never does
- It never writes your offerings, prices or regions from this API: inventory feeds live availability only.
- It never shows a SKU you did not map and switch on.
- It never calls anything but the base URL you entered.
- It never shows your token after you save it, and deleting the connection deletes the token.
Roles
| Who | Can |
|---|---|
| Admins of the provider in the portal | Connect, check, choose what to sell, switch selling, run test launches, disconnect |
| Other members | See the connection's state |
| The Kovara operator | Approve or pause the connection (/admin/provider-connections) |