Riferimento API hosting — provisioning server con una chiamata

Guida rapida

Un server, dal nulla, in due chiamate.

Crei una chiave nell'area cliente, ne scelga gli scope, e verrà mostrata una sola volta. Su questo account non esiste una chiave master né un modo per ampliare una chiave a posteriori — ne crei invece una nuova.

1 — veda cosa può acquistare

curl -s https://api.dediprivacy.com/v1/plans?family=vps \
  -H "Authorization: Bearer $DP_KEY"

2 — la distribuisca

curl -s -X POST https://api.dediprivacy.com/v1/servers \
  -H "Authorization: Bearer $DP_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "plan":   "vps-4",
        "region": "ams",
        "image":  "debian-13",
        "cycle":  "12"
      }'

Il provisioning attinge al saldo dell'account. Una chiamata che lo porterebbe in negativo fallisce con 402 e l'esatto disavanzo invece di costruire mezza macchina — non c'è alcuno stato parzialmente provisionato da ripulire, e nessuna fattura arriva in seguito.

Convenzioni

Le parti identiche a ogni chiamata, decise una volta per tutte così non deve mai ricercarle due volte.

URL di base: https://api.dediprivacy.com/v1 Solo TLS, HTTP/2, e nessuna porta non cifrata da cui reindirizzare. Una richiesta in chiaro viene rifiutata anziché aggiornata, perché un upgrade significa che la richiesta ha già attraversato la rete una volta.
Autenticazione: Token bearer, per chiave Le chiavi vengono create nell'area clienti con gli ambiti che Lei sceglie, mostrate una sola volta e memorizzate sotto forma di hash. Non esiste una chiave master né un'autenticazione basata su password su questa API.
Tipo di contenuto: application/json Su richieste e risposte. Gli orari sono in formato RFC 3339 UTC, gli importi sono un numero intero di centesimi, e non esiste alcun formato dipendente dalla lingua.
Idempotenza: Idempotency-Key su ogni POST Una chiave ripetuta restituisce la risposta originale invece di eseguire il provisioning due volte. Le chiavi vengono ricordate per 24 ore, un tempo più lungo di quanto qualsiasi ciclo di ritentativo dovrebbe durare.
Limite di frequenza: 600 richieste al minuto Per chiave, restituito in X-RateLimit-Remaining. Le chiamate di provisioning sono limitate separatamente a 60 all'ora; ci contatti se questo rappresenta davvero un ostacolo.
Paginazione: Cursore, non numero di pagina Un next_cursor in ogni risposta di elenco. La paginazione per offset salta silenziosamente delle righe quando l'insieme sottostante cambia, e preferiamo non consegnarLe questo difetto.

Identificatori

Letto dallo stesso catalogo su cui si basano i listini pubblici e il configuratore. Una regione aggiunta all'infrastruttura appare qui senza che nessuno modifichi questa pagina.

regione

kefReykjavík
otpBucarest
sofSofia
kivChișinău
zrhZurigo
amsAmsterdam
ptyCittà di Panama
sinSingapore

famiglia

vpsVPS cloud
rdpWindows RDP
dedicatoServer dedicati
gpuCompute GPU
cloud-privatoCloud privato
hosting-webHosting Web
archiviazioneArchiviazione Object & Block
colocationColocation
personalizzatoConfigurazione personalizzata

ciclo

11 mese
33 meses, −5 %
1212 meses, −20 %
2424 meses, −35 %

Endpoint

Catalogo

Tutto ciò che può essere ordinato, con prezzi in tempo reale. Non è richiesta autenticazione — sono le stesse cifre su cui si basano i listini pubblici.

GET /regions Elenca regioni

Ogni regione con il proprio identificatore, città, paese e stato operativo attuale.

Risposta

{
  "data": [
    { "id": "ams", "city": "Amsterdam", "country": "Netherlands",
      "status": "operational", "uplink_gbit": 600 }
  ]
}

GET /plans Elenca piani

Filtri per famiglia con ?family=vps. I prezzi sono mensili, in centesimi, prima di eventuali sconti sul ciclo.

Risposta

{
  "data": [
    { "id": "vps-4", "family": "vps", "cores": 4, "ram_gb": 8,
      "disk_gb": 160, "price_cents": 1100, "regions": ["ams","kef"] }
  ],
  "next_cursor": null
}

GET /images Elenca immagini

Immagini del sistema operativo disponibili per una famiglia, con la posizione di licenza di ciascuna.

Risposta

{
  "data": [
    { "id": "debian-13", "name": "Debian 13", "licence": "included" },
    { "id": "win-2025", "name": "Windows Server 2025", "licence": "included" }
  ]
}

Endpoint

Server

Creare, ispezionare e controllare le macchine. Il provisioning attinge al saldo dell'account; una richiesta che lo porterebbe in negativo fallisce con un errore 402 e l'importo esatto mancante, anziché costruire qualcosa a metà.

POST /servers Distribuisca un server

Restituisce immediatamente lo stato "provisioning". Interroghi la risorsa oppure usi un webhook.

Richiesta

{
  "plan": "vps-4",
  "region": "ams",
  "image": "debian-13",
  "cycle": "12",
  "label": "edge-01",
  "ssh_keys": ["ssh-ed25519 AAAA..."]
}

Risposta

{
  "id": "srv_8Kq2",
  "status": "provisioning",
  "region": "ams",
  "ipv4": null,
  "charged_cents": 10560,
  "renews_at": "2027-07-28T00:00:00Z"
}

GET /servers Elenca server

Tutto ciò che riguarda l'account, dal più recente.

Risposta

{
  "data": [
    { "id": "srv_8Kq2", "label": "edge-01", "status": "active",
      "region": "ams", "ipv4": "203.0.113.10",
      "ipv6": "2001:db8:1234:5678::2" }
  ],
  "next_cursor": null
}

GET /servers/{id} Recuperi un server

Dettagli completi, incluse specifiche, indirizzi e il prossimo rinnovo.

Risposta

{
  "id": "srv_8Kq2",
  "status": "active",
  "plan": "vps-4",
  "image": "debian-13",
  "cycle": "12",
  "renews_at": "2027-07-28T00:00:00Z"
}

POST /servers/{id}/actions Agisca su un server

Un solo endpoint, un campo azione: reboot, shutdown, start, rebuild, resize, rdns.

Richiesta

{
  "action": "rebuild",
  "image": "ubuntu-26-04"
}

Risposta

{
  "id": "act_3Xf9",
  "action": "rebuild",
  "status": "running"
}

DELETE /servers/{id} Annulli un server

Prosegue fino alla fine del periodo già pagato. Aggiunga ?immediate=true per eliminarlo subito e smettere di pagare da oggi.

Risposta

{
  "id": "srv_8Kq2",
  "status": "cancelled",
  "ends_at": "2027-07-28T00:00:00Z"
}

Endpoint

Fatturazione

Un unico saldo finanzia tutto. Non esiste un oggetto fattura perché non c'è nulla da rincorrere — un servizio attinge dal saldo alla sua data di rinnovo.

GET /balance Recuperi il saldo

Saldo attuale, quanto è impegnato per i rinnovi, e quanto durerà al ritmo di consumo attuale.

Risposta

{
  "balance_cents": 48250,
  "committed_cents": 12400,
  "runway_days": 117
}

POST /topups Apra una ricarica

Restituisce un indirizzo di pagamento per l'asset scelto. Eventuali bonus vengono applicati nel momento in cui il pagamento si conferma.

Richiesta

{
  "amount_cents": 100000,
  "asset": "XMR"
}

Risposta

{
  "id": "top_5Wc1",
  "asset": "XMR",
  "address": "4A...",
  "amount": "3.417",
  "bonus_cents": 30000,
  "expires_at": "2026-07-28T18:00:00Z"
}

GET /ledger Elenchi le voci del registro

Ogni accredito e addebito, con il servizio a cui ciascuno si riferisce. Questo è tutto ciò che conserviamo sui Suoi pagamenti.

Risposta

{
  "data": [
    { "at": "2026-07-28T16:04:00Z", "cents": -1100,
      "kind": "renewal", "ref": "srv_8Kq2" }
  ]
}

Endpoint

Stato

Pubblico e senza autenticazione, così può essere interrogato da qualcosa che non è in possesso della Sua chiave — e continua a rispondere anche se il problema riguarda proprio il Suo account.

GET /status Stato attuale

Gli stessi dati della pagina di stato, calcolati dallo stesso registro degli incidenti.

Risposta

{
  "state": "operational",
  "open_incidents": 0,
  "uptime_90d": 99.9971,
  "regions": { "ams": "operational", "kef": "operational" }
}

GET /incidents Elenco incidenti

Il registro stesso, filtrabile per regione e data.

Risposta

{
  "data": [
    { "id": "inc_71", "region": "otp", "severity": "partial",
      "started_at": "2026-06-07T02:14:00Z",
      "unreachable_seconds": 1080 }
  ]
}

Errori

Ogni guasto porta con sé un codice e un messaggio scritto per una persona. Corrispondenza sul codice; il messaggio può essere migliorato.

400 invalid_request Il corpo non è stato analizzato correttamente, oppure un campo è del tipo sbagliato. Il messaggio indica il campo.

401 non autenticato Nessuna chiave, una chiave malformata, o una chiave revocata.

403 scope_missing La chiave è valida ma non è stata creata con l'ambito richiesto da questa chiamata. Gli ambiti sono scelti per ciascuna chiave e non possono essere ampliati in seguito.

402 insufficient_funds Il saldo non sarebbe sufficiente. La risposta contiene required_cents e balance_cents, in modo da poter agire senza una seconda chiamata.

404 not_found Nessuna risorsa di questo tipo su questo account. Deliberatamente identica alla risposta per una risorsa sull'account di qualcun altro.

409 conflitto La risorsa è occupata — solitamente un'operazione già in corso su quel server.

422 non disponibile Valido, ma al momento non possibile: il piano non è disponibile in quella regione, oppure l'immagine non è offerta per quella famiglia.

429 rate_limited Retry-After è impostato, ed è accurato anziché una costante.

5xx server_error Nostro. È sicuro riprovare con la stessa Idempotency-Key — è esattamente a questo che serve.

A 404 per una risorsa nell’account di qualcun altro è, byte per byte, identica a quella per una risorsa mai esistita. È intenzionale: risposte distinguibili trasformano un’API in un oracolo per enumerare l’infrastruttura altrui.

API di hostingTutto ciò che fa il configuratore, via HTTP.