Sviluppatori
Riferimento API
Autenticati con una sessione o una chiave API e utilizza gli endpoint implementati per account, preventivi, istanze e fatturazione.
8 min di lettura · AggiornatoAutenticazione
Il percorso di base è /api/v1. Le richieste del browser utilizzano il cookie di sessione HttpOnly creato al momento dell'accesso. Gli script possono utilizzare Authorization: Bearer seguito da una chiave API attiva. Le chiavi hanno autorizzazioni complete sull'account e vengono mostrate una sola volta al momento della creazione.
L'interfaccia locale utilizza chiavi gh_demo_. La revoca di una chiave impedisce immediatamente nuove richieste autenticate che la utilizzano. Non inserire le chiavi negli URL o nei bundle lato browser.
GET /api/v1/balance
Authorization: Bearer <your-api-key>
200 OK
{ "currency": "USD", "balanceCents": 50000, "derivedFrom": "ledger_entries" }Regole di richiesta e di nuovo tentativo
I corpi delle richieste POST e PATCH sono oggetti JSON, con Content-Type: application/json. Invia {} per azioni senza parametri. I corpi sono limitati a 32 KiB di testo. Le risposte usano Cache-Control: no-store.
Deployment, rinnovo manuale e ritiro richiedono un Idempotency-Key di 8–128 caratteri. Usa una nuova chiave per una nuova operazione prevista e riutilizza la stessa chiave per il suo nuovo tentativo. Non riutilizzarla mai con un corpo diverso. Una risposta di replay include replayed: true.
I preventivi delle istanze calcolano il prezzo di catalogo corrente senza riservare capacità. Invia expectedPriceCents al momento della distribuzione; una mancata corrispondenza restituisce 409 così il prezzo può essere riesaminato.
POST /api/v1/instances
Content-Type: application/json
Idempotency-Key: <unique-operation-id>
Authorization: Bearer <your-api-key>
{
"sku": "nvidia-rtx-4090",
"gpuCount": 1,
"region": "dal",
"image": "pytorch",
"period": "week",
"options": [],
"sshKeyId": "<saved-key-id>",
"autoRenew": false,
"expectedPriceCents": 11000
}Endpoint implementati
Tutte le risorse dell'account sono limitate al loro proprietario. L'endpoint di disponibilità è pubblico ed espone lo snapshot del catalogo, non un rilevamento hardware in tempo reale.
| Metodo | Percorso dopo /api/v1 | Scopo |
|---|---|---|
| POST | /auth/register · /auth/login | Nome utente + password; crea una sessione |
| POST | /auth/recover | Nome utente + codice inutilizzato + nuova password |
| POST | /auth/logout | Revoca la sessione corrente del browser |
| GET | /me · /balance · /ledger | Account, saldo e ultime 100 voci |
| GET / DELETE | /sessions · /sessions/:id | Elenca le sessioni attive o revocane una |
| GET | /availability | Catalogo pubblico e istantanea delle scorte regionali |
| GET / POST | /deposit-quotes | Elenca le quotazioni attive o creane una con asset + desiredUsdCents |
| POST | /demo/confirm-deposit | ID preventivo; solo sviluppo locale |
| GET | /deposits · /withdrawals | Ultimi 100 record per questo account |
| POST | /withdrawals | Asset + destinazione + amountUsdCents; idempotente |
| POST | /instance-quotes | GPU, quantità, regione, immagine, periodo e opzioni |
| GET / POST | /instances | Elenca le allocazioni o implementa; l'implementazione è idempotente |
| POST | /instances/:id/start · stop · release · renew | Azione del ciclo di vita; il rinnovo è idempotente |
| PATCH | /instances/:id/auto-renew | Imposta enabled su true o false |
| GET / POST | /ssh-keys · /api-keys | Elenca o crea le chiavi dell'account |
| DELETE | /ssh-keys/:id · /api-keys/:id | Revoca una chiave |
Gestisci gli errori in modo esplicito
Gli errori hanno {error, message}: un codice stabile e una spiegazione leggibile. 400 indica input non valido, 401 autenticazione mancante o non valida, 403 un'origine rifiutata, 404 una risorsa sconosciuta o non posseduta, 409 un conflitto di saldo/state/duplicate e 415 il tipo di contenuto errato.
Per un preventivo di deposito scaduto, creare un altro preventivo. Per uno stato dell'istanza modificato, ricaricare l'istanza prima di decidere un'altra azione. Dopo un'interruzione di rete, riutilizzare la chiave dell'operazione invece di creare un secondo addebito.