Riferimento API
Usa le operazioni API e interpreta i loro risultati
Leggi gli endpoint disponibili, le regole di idempotenza, le risposte delle azioni in coda e i limiti correnti sul tracciamento delle operazioni.
In questa pagina
Prima di iniziare
- Una sessione valida e, per le modifiche protette, il suo token CSRF.
- Identificatori presi dal catalogo corrente o da risposte autenticate API.
- Una Idempotency-Key univoca per ogni ordine, prelievo o azione hardware.
Leggi l'account prima di modificarlo
Utilizza gli endpoint di lettura per confermare account, saldo e risorsa di destinazione. GET /api/v1/me restituisce username, balanceUsd e il csrfToken della sessione. Gli identificatori delle risorse sono specifici dell'account; utilizza l'identificatore del server o della rete restituito per l'account corrente invece di copiare un valore da un altro ambiente.
L'attuale API è un'interfaccia account compatta, non una piattaforma completa di job asincroni. Salva i riferimenti delle scritture riuscite nei tuoi registri. Non esiste un endpoint per elencare ogni ordine, ispezionare un'azione in coda specifica o recuperare lo stato di revisione più recente di un prelievo.
| Endpoint di lettura | Dati restituiti |
|---|---|
| GET /api/v1/ledger | Le ultime voci del registro 100, prima le più recenti; nessun contratto di paginazione. |
| GET /api/v1/servers | Server non terminati, stato, regione, paidThrough, graceUntil e autoRenew. |
| GET /api/v1/network | Indirizzi assegnati, lunghezze dei prefissi, valori PTR e identificatori dei server correlati. |
| GET /api/health | Conteggi di servizi di base e catalogo; nessuna garanzia sull'account o sulla salute del server fisico. |
Usa l'endpoint di modifica corrispondente
Le azioni server supportate sono reboot, power_off, reinstall, mount_iso, kvm e rotate_root_password. Un URL ISO personalizzato deve utilizzare HTTPS pubblico senza credenziali incorporate. Il termine dell'ordine è settimanale o mensile, rappresentando sette o trenta giorni. Prezzo, sconti, fondi e capacità sono verificati dal servizio; non inviare un prezzo calcolato dal client come autorità.
| Endpoint | Campi della richiesta e risultato |
|---|---|
| POST /api/v1/orders | configId, regionId, osId, term, quantity; opzionale sshPublicKey. Restituisce id ordine e ACCEPTED. |
| POST /api/v1/deposit-addresses | asset. Restituisce indirizzo, asset, rete, confirmationsRequired e modalità, oppure errore di regolamento non disponibile. |
| POST /api/v1/withdrawals | asset, destinazione, usd. Restituisce id e PENDING_REVIEW; il saldo viene trattenuto. |
| POST /api/v1/servers/{id}/actions | azione; isoUrl per mount_iso. Restituisce l'ID dell'azione e QUEUED. |
| PUT /api/v1/servers/{id}/ddos | modalità: BASELINE o ADVANCED. Restituisce QUEUED o UNCHANGED e quoteRequired. |
| PUT /api/v1/network/{id}/rdns | ptr, o un valore vuoto per cancellarlo. Restituisce il valore PTR memorizzato. |
Rendi deliberati i tentativi
Ordini, prelievi, azioni sul server e richieste DDoS richiedono Idempotency-Key. Utilizza lettere, numeri, trattini o underscore 8–100 e assegna una nuova chiave per ogni operazione distinta prevista. Conserva la chiave originale, la risorsa e il payload prima dell'invio in modo da poter indagare su una risposta incerta.
Gli ordini possono riprodurre il risultato esistente per la stessa chiave e richiesta normalizzata; dettagli dell'ordine modificati producono un conflitto. Le riproduzioni delle azioni sul server restituiscono l'azione esistente quando compatibile. Mantieni le chiavi delle azioni uniche su tutti i server dell'account. I prelievi segnalano un conflitto quando già registrati invece di restituire la richiesta originale come successo.
POST /api/v1/servers/{serverId}/actions HTTP/1.1
Content-Type: application/json
x-csrf-token: <current-session-token>
Idempotency-Key: <unique-operation-key>
Cookie: <current-session-cookies>
{"action":"reboot"}Distingui l'accettazione dal completamento
Una risposta IN CODA 202 conferma che una richiesta hardware è stata registrata. Non contiene un URL KVM funzionante, una password di root sostitutiva o la prova che la macchina si sia riavviata. Allo stesso modo, ACCEPTED registra un ordine che entra nel provisioning; PENDING_REVIEW registra un prelievo in attesa di revisione da parte dell'operatore. Conservare l'identificativo restituito quando si chiede informazioni sull'esecuzione.
Non esiste una rotta di polling dello stato delle azioni in questa versione. Rileggere i dati del server o della rete dove rilevante e ottenere conferma dall'operatore per gli effetti fisici. Un PTR memorizzato o una preferenza DDoS da sola non è una misura del DNS pubblico o della protezione di rete attiva.
Rispondi ai guasti senza duplicare il lavoro
- Errore di convalida 400: correggere i campi documentati prima di inviare nuovamente.
- 401 o 403: ripara l'autenticazione della sessione o la verifica CSRF prima di riprovare.
- 404: verifica che l'identificatore della risorsa appartenga all'account connesso.
- 409: ispeziona il codice di errore; saldo insufficiente, capacità esaurita e conflitti di idempotenza richiedono risposte diverse.
- 502 o 503 sui depositi: non è stato restituito alcun nuovo indirizzo utilizzabile; non avviare un trasferimento.
- Timeout o risposta illeggibile: controlla i record account disponibili e conserva i dettagli della richiesta originale. Non creare ciecamente una nuova chiave operativa.