{"openapi":"3.1.0","info":{"title":"Kovara Provider API","version":"1","description":"Implemented by a GPU provider, called by Kovara. JSON over HTTPS on a public host name. Kovara sends `Authorization: Bearer <token>` with the token the provider issued to Kovara, and `Kovara-Provider-API-Version: 1`. Errors use {\"error\": {\"code\", \"message\"}}. Guide: https://www.kovaragrid.com/docs/provider-api"},"servers":[{"url":"https://api.example-cloud.com/kovara","description":"The provider's base URL, as entered in the Kovara Provider portal"}],"security":[{"bearer":[]}],"paths":{"/v1/capabilities":{"get":{"summary":"What this API supports","responses":{"200":{"description":"Capabilities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Capabilities"}}}},"401":{"description":"Bad token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/inventory":{"get":{"summary":"Every SKU Kovara may show, with price and what can be launched now","responses":{"200":{"description":"Inventory","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Inventory"}}}},"401":{"description":"Bad token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instances":{"post":{"summary":"Launch one instance of a SKU","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":100},"description":"Same as client_token: a retry with the same key returns the same instance."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaunchRequest"}}}},"responses":{"200":{"description":"Same client_token: the existing instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Instance"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Instance"}}}},"409":{"description":"No capacity for this SKU now (code capacity_unavailable)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/instances/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"}}],"get":{"summary":"One instance","responses":{"200":{"description":"Instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Instance"}}}},"404":{"description":"Unknown instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Terminate (idempotent)","responses":{"200":{"description":"Already terminated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Instance"}}}},"202":{"description":"Terminating","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Instance"}}}},"404":{"description":"Unknown instance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/usage":{"get":{"summary":"Billed usage of instances Kovara launched","parameters":[{"name":"since","in":"query","required":true,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Usage","content":{"application/json":{"schema":{"type":"object","required":["records"],"properties":{"records":{"type":"array","maxItems":5000,"items":{"$ref":"#/components/schemas/UsageRecord"}}}}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","maxLength":60},"message":{"type":"string","maxLength":300}}}}},"Capabilities":{"type":"object","required":["api_version","provider_name","features"],"properties":{"api_version":{"const":"1"},"provider_name":{"type":"string","minLength":1,"maxLength":120},"features":{"type":"object","properties":{"instances":{"type":"boolean"},"usage":{"type":"boolean"},"webhooks":{"type":"boolean"}}},"test_mode":{"type":"boolean","description":"True when this token launches in a test mode that is not billed."}}},"Inventory":{"type":"object","required":["generated_at","items"],"properties":{"generated_at":{"type":"string","format":"date-time"},"items":{"type":"array","maxItems":2000,"items":{"$ref":"#/components/schemas/Sku"}}}},"Sku":{"type":"object","required":["sku_id","gpu_model","gpu_count","region","price"],"properties":{"sku_id":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:/-]{0,99}$"},"gpu_model":{"type":"string","maxLength":120,"examples":["NVIDIA H100 SXM 80GB"]},"gpu_memory_gb":{"type":"number"},"gpu_count":{"type":"integer","minimum":1,"maximum":64},"vcpus":{"type":"integer"},"ram_gb":{"type":"number"},"storage_gb":{"type":"number"},"region":{"type":"object","required":["code"],"properties":{"code":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"},"city":{"type":"string"},"country_iso2":{"type":"string","pattern":"^[A-Z]{2}$"}}},"price":{"type":"object","required":["amount","currency","unit","contract"],"properties":{"amount":{"type":"number","minimum":0,"maximum":100000},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"unit":{"enum":["instance_hour","gpu_hour"]},"contract":{"enum":["on_demand","spot"]}}},"available_count":{"type":["integer","null"],"minimum":0,"description":"Instances of this SKU that can be launched now. null when not known: Kovara then shows it as unknown, never as available."}}},"LaunchRequest":{"type":"object","required":["sku_id","region_code","ssh_public_key","client_token"],"properties":{"sku_id":{"type":"string"},"region_code":{"type":"string"},"ssh_public_key":{"type":"string","description":"OpenSSH public key to install for login"},"image":{"type":"string"},"name":{"type":"string","maxLength":63},"labels":{"type":"object","additionalProperties":{"type":"string"}},"client_token":{"type":"string","maxLength":100,"description":"Idempotency token"}}},"Instance":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string"},"sku_id":{"type":"string"},"region_code":{"type":"string"},"status":{"enum":["pending","provisioning","running","stopping","terminated","failed"]},"created_at":{"type":"string","format":"date-time"},"running_at":{"type":["string","null"],"format":"date-time"},"terminated_at":{"type":["string","null"],"format":"date-time"},"connection":{"type":["object","null"],"description":"Required once running","properties":{"host":{"type":"string"},"port":{"type":"integer"},"username":{"type":"string"}}},"failure_reason":{"type":["string","null"],"maxLength":300}}},"UsageRecord":{"type":"object","required":["instance_id","started_at","billed_seconds","amount","currency"],"properties":{"instance_id":{"type":"string"},"sku_id":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"ended_at":{"type":["string","null"],"format":"date-time"},"billed_seconds":{"type":"integer","minimum":0},"amount":{"type":"number","minimum":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}}}}}}