API di SiteLyra

Panoramica

Introduzione

Con l'API di SiteLyra i tuoi programmi gestiscono domini, DNS, hosting e posta del tuo account, e leggono ordini e credito, senza passare dal pannello. Le risposte sono in JSON.

Con l'API puoi, per esempio, aggiungere e modificare record DNS, creare caselle e inoltri, utenti FTP e database, cambiare PHP, gestire cron, WordPress e Git. Acquisti e rinnovi si fanno sempre dal sito.

Creare una chiave

  1. Nel menu a sinistra apri API e clicca + Nuova chiave.
  2. Scrivi un nome che ti aiuti a riconoscerla, per esempio «Gestionale».
  3. Per ogni servizio scegli il permesso: nessun accesso, solo lettura, oppure lettura e modifica. La fatturazione (ordini e credito) è solo in lettura.
  4. Se vuoi, scrivi gli IP ammessi (uno per riga) e una scadenza.
  5. Clicca Nuova chiave e copia subito la chiave: non la salviamo, quindi chiusa la finestra non si può più vedere.

La chiave vale quanto chi l'ha creata: se lavori sull'account di un altro con un ruolo limitato, la chiave ha gli stessi limiti, e se vieni tolto dall'account smette di funzionare. Il proprietario e gli amministratori vedono e possono revocare tutte le chiavi dell'account.

Autenticazione

Ogni richiesta porta la chiave nell'intestazione Authorization. Negli esempi la chiave sta nella variabile API_KEY:

export API_KEY="sl_…"
curl "https://sitelyra.it/api/v1/me" -H "Authorization: Bearer $API_KEY"

Provare la chiave (/api/v1/me) restituisce la chiave, l'account su cui lavora e i permessi effettivi.

Risposte ed errori

Le risposte riuscite hanno i dati in data. Gli elenchi di domini, siti, domini di posta, ordini e movimenti del credito hanno anche meta con page, perPage e total e si sfogliano con ?page=2&per_page=100 (predefiniti 100 per pagina, al massimo 500); gli altri elenchi arrivano in data senza pagine. Le richieste che modificano mandano il corpo in JSON, con l'intestazione Content-Type: application/json.

Alcune modifiche dell'hosting (PHP, cron, hotlink, WordPress, Git) si mettono in coda sul server e si applicano in pochi secondi: la risposta è 202 con "queued": true. Lo stesso vale per la scansione anti-malware, che dà i risultati entro un'ora.

Gli errori hanno sempre la forma { "error": { "code": "…", "message": "…" } }, a volte con details:

Codice HTTPSignificato
400Il corpo della richiesta non è un oggetto JSON (invalid_body)
401Chiave mancante, sbagliata, scaduta, da un IP non ammesso o di un utente bloccato o tolto dall'account (unauthorized)
403La chiave non ha il permesso per quel servizio (forbidden)
404La risorsa non c'è, la chiave non la vede o la funzione non è attiva per il tuo account (not_found)
409Non si può nello stato attuale: il code dice perché, per esempio dns_not_hosted o site_not_active
422Un campo manca o non è valido (invalid_fields, con i campi in details.fields), oppure il server ha rifiutato un valore (rejected)
429Troppe richieste (rate_limited): limite orario della chiave o troppi tentativi con una chiave sbagliata dallo stesso IP
500Errore inatteso (internal_error)
503Un servizio (DNS, server web, registro) non risponde: riprova tra poco (unavailable)

Ogni chiamata elenca anche i suoi errori specifici.

Limiti

Ogni chiave fa al massimo 1.000 letture e 100 modifiche all'ora (oltre: 429). Le modifiche dell'hosting hanno anche il limite del pannello: 60 all'ora per persona (oltre: 409 busy). Dopo 60 richieste con una chiave sbagliata in 10 minuti, l'IP riceve 429 per il resto dei 10 minuti. Ogni persona può avere fino a 20 chiavi per account.

Password

L'API non mostra mai le password salvate (FTP, database, caselle, WordPress). Le password le generiamo noi, quando crei una casella, un utente FTP o un database o quando ne chiedi una nuova, e si vedono una volta sola, nella risposta.

Registro attività

Ogni modifica fatta con una chiave finisce nel registro attività dell'account, con il nome della chiave e l'IP da cui è arrivata.

Revocare una chiave

In API apri il menu ⋮ della chiave e scegli Revoca: i programmi che la utilizzano smettono subito di funzionare. Se una chiave finisce nelle mani sbagliate, revocala e creane una nuova.

Account

Chiave API

Operazioni

GET

Provare la chiave

/me

Restituisce la chiave, chi l'ha creata, l'account su cui lavora e i permessi effettivi per ogni servizio. È la chiamata più semplice per controllare che la chiave funzioni.

In permissions ogni servizio vale read, write oppure null (nessun accesso). I permessi effettivi possono essere meno di quelli scelti alla creazione: per esempio chi ha un ruolo in sola lettura non modifica, e la fatturazione la vedono solo il proprietario e gli amministratori. limitedToDomains elenca i domini a cui la chiave è limitata, oppure è null se vede tutto l'account.

Permesso: qualsiasi chiave valida

GET/mecURL
curl "https://sitelyra.it/api/v1/me" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "key": {
      "name": "Gestionale"
    },
    "user": {
      "email": "mario@example.com"
    },
    "account": {
      "name": "Mario Rossi",
      "email": "mario@example.com",
      "role": "owner",
      "limitedToDomains": null
    },
    "permissions": {
      "domains": "write",
      "dns": "write",
      "hosting": "read",
      "mail": "write",
      "billing": "read"
    }
  }
}

Domini

Domini

GET

Elenco dei domini

/domains

Restituisce i domini dell'account in ordine alfabetico, a pagine.

Ogni dominio ha: name (in ASCII), nameUnicode (con gli accenti), status, registeredAt ed expiresAt (date ISO 8601, null se non note), autoRenew, lock (blocco del trasferimento), privacy (WHOIS nascosto), nameservers e dns (hosted: la zona è sul nostro DNS; dnssec: off, pending o active).

Parametri della query

NomeTipoObbligatorioDescrizione
pagenumerofacoltativoPagina, da 1 (predefinita 1).
per_pagenumerofacoltativoDomini per pagina (predefiniti 100, al massimo 500).

Permesso: domains:read

GET/domainscURL
curl "https://sitelyra.it/api/v1/domains?page=1&per_page=100" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "name": "example.com",
      "nameUnicode": "example.com",
      "status": "active",
      "registeredAt": "2024-03-01T10:00:00.000Z",
      "expiresAt": "2027-03-01T10:00:00.000Z",
      "autoRenew": true,
      "lock": true,
      "privacy": true,
      "nameservers": ["ns1.example.net", "ns2.example.net"],
      "dns": {
        "hosted": true,
        "dnssec": "off"
      }
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 100,
    "total": 1
  }
}
GET

Dettagli di un dominio

/domains/{domain}

Restituisce un dominio: stato, scadenza, rinnovo automatico, blocco, privacy, nameserver e DNS.

Ogni dominio ha: name (in ASCII), nameUnicode (con gli accenti), status, registeredAt ed expiresAt (date ISO 8601, null se non note), autoRenew, lock (blocco del trasferimento), privacy (WHOIS nascosto), nameservers e dns (hosted: la zona è sul nostro DNS; dnssec: off, pending o active).

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: domains:read

GET/domains/{domain}cURL
curl "https://sitelyra.it/api/v1/domains/example.com" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "name": "example.com",
    "nameUnicode": "example.com",
    "status": "active",
    "registeredAt": "2024-03-01T10:00:00.000Z",
    "expiresAt": "2027-03-01T10:00:00.000Z",
    "autoRenew": true,
    "lock": true,
    "privacy": true,
    "nameservers": ["ns1.example.net", "ns2.example.net"],
    "dns": {
      "hosted": true,
      "dnssec": "off"
    }
  }
}

Domini

Nameserver

Come funziona nel pannello: guida Nameserver.

GET

Elenco dei gruppi di nameserver

/nameserver-groups

Restituisce i gruppi di nameserver da assegnare ai domini: il nostro (system: true) e quelli creati nel tuo account.

Non è disponibile per chi è limitato ad alcuni domini, come nel pannello.

Errori specifici

StatoCodiceDescrizione
403forbiddenLa chiave è limitata ad alcuni domini.

Permesso: domains:read

GET/nameserver-groupscURL
curl "https://sitelyra.it/api/v1/nameserver-groups" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "id": "cm3k9x2ab0000qz8f1a2b3c4d",
      "label": "SiteLyra",
      "system": true,
      "nameservers": ["ns1.example.net", "ns2.example.net"]
    },
    {
      "id": "cm3k9x2ab0001qz8f7h2d4e5g",
      "label": "Miei server",
      "system": false,
      "nameservers": ["ns1.example.com", "ns2.example.com"]
    }
  ]
}
PUT

Cambiare i nameserver

/domains/{domain}/nameservers

Assegna al dominio un gruppo di nameserver: il nostro oppure uno dei gruppi del tuo account.

Gli id dei gruppi si leggono con Gruppi di nameserver. Passando ai nostri nameserver la zona DNS si crea da sola, con i record predefiniti.

Errori specifici

StatoCodiceDescrizione
404not_foundIl dominio o il gruppo non esistono.
409operation_failedIl registro non ha accettato i nameserver: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
grouptestoobbligatorioId del gruppo di nameserver.

Permesso: domains:write

PUT/domains/{domain}/nameserverscURL
curl -X PUT "https://sitelyra.it/api/v1/domains/example.com/nameservers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group":"cm3k9x2ab0001qz8f7h2d4e5g"}'
200
{
  "data": {
    "name": "example.com",
    "nameUnicode": "example.com",
    "status": "active",
    "registeredAt": "2024-03-01T10:00:00.000Z",
    "expiresAt": "2027-03-01T10:00:00.000Z",
    "autoRenew": true,
    "lock": true,
    "privacy": true,
    "nameservers": ["ns1.example.com", "ns2.example.com"],
    "dns": {
      "hosted": false,
      "dnssec": "off"
    }
  }
}

Domini

Privacy WHOIS

Come funziona nel pannello: guida Privacy WHOIS.

PUT

Attivare o disattivare la privacy

/domains/{domain}/privacy

Nasconde o mostra i dati dell'intestatario nel WHOIS pubblico.

Errori specifici

StatoCodiceDescrizione
404not_foundIl dominio non esiste o la privacy non è disponibile per questo dominio.
409operation_failedIl registro non ha accettato la modifica: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
enabledvero/falsoobbligatoriotrue per nascondere i dati, false per mostrarli.

Permesso: domains:write

PUT/domains/{domain}/privacycURL
curl -X PUT "https://sitelyra.it/api/v1/domains/example.com/privacy" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'
200
{
  "data": {
    "name": "example.com",
    "nameUnicode": "example.com",
    "status": "active",
    "registeredAt": "2024-03-01T10:00:00.000Z",
    "expiresAt": "2027-03-01T10:00:00.000Z",
    "autoRenew": true,
    "lock": true,
    "privacy": true,
    "nameservers": ["ns1.example.net", "ns2.example.net"],
    "dns": {
      "hosted": true,
      "dnssec": "off"
    }
  }
}

Domini

Protezione dal furto

Come funziona nel pannello: guida Protezione dal furto.

PUT

Attivare o disattivare il blocco

/domains/{domain}/lock

Attiva o disattiva il blocco del trasferimento: con il blocco attivo nessuno può trasferire il dominio a un altro fornitore.

Per trasferire il dominio altrove disattiva il blocco e leggi il codice di trasferimento.

Errori specifici

StatoCodiceDescrizione
409unsupportedL'estensione del dominio non ha il blocco.
409operation_failedIl registro non ha accettato la modifica: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
enabledvero/falsoobbligatoriotrue per attivare il blocco, false per toglierlo.

Permesso: domains:write

PUT/domains/{domain}/lockcURL
curl -X PUT "https://sitelyra.it/api/v1/domains/example.com/lock" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'
200
{
  "data": {
    "name": "example.com",
    "nameUnicode": "example.com",
    "status": "active",
    "registeredAt": "2024-03-01T10:00:00.000Z",
    "expiresAt": "2027-03-01T10:00:00.000Z",
    "autoRenew": true,
    "lock": false,
    "privacy": true,
    "nameservers": ["ns1.example.net", "ns2.example.net"],
    "dns": {
      "hosted": true,
      "dnssec": "off"
    }
  }
}

Domini

Codice di trasferimento

Come funziona nel pannello: guida Codice di trasferimento.

POST

Leggere il codice di trasferimento

/domains/{domain}/auth-code

Legge dal registro il codice di trasferimento (EPP o auth code), che serve per portare il dominio a un altro fornitore.

Il codice non lo salviamo: si legge al momento e ogni lettura resta nel registro attività. Serve il permesso di modifica dei domini e un ruolo che veda le password.

Errori specifici

StatoCodiceDescrizione
409operation_failedIl registro non ha restituito il codice: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: domains:write

POST/domains/{domain}/auth-codecURL
curl -X POST "https://sitelyra.it/api/v1/domains/example.com/auth-code" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "authCode": "x7T#q2Lm9vRk"
  }
}

Domini

Glue record

Come funziona nel pannello: guida Glue record.

Operazioni

GET

Elenco dei glue record

/glue

Restituisce i glue record dell'account: nome host, IPv4, IPv6 e il dominio a cui appartengono.

Non è disponibile per chi è limitato ad alcuni domini, come nel pannello.

Errori specifici

StatoCodiceDescrizione
403forbiddenLa chiave è limitata ad alcuni domini.

Permesso: domains:read

GET/gluecURL
curl "https://sitelyra.it/api/v1/glue" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "name": "ns1.example.com",
      "ip": "203.0.113.10",
      "ip6": null,
      "domain": "example.com"
    }
  ]
}
GET

Elenco dei record DNS

/dns/{domain}/records

Restituisce i record della zona sul nostro DNS, nell'ordine dei file di zona.

Ogni record ha id, type, host (vuoto = il dominio), ttl, value (il valore in una riga, come nel pannello) e fields (i singoli valori, gli stessi da mandare per modificarlo). I record con system: true sono gli NS della zona: si vedono ma non si modificano.

Errori specifici

StatoCodiceDescrizione
409dns_not_hostedIl dominio non utilizza i nostri nameserver, oppure la sua zona non è ancora pronta: i record si gestiscono dove sta il DNS.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: dns:read

GET/dns/{domain}/recordscURL
curl "https://sitelyra.it/api/v1/dns/example.com/records" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "id": "512345670",
      "type": "NS",
      "host": "",
      "ttl": 3600,
      "value": "ns1.example.net",
      "fields": {
        "record": "ns1.example.net"
      },
      "system": true
    },
    {
      "id": "512345679",
      "type": "MX",
      "host": "",
      "ttl": 3600,
      "value": "10 mail.example.com",
      "fields": {
        "priority": "10",
        "record": "mail.example.com"
      },
      "system": false
    },
    {
      "id": "512345678",
      "type": "A",
      "host": "www",
      "ttl": 3600,
      "value": "203.0.113.10",
      "fields": {
        "record": "203.0.113.10"
      },
      "system": false
    }
  ]
}
POST

Aggiungere un record DNS

/dns/{domain}/records

Aggiunge un record alla zona e lo restituisce con il suo id. Se il record nuovo non si riconosce nell'elenco della zona, la risposta è {"created": true}.

Esempio per la posta: {"type":"MX","host":"","fields":{"priority":10,"record":"mail.example.com"}}. Esempio TXT: {"type":"TXT","host":"_dmarc","fields":{"record":"v=DMARC1; p=none"}}.

Errori specifici

StatoCodiceDescrizione
422invalid_fieldsUn campo manca o non è valido: error.details.fields dice quale.
422rejectedIl server DNS ha rifiutato il valore: il messaggio spiega perché.
409dns_limitÈ stato raggiunto il numero massimo di record del dominio (error.details.values.max).
409dns_not_hostedIl dominio non utilizza i nostri nameserver, oppure la sua zona non è ancora pronta: i record si gestiscono dove sta il DNS.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
typetestoobbligatorioTipo, in maiuscole o minuscole: A, AAAA, ALIAS, CAA, CERT, CNAME, DNAME, DS, HINFO, HTTPS, LOC, MX, NAPTR, NS, OPENPGPKEY, PTR, RP, SMIMEA, SPF, SRV, SSHFP, SVCB, TLSA, TXT, WR (redirect web).
hosttestofacoltativoNome: www, mail… Vuoto o @ = il dominio stesso.
ttlnumerofacoltativoDurata in secondi (predefinita 3600), uno di questi valori: 60, 300, 600, 900, 1800, 3600, 21600, 43200, 86400, 172800, 259200, 604800, 1209600, 2592000.
fieldsoggettoobbligatorioValori del tipo, in testo o numero. Quasi sempre record (l'indirizzo, il nome o il testo); MX e SRV anche priority (da 0 a 65535), SRV weight e port (da 0 a 65535), CAA caa_flag (0 o 128), caa_type (issue, issuewild, iodef, issuemail, issuevmc, contactemail, contactphone) e caa_value, WR redirect_type (301 o 302), frame e save_path (0 o 1).

Permesso: dns:write

POST/dns/{domain}/recordscURL
curl -X POST "https://sitelyra.it/api/v1/dns/example.com/records" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","host":"www","ttl":3600,"fields":{"record":"203.0.113.10"}}'
200
{
  "data": {
    "id": "512345678",
    "type": "A",
    "host": "www",
    "ttl": 3600,
    "value": "203.0.113.10",
    "fields": {
      "record": "203.0.113.10"
    },
    "system": false
  }
}
PUT

Modificare un record DNS

/dns/{domain}/records/{id}

Riscrive un record: nome, durata e valori. Il tipo non cambia (per cambiarlo eliminalo e aggiungine uno nuovo).

Manda tutti i valori del record, non solo quelli che cambiano: quelli assenti si tolgono, host assente = il dominio stesso, ttl assente = 3600. Risponde con il record modificato (o {"updated": true} se non si ritrova nell'elenco della zona).

Errori specifici

StatoCodiceDescrizione
409system_recordÈ un NS della zona, che non si modifica.
422invalid_fieldsUn campo manca o non è valido: error.details.fields dice quale.
422rejectedIl server DNS ha rifiutato il valore: il messaggio spiega perché.
409dns_not_hostedIl dominio non utilizza i nostri nameserver, oppure la sua zona non è ancora pronta: i record si gestiscono dove sta il DNS.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
idtestoobbligatorioId del record, dall'elenco dei record.

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
typetestofacoltativoFacoltativo: il tipo non cambia; se lo scrivi deve essere quello del record.
hosttestofacoltativoNome: www, mail… Vuoto o @ = il dominio stesso.
ttlnumerofacoltativoDurata in secondi (predefinita 3600), uno di questi valori: 60, 300, 600, 900, 1800, 3600, 21600, 43200, 86400, 172800, 259200, 604800, 1209600, 2592000.
fieldsoggettoobbligatorioValori del tipo, in testo o numero. Quasi sempre record (l'indirizzo, il nome o il testo); MX e SRV anche priority (da 0 a 65535), SRV weight e port (da 0 a 65535), CAA caa_flag (0 o 128), caa_type (issue, issuewild, iodef, issuemail, issuevmc, contactemail, contactphone) e caa_value, WR redirect_type (301 o 302), frame e save_path (0 o 1).

Permesso: dns:write

PUT/dns/{domain}/records/{id}cURL
curl -X PUT "https://sitelyra.it/api/v1/dns/example.com/records/512345678" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"host":"www","ttl":600,"fields":{"record":"203.0.113.20"}}'
200
{
  "data": {
    "id": "512345678",
    "type": "A",
    "host": "www",
    "ttl": 600,
    "value": "203.0.113.20",
    "fields": {
      "record": "203.0.113.20"
    },
    "system": false
  }
}
DELETE

Eliminare un record DNS

/dns/{domain}/records/{id}

Elimina un record dalla zona.

Errori specifici

StatoCodiceDescrizione
409system_recordÈ un NS della zona, che non si elimina.
422rejectedIl server DNS ha rifiutato la richiesta: il messaggio spiega perché.
409dns_not_hostedIl dominio non utilizza i nostri nameserver, oppure la sua zona non è ancora pronta: i record si gestiscono dove sta il DNS.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
idtestoobbligatorioId del record, dall'elenco dei record.

Permesso: dns:write

DELETE/dns/{domain}/records/{id}cURL
curl -X DELETE "https://sitelyra.it/api/v1/dns/example.com/records/512345678" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "deleted": true
  }
}

DNS

Modelli DNS

Come funziona nel pannello: guida Modelli DNS.

GET

Elenco dei modelli DNS

/dns/templates

Restituisce i modelli da applicare a una zona (per esempio Google Workspace o Microsoft 365), con i record che aggiungono.

name e description sono in inglese; description può essere null. Nei valori dei record possono comparire segnaposto ({domain}, {domainDashed}, {serverIp4}, {serverIp6}) che si riempiono quando il modello si applica.

Permesso: dns:read

GET/dns/templatescURL
curl "https://sitelyra.it/api/v1/dns/templates" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "slug": "google-workspace",
      "name": "Google Workspace",
      "description": "Gmail for your domain: Google mail server and SPF.",
      "records": [
        {
          "type": "MX",
          "host": "",
          "ttl": 3600,
          "fields": {
            "priority": "1",
            "record": "smtp.google.com"
          }
        },
        {
          "type": "TXT",
          "host": "",
          "ttl": 3600,
          "fields": {
            "record": "v=spf1 include:_spf.google.com ~all"
          }
        }
      ]
    }
  ]
}
POST

Applicare un modello DNS

/dns/{domain}/templates/{slug}

Aggiunge alla zona i record del modello che mancano; quelli già presenti restano. added dice quanti record ha aggiunto.

Errori specifici

StatoCodiceDescrizione
409dns_limitI record del modello (contati tutti, anche quelli già presenti) superano il numero massimo di record del dominio (error.details.values.max).
422rejectedIl server DNS ha rifiutato un record del modello: il messaggio spiega perché.
409dns_not_hostedIl dominio non utilizza i nostri nameserver, oppure la sua zona non è ancora pronta: i record si gestiscono dove sta il DNS.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
slugtestoobbligatorioNome del modello, dall'elenco dei modelli DNS.

Permesso: dns:write

POST/dns/{domain}/templates/{slug}cURL
curl -X POST "https://sitelyra.it/api/v1/dns/example.com/templates/google-workspace" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "added": 2
  }
}

DNS

SOA

Come funziona nel pannello: guida SOA.

GET

Leggere il SOA

/dns/{domain}/soa

Restituisce il SOA della zona: server primario, email del responsabile e tempi in secondi.

Errori specifici

StatoCodiceDescrizione
409dns_not_hostedIl dominio non utilizza i nostri nameserver, oppure la sua zona non è ancora pronta: i record si gestiscono dove sta il DNS.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: dns:read

GET/dns/{domain}/soacURL
curl "https://sitelyra.it/api/v1/dns/example.com/soa" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "serial": "2026110701",
    "primaryNs": "ns1.example.net",
    "adminMail": "hostmaster@example.com",
    "refresh": 7200,
    "retry": 1800,
    "expire": 1209600,
    "defaultTtl": 3600
  }
}
PUT

Modificare il SOA

/dns/{domain}/soa

Cambia l'email del responsabile e i tempi del SOA. Il server primario resta sempre il nostro.

I campi che non mandi restano come sono.

Errori specifici

StatoCodiceDescrizione
422invalid_fieldsUn campo manca o non è valido: error.details.fields dice quale.
422rejectedIl server DNS ha rifiutato il valore: il messaggio spiega perché.
409dns_not_hostedIl dominio non utilizza i nostri nameserver, oppure la sua zona non è ancora pronta: i record si gestiscono dove sta il DNS.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
adminMailtestofacoltativoEmail del responsabile della zona.
refreshnumerofacoltativoDa 1200 a 43200 secondi.
retrynumerofacoltativoDa 180 a 2419200 secondi.
expirenumerofacoltativoDa 1209600 a 2419200 secondi.
defaultTtlnumerofacoltativoDa 60 a 2419200 secondi.

Permesso: dns:write

PUT/dns/{domain}/soacURL
curl -X PUT "https://sitelyra.it/api/v1/dns/example.com/soa" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"adminMail":"dns@example.com","refresh":3600}'
200
{
  "data": {
    "serial": "2026110702",
    "primaryNs": "ns1.example.net",
    "adminMail": "dns@example.com",
    "refresh": 3600,
    "retry": 1800,
    "expire": 1209600,
    "defaultTtl": 3600
  }
}

DNS

DNSSEC

Come funziona nel pannello: guida DNSSEC.

GET

Stato del DNSSEC

/dns/{domain}/dnssec

Restituisce lo stato del DNSSEC: off, pending (zona firmata, chiavi in arrivo al registro) oppure active.

Errori specifici

StatoCodiceDescrizione
409dns_not_hostedIl dominio non utilizza i nostri nameserver, oppure la sua zona non è ancora pronta: i record si gestiscono dove sta il DNS.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: dns:read

GET/dns/{domain}/dnsseccURL
curl "https://sitelyra.it/api/v1/dns/example.com/dnssec" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "state": "active"
  }
}
PUT

Attivare o disattivare il DNSSEC

/dns/{domain}/dnssec

Attiva il DNSSEC (firma della zona e chiavi al registro appena pronte) o lo disattiva (prima si tolgono le chiavi dal registro, poi la firma).

Dopo l'attivazione lo stato resta pending per qualche minuto, poi diventa active.

Errori specifici

StatoCodiceDescrizione
422invalid_fieldsenabled manca o non è true/false: error.details.fields lo dice.
422rejectedIl server DNS ha rifiutato la richiesta: il messaggio spiega perché.
409dns_not_hostedIl dominio non utilizza i nostri nameserver, oppure la sua zona non è ancora pronta: i record si gestiscono dove sta il DNS.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
enabledvero/falsoobbligatoriotrue per attivare, false per disattivare.

Permesso: dns:write

PUT/dns/{domain}/dnsseccURL
curl -X PUT "https://sitelyra.it/api/v1/dns/example.com/dnssec" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'
200
{
  "data": {
    "state": "pending"
  }
}

Hosting

Siti

Come funziona nel pannello: guida Siti.

GET

Elenco dei siti

/hosting

Restituisce i siti hosting dell'account in ordine alfabetico, a pagine.

Ogni sito ha: domain, status (active, provisioning, suspended…), plan, app (wordpress o null), mainSite (il sito principale, se il sito è stato aggiunto a un piano), startsAt ed expiresAt, autoRenew, limits (spazio in MB, database, utenti FTP, caselle; -1 = illimitato) e features (funzioni del piano).

Parametri della query

NomeTipoObbligatorioDescrizione
pagenumerofacoltativoPagina, da 1.
per_pagenumerofacoltativoSiti per pagina (predefiniti 100, al massimo 500).

Permesso: hosting:read

GET/hostingcURL
curl "https://sitelyra.it/api/v1/hosting" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "domain": "example.com",
      "domainUnicode": "example.com",
      "status": "active",
      "plan": {
        "slug": "plus",
        "name": "Plus"
      },
      "app": "wordpress",
      "mainSite": null,
      "startsAt": "2026-01-10T09:00:00.000Z",
      "expiresAt": "2027-01-10T09:00:00.000Z",
      "autoRenew": true,
      "limits": {
        "diskMb": 20480,
        "databases": 10,
        "ftpUsers": 10,
        "mailboxes": 10
      },
      "features": ["ssl", "wordpress", "backup", "cron"]
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 100,
    "total": 1
  }
}
GET

Dettagli di un sito

/hosting/{domain}

Restituisce un sito con lo stato sul server: versione PHP, spazio occupato, sito in funzione e WordPress.

Ogni sito ha: domain, status (active, provisioning, suspended…), plan, app (wordpress o null), mainSite (il sito principale, se il sito è stato aggiunto a un piano), startsAt ed expiresAt, autoRenew, limits (spazio in MB, database, utenti FTP, caselle; -1 = illimitato) e features (funzioni del piano). Se il sito non è attivo o il server non risponde, i dati del sito arrivano lo stesso, con server: null.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: hosting:read

GET/hosting/{domain}cURL
curl "https://sitelyra.it/api/v1/hosting/example.com" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "domain": "example.com",
    "domainUnicode": "example.com",
    "status": "active",
    "plan": {
      "slug": "plus",
      "name": "Plus"
    },
    "app": "wordpress",
    "mainSite": null,
    "startsAt": "2026-01-10T09:00:00.000Z",
    "expiresAt": "2027-01-10T09:00:00.000Z",
    "autoRenew": true,
    "limits": {
      "diskMb": 20480,
      "databases": 10,
      "ftpUsers": 10,
      "mailboxes": 10
    },
    "features": ["ssl", "wordpress", "backup", "cron"],
    "server": {
      "phpVersion": "8.3",
      "diskUsedBytes": 734003200,
      "diskLimitBytes": 21474836480,
      "running": true,
      "wordpress": true
    }
  }
}
GET

Elenco degli utenti FTP

/hosting/{domain}/ftp-users

Restituisce gli utenti FTP aggiunti al sito, con cartella (directory, il percorso completo sul server) e stato; quotaMb 0 = nessun limite proprio. L'utente principale del sito non compare nell'elenco (primary è sempre false). Le password non si leggono mai.

Errori specifici

StatoCodiceDescrizione
409site_not_activeIl sito non è attivo (in creazione, sospeso o non riuscito).
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: hosting:read

GET/hosting/{domain}/ftp-userscURL
curl "https://sitelyra.it/api/v1/hosting/example.com/ftp-users" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "user": "example_com_dev",
      "directory": "/srv/sites/example_com/www/dev",
      "quotaMb": 0,
      "active": true,
      "primary": false
    }
  ]
}
POST

Aggiungere un utente FTP

/hosting/{domain}/ftp-users

Crea un utente FTP limitato a una cartella del sito. La password la generiamo noi e si vede solo in questa risposta.

Errori specifici

StatoCodiceDescrizione
422invalidIl nome o la cartella non sono validi.
409too_longIl nome completo supera i 32 caratteri.
409takenIl nome è già utilizzato.
409limitIl piano non ha altri utenti FTP disponibili.
409not_activeIl sito non è attivo.
409busyHai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
suffixtestoobbligatorioDa 2 a 16 lettere minuscole o cifre: il nome diventa <utente del sito>_<suffix>.
directorytestofacoltativoCartella dentro www a cui è limitato (per esempio dev): lettere, cifre, ., _, - e /; si crea se non c'è. Vuota = tutto il sito.

Permesso: hosting:write

POST/hosting/{domain}/ftp-userscURL
curl -X POST "https://sitelyra.it/api/v1/hosting/example.com/ftp-users" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"suffix":"dev","directory":"dev"}'
200
{
  "data": {
    "user": "example_com_dev",
    "password": "Hq7mT2kPz9xRw4sN"
  }
}
PATCH

Sospendere o riattivare un utente FTP

/hosting/{domain}/ftp-users/{user}

Sospende o riattiva un utente FTP aggiunto. L'utente principale resta sempre attivo.

Errori specifici

StatoCodiceDescrizione
409not_activeIl sito non è attivo.
409busyHai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
usertestoobbligatorioNome dell'utente FTP, dall'elenco degli utenti FTP.

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
activevero/falsoobbligatoriofalse per sospendere, true per riattivare.

Permesso: hosting:write

PATCH/hosting/{domain}/ftp-users/{user}cURL
curl -X PATCH "https://sitelyra.it/api/v1/hosting/example.com/ftp-users/example_com_dev" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active":false}'
200
{
  "data": {
    "user": "example_com_dev",
    "active": false
  }
}
DELETE

Eliminare un utente FTP

/hosting/{domain}/ftp-users/{user}

Elimina un utente FTP aggiunto. I file restano nel sito.

Errori specifici

StatoCodiceDescrizione
409not_activeIl sito non è attivo.
409busyHai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
usertestoobbligatorioNome dell'utente FTP, dall'elenco degli utenti FTP.

Permesso: hosting:write

DELETE/hosting/{domain}/ftp-users/{user}cURL
curl -X DELETE "https://sitelyra.it/api/v1/hosting/example.com/ftp-users/example_com_dev" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "deleted": true
  }
}
POST

Nuova password FTP

/hosting/{domain}/ftp-users/{user}/password

Genera una nuova password per un utente FTP, anche per quello principale. La vecchia smette subito di funzionare; la nuova si vede solo in questa risposta.

Errori specifici

StatoCodiceDescrizione
409not_activeIl sito non è attivo.
409busyHai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
usertestoobbligatorioNome dell'utente FTP, dall'elenco degli utenti FTP.

Permesso: hosting:write

POST/hosting/{domain}/ftp-users/{user}/passwordcURL
curl -X POST "https://sitelyra.it/api/v1/hosting/example.com/ftp-users/example_com/password" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "user": "example_com",
    "password": "Tz4kQ8mW2pXn7Rv3"
  }
}
GET

Repository Git del sito

/hosting/{domain}/git

Restituisce il repository collegato al sito: indirizzo, ramo, chiave di deploy da aggiungere al repository (in sola lettura), ultimo commit ed esito dell'ultimo aggiornamento.

Errori specifici

StatoCodiceDescrizione
409not_activeIl sito non è attivo.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: hosting:read

GET/hosting/{domain}/gitcURL
curl "https://sitelyra.it/api/v1/hosting/example.com/git" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "supported": true,
    "configured": true,
    "url": "git@github.com:example/site.git",
    "branch": "main",
    "publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI… deploy@example.com",
    "head": {
      "hash": "3f2a9c1e8b7d6a5f4e3d2c1b0a9f8e7d6c5b4a32",
      "subject": "Nuova home",
      "date": "2026-11-06T19:20:00+01:00"
    },
    "wwwEmpty": false,
    "lastPull": {
      "ok": true,
      "message": null,
      "hash": "3f2a9c1e8b7d6a5f4e3d2c1b0a9f8e7d6c5b4a32",
      "subject": "Nuova home",
      "at": "2026-11-06T18:21:00.000Z"
    }
  }
}
PUT

Collegare un repository Git

/hosting/{domain}/git

Collega un repository al sito, o cambia indirizzo e ramo. Restituisce lo stato, con la chiave di deploy da aggiungere al repository.

Errori specifici

StatoCodiceDescrizione
409git_repo_invalidL'indirizzo del repository non è valido.
409git_branch_invalidIl nome del ramo non è valido.
409git_unsupportedIl sito non supporta Git.
409not_activeIl sito non è attivo.
409busyHai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
urltestoobbligatorioIndirizzo SSH (git@host:percorso o ssh://…) o HTTPS senza credenziali del repository, al massimo 300 caratteri.
branchtestofacoltativoRamo da scaricare, al massimo 100 caratteri (predefinito main).

Permesso: hosting:write

PUT/hosting/{domain}/gitcURL
curl -X PUT "https://sitelyra.it/api/v1/hosting/example.com/git" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"git@github.com:example/site.git","branch":"main"}'
200
{
  "data": {
    "supported": true,
    "configured": true,
    "url": "git@github.com:example/site.git",
    "branch": "main",
    "publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI… deploy@example.com",
    "head": null,
    "wwwEmpty": true,
    "lastPull": null
  }
}
DELETE

Scollegare il repository Git

/hosting/{domain}/git

Scollega il repository dal sito e cancella la chiave di deploy: se ne colleghi un altro, la chiave è nuova. I file del sito restano.

Errori specifici

StatoCodiceDescrizione
409not_activeIl sito non è attivo.
409busyHai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: hosting:write

DELETE/hosting/{domain}/gitcURL
curl -X DELETE "https://sitelyra.it/api/v1/hosting/example.com/git" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "deleted": true
  }
}
POST

Aggiornare il sito da Git

/hosting/{domain}/git/pull

Scarica nel sito le ultime modifiche del ramo collegato.

La modifica si mette in coda sul server e si applica in pochi secondi, una alla volta per sito: la risposta è 202 con queued: true. L'esito si legge in Repository Git del sito, campo lastPull (ok: false con il motivo in message se l'aggiornamento non riesce). Il primo aggiornamento richiede la cartella www vuota (campo wwwEmpty). Puoi chiamarla da una pipeline (per esempio GitHub Actions) dopo ogni push.

Errori specifici

StatoCodiceDescrizione
409not_activeIl sito non è attivo.
409busyC'è già una modifica in corso sul sito, oppure hai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: hosting:write

POST/hosting/{domain}/git/pullcURL
curl -X POST "https://sitelyra.it/api/v1/hosting/example.com/git/pull" \
  -H "Authorization: Bearer $API_KEY"
202
{
  "data": {
    "queued": true
  }
}
GET

Elenco dei database

/hosting/{domain}/databases

Restituisce i database del sito: quello creato con il sito (primary: true) e quelli aggiunti, con lo spazio occupato in byte (null se non si legge).

Errori specifici

StatoCodiceDescrizione
409site_not_activeIl sito non è attivo (in creazione, sospeso o non riuscito).
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: hosting:read

GET/hosting/{domain}/databasescURL
curl "https://sitelyra.it/api/v1/hosting/example.com/databases" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "name": "example_com",
      "primary": true,
      "sizeBytes": 52428800
    },
    {
      "name": "example_com_shop",
      "primary": false,
      "sizeBytes": 1048576
    }
  ]
}
POST

Aggiungere un database

/hosting/{domain}/databases

Crea un database MariaDB con il suo utente (stesso nome). La password la generiamo noi e si vede solo in questa risposta.

Errori specifici

StatoCodiceDescrizione
422invalidIl nome non è valido.
409too_longIl nome completo supera i 32 caratteri.
409takenIl nome è già utilizzato.
409limitIl piano non ha altri database disponibili.
409not_activeIl sito non è attivo.
409busyHai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
suffixtestoobbligatorioDa 2 a 16 lettere minuscole o cifre: il nome diventa <prefisso del sito>_<suffix>.

Permesso: hosting:write

POST/hosting/{domain}/databasescURL
curl -X POST "https://sitelyra.it/api/v1/hosting/example.com/databases" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"suffix":"shop"}'
200
{
  "data": {
    "name": "example_com_shop",
    "user": "example_com_shop",
    "password": "pX7rK2mQ9tW4zN8vB3sL"
  }
}
DELETE

Eliminare un database

/hosting/{domain}/databases/{name}

Elimina un database aggiunto con tutti i suoi dati. Il database creato con il sito non si elimina.

L'eliminazione non si può annullare.

Errori specifici

StatoCodiceDescrizione
409not_activeIl sito non è attivo.
409busyHai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
nametestoobbligatorioNome del database, dall'elenco dei database.

Permesso: hosting:write

DELETE/hosting/{domain}/databases/{name}cURL
curl -X DELETE "https://sitelyra.it/api/v1/hosting/example.com/databases/example_com_shop" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "deleted": true
  }
}
POST

Nuova password del database

/hosting/{domain}/databases/{name}/password

Genera una nuova password per un database aggiunto: si vede solo in questa risposta. Ricordati di aggiornarla nel sito.

Errori specifici

StatoCodiceDescrizione
409not_activeIl sito non è attivo.
409busyHai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
nametestoobbligatorioNome del database, dall'elenco dei database.

Permesso: hosting:write

POST/hosting/{domain}/databases/{name}/passwordcURL
curl -X POST "https://sitelyra.it/api/v1/hosting/example.com/databases/example_com_shop/password" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "name": "example_com_shop",
    "password": "mR8tK3wQ7pZ2xN9vL4sB"
  }
}
GET

IP ammessi a phpMyAdmin

/hosting/{domain}/phpmyadmin/ips

Restituisce gli IP da cui si può aprire phpMyAdmin. Valgono per tutti i siti dell'account, 30 giorni ciascuno, al massimo 5.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: hosting:read

GET/hosting/{domain}/phpmyadmin/ipscURL
curl "https://sitelyra.it/api/v1/hosting/example.com/phpmyadmin/ips" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "id": "cm3pma0000001qz8f1a2b3c4d",
      "ip": "203.0.113.50",
      "note": "Ufficio",
      "expiresAt": "2026-12-07T10:00:00.000Z",
      "createdAt": "2026-11-07T10:00:00.000Z"
    }
  ]
}
POST

Ammettere un IP a phpMyAdmin

/hosting/{domain}/phpmyadmin/ips

Ammette un IP a phpMyAdmin per 30 giorni; se c'è già, i 30 giorni ripartono. Restituisce l'elenco aggiornato.

Errori specifici

StatoCodiceDescrizione
409ip_invalidL'indirizzo non è valido.
409ip_limitCi sono già 5 IP ammessi.
409busyHai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
iptestoobbligatorioUn indirizzo IPv4 o IPv6 (non una rete).
notetestofacoltativoNota, fino a 100 caratteri: oltre si taglia (per esempio «Ufficio»). Se l'IP c'è già e la nota è vuota, resta quella di prima.

Permesso: hosting:write

POST/hosting/{domain}/phpmyadmin/ipscURL
curl -X POST "https://sitelyra.it/api/v1/hosting/example.com/phpmyadmin/ips" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ip":"203.0.113.50","note":"Ufficio"}'
200
{
  "data": [
    {
      "id": "cm3pma0000001qz8f1a2b3c4d",
      "ip": "203.0.113.50",
      "note": "Ufficio",
      "expiresAt": "2026-12-07T10:00:00.000Z",
      "createdAt": "2026-11-07T10:00:00.000Z"
    }
  ]
}
DELETE

Togliere un IP da phpMyAdmin

/hosting/{domain}/phpmyadmin/ips/{id}

Toglie un IP da quelli ammessi a phpMyAdmin.

Errori specifici

StatoCodiceDescrizione
409busyHai fatto più di 60 modifiche all'ora: riprova tra poco.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
idtestoobbligatorioId dell'IP, dall'elenco degli IP ammessi.

Permesso: hosting:write

DELETE/hosting/{domain}/phpmyadmin/ips/{id}cURL
curl -X DELETE "https://sitelyra.it/api/v1/hosting/example.com/phpmyadmin/ips/cm3pma0000001qz8f1a2b3c4d" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "deleted": true
  }
}

Hosting

Impostazioni PHP

Come funziona nel pannello: guida Impostazioni PHP.

GET

Versione e impostazioni PHP

/hosting/{domain}/php

Restituisce la versione PHP del sito, le impostazioni attuali e i valori che si possono scegliere.

Errori specifici

StatoCodiceDescrizione
409site_not_activeIl sito non è attivo (in creazione, sospeso o non riuscito).
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: hosting:read

GET/hosting/{domain}/phpcURL
curl "https://sitelyra.it/api/v1/hosting/example.com/php" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "version": "8.3",
    "settings": {
      "memory_limit": "256M",
      "upload_max_filesize": "64M",
      "post_max_size": "64M",
      "max_execution_time": "60"
    },
    "available": {
      "versions": ["8.1", "8.2", "8.3", "8.4"],
      "settings": {
        "memory_limit": ["128M", "256M", "512M", "1024M"],
        "upload_max_filesize": ["16M", "32M", "64M", "128M", "256M", "512M"],
        "post_max_size": ["16M", "32M", "64M", "128M", "256M", "512M"],
        "max_execution_time": ["30", "60", "120", "300"]
      }
    }
  }
}
PATCH

Cambiare PHP

/hosting/{domain}/php

Cambia la versione PHP e/o le impostazioni del sito, con i valori dell'elenco di Versione e impostazioni PHP.

La modifica si mette in coda sul server e si applica in pochi secondi, una alla volta per sito: la risposta è 202 con queued: true.

Errori specifici

StatoCodiceDescrizione
422invalidVersione o valore non ammessi, oppure niente da cambiare.
422invalid_fieldsUn campo non è valido (per esempio un'impostazione di settings che non esiste): error.details.fields dice quale.
409not_activeIl sito non è attivo.
409busyC'è già una modifica in corso sul sito, oppure hai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
versiontestofacoltativoVersione PHP, per esempio 8.3.
settingsoggettofacoltativoImpostazioni da cambiare: memory_limit, upload_max_filesize, post_max_size, max_execution_time.

Permesso: hosting:write

PATCH/hosting/{domain}/phpcURL
curl -X PATCH "https://sitelyra.it/api/v1/hosting/example.com/php" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version":"8.4","settings":{"memory_limit":"512M"}}'
202
{
  "data": {
    "queued": true
  }
}
GET

Elenco dei cron

/hosting/{domain}/cron

Restituisce i cron del sito, con la frequenza nei cinque campi di crontab e il comando.

Solo per i piani che includono i cron.

Errori specifici

StatoCodiceDescrizione
409cron_not_in_planIl piano non include i cron.
409site_not_activeIl sito non è attivo (in creazione, sospeso o non riuscito).
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: hosting:read

GET/hosting/{domain}/croncURL
curl "https://sitelyra.it/api/v1/hosting/example.com/cron" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "id": "a1b2c3d4",
      "minute": "*/15",
      "hour": "*",
      "day": "*",
      "month": "*",
      "weekday": "*",
      "command": "php cron.php"
    }
  ]
}
POST

Aggiungere un cron

/hosting/{domain}/cron

Aggiunge un cron al sito: al massimo 20, non più spesso di una volta ogni 5 minuti.

La modifica si mette in coda sul server e si applica in pochi secondi, una alla volta per sito: la risposta è 202 con queued: true.

Errori specifici

StatoCodiceDescrizione
422invalid_fieldsUn campo manca o non è valido: error.details.fields dice quale.
409cron_limitIl sito ha già 20 cron.
409cron_scheduleLa frequenza non è valida.
409cron_too_oftenPiù spesso di una volta ogni 5 minuti.
409cron_commandIl comando è vuoto, supera i 1000 caratteri o contiene % o un a capo.
409cron_plan_missingIl piano non include i cron.
409not_activeIl sito non è attivo.
409busyC'è già una modifica in corso sul sito, oppure hai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
minutetestoobbligatorioMinuto (0-59), come in crontab: 0, */15, 0,30, 10-20…; le stesse forme valgono per gli altri quattro campi (solo cifre e * , - /, fino a 120 caratteri).
hourtestoobbligatorioOra (0-23) o *.
daytestoobbligatorioGiorno del mese (1-31) o *.
monthtestoobbligatorioMese (1-12) o *.
weekdaytestoobbligatorioGiorno della settimana (0-7, 0 e 7 = domenica) o *.
commandtestoobbligatorioComando su una riga (fino a 1000 caratteri, senza %), eseguito nella cartella www del sito: per esempio php cron.php.

Permesso: hosting:write

POST/hosting/{domain}/croncURL
curl -X POST "https://sitelyra.it/api/v1/hosting/example.com/cron" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"minute":"0","hour":"3","day":"*","month":"*","weekday":"*","command":"php cron.php"}'
202
{
  "data": {
    "queued": true
  }
}
PUT

Modificare un cron

/hosting/{domain}/cron/{id}

Riscrive frequenza e comando di un cron.

La modifica si mette in coda sul server e si applica in pochi secondi, una alla volta per sito: la risposta è 202 con queued: true.

Errori specifici

StatoCodiceDescrizione
422invalid_fieldsUn campo manca o non è valido: error.details.fields dice quale.
404not_foundIl cron non c'è.
409cron_scheduleLa frequenza non è valida.
409cron_too_oftenPiù spesso di una volta ogni 5 minuti.
409cron_commandIl comando è vuoto, supera i 1000 caratteri o contiene % o un a capo.
409cron_plan_missingIl piano non include i cron.
409not_activeIl sito non è attivo.
409busyC'è già una modifica in corso sul sito, oppure hai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
idtestoobbligatorioId del cron, dall'elenco dei cron.

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
minutetestoobbligatorioMinuto (0-59), come in crontab: 0, */15, 0,30, 10-20…; le stesse forme valgono per gli altri quattro campi (solo cifre e * , - /, fino a 120 caratteri).
hourtestoobbligatorioOra (0-23) o *.
daytestoobbligatorioGiorno del mese (1-31) o *.
monthtestoobbligatorioMese (1-12) o *.
weekdaytestoobbligatorioGiorno della settimana (0-7, 0 e 7 = domenica) o *.
commandtestoobbligatorioComando su una riga (fino a 1000 caratteri, senza %), eseguito nella cartella www del sito: per esempio php cron.php.

Permesso: hosting:write

PUT/hosting/{domain}/cron/{id}cURL
curl -X PUT "https://sitelyra.it/api/v1/hosting/example.com/cron/a1b2c3d4" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"minute":"30","hour":"4","day":"*","month":"*","weekday":"1","command":"php report.php"}'
202
{
  "data": {
    "queued": true
  }
}
DELETE

Eliminare un cron

/hosting/{domain}/cron/{id}

Elimina un cron dal sito.

La modifica si mette in coda sul server e si applica in pochi secondi, una alla volta per sito: la risposta è 202 con queued: true.

Errori specifici

StatoCodiceDescrizione
404not_foundIl cron non c'è.
409cron_plan_missingIl piano non include i cron.
409not_activeIl sito non è attivo.
409busyC'è già una modifica in corso sul sito, oppure hai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
idtestoobbligatorioId del cron, dall'elenco dei cron.

Permesso: hosting:write

DELETE/hosting/{domain}/cron/{id}cURL
curl -X DELETE "https://sitelyra.it/api/v1/hosting/example.com/cron/a1b2c3d4" \
  -H "Authorization: Bearer $API_KEY"
202
{
  "data": {
    "queued": true
  }
}
GET

File trovati dall'anti-malware

/hosting/{domain}/malware

Restituisce i file trovati dalle scansioni anti-malware del sito, dal più recente (al massimo 500): in quarantena (quarantined) o ripristinati (restored).

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: hosting:read

GET/hosting/{domain}/malwarecURL
curl "https://sitelyra.it/api/v1/hosting/example.com/malware" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "id": "cm3mal0000001qz8f1a2b3c4d",
      "path": "www/wp-content/uploads/x.php",
      "signature": "{HEX}php.cmdshell.1",
      "status": "quarantined",
      "detectedAt": "2026-11-06T03:10:00.000Z",
      "restoredAt": null
    }
  ]
}
POST

Avviare una scansione

/hosting/{domain}/malware/scan

Avvia subito una scansione completa del sito. I risultati arrivano in File trovati dall'anti-malware entro un'ora.

Errori specifici

StatoCodiceDescrizione
409scan_busyIl sito è già in coda o in scansione.
409busyHai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: hosting:write

POST/hosting/{domain}/malware/scancURL
curl -X POST "https://sitelyra.it/api/v1/hosting/example.com/malware/scan" \
  -H "Authorization: Bearer $API_KEY"
202
{
  "data": {
    "queued": true
  }
}
POST

Ripristinare un file dalla quarantena

/hosting/{domain}/malware/{id}/restore

Riporta nel sito un file in quarantena, se è un falso positivo.

Errori specifici

StatoCodiceDescrizione
404not_foundIl file non c'è o non è in quarantena (per esempio è già stato ripristinato).
409restore_existsNel sito c'è già un file con lo stesso nome.
409busyHai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
idtestoobbligatorioId del file, da File trovati dall'anti-malware.

Permesso: hosting:write

POST/hosting/{domain}/malware/{id}/restorecURL
curl -X POST "https://sitelyra.it/api/v1/hosting/example.com/malware/cm3mal0000001qz8f1a2b3c4d/restore" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "restored": "www/wp-content/uploads/x.php"
  }
}
GET

Stato di WordPress

/hosting/{domain}/wordpress

Restituisce la versione di WordPress, l'aggiornamento disponibile, i plugin, i temi e l'esito dell'ultima azione (se è dell'ultima ora).

Errori specifici

StatoCodiceDescrizione
409site_not_activeIl sito non è attivo (in creazione, sospeso o non riuscito).
503unavailableIl server non risponde (riprova più tardi) oppure WordPress non è installato nel sito.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: hosting:read

GET/hosting/{domain}/wordpresscURL
curl "https://sitelyra.it/api/v1/hosting/example.com/wordpress" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "version": "6.8.3",
    "coreUpdate": null,
    "plugins": [
      {
        "name": "akismet",
        "title": "Akismet Anti-spam",
        "status": "active",
        "version": "5.5",
        "update": false,
        "updateVersion": null,
        "autoUpdate": true
      }
    ],
    "themes": [
      {
        "name": "twentytwentyfive",
        "title": "Twenty Twenty-Five",
        "status": "active",
        "version": "1.3",
        "update": false,
        "updateVersion": null
      }
    ],
    "lastAction": {
      "action": "plugin-update",
      "name": "akismet",
      "ok": true,
      "message": null,
      "at": "2026-11-07T10:05:00.000Z"
    }
  }
}
POST

Installare WordPress

/hosting/{domain}/wordpress/install

Installa WordPress nel sito, se il piano lo include e la cartella del sito è vuota.

La modifica si mette in coda sul server e si applica in pochi secondi, una alla volta per sito: la risposta è 202 con queued: true. La password dell'amministratore di WordPress si vede nel pannello, scheda WordPress del sito: l'API non la restituisce.

Errori specifici

StatoCodiceDescrizione
422invalid_fieldsUn campo manca o non è valido: error.details.fields dice quale.
409plan_missingIl piano non include WordPress.
409already_installedWordPress è già installato.
409not_emptyNella cartella del sito ci sono altri file.
409not_activeIl sito non è attivo.
409busyC'è già una modifica in corso sul sito, oppure hai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
localetestofacoltativoLingua di WordPress: it (predefinita) o en.

Permesso: hosting:write

POST/hosting/{domain}/wordpress/installcURL
curl -X POST "https://sitelyra.it/api/v1/hosting/example.com/wordpress/install" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"locale":"it"}'
202
{
  "data": {
    "queued": true
  }
}
POST

Plugin, temi e aggiornamenti di WordPress

/hosting/{domain}/wordpress/actions

Attiva, aggiorna o elimina plugin e temi, oppure aggiorna WordPress.

Azioni: plugin-activate, plugin-deactivate, plugin-update, plugin-delete, plugin-autoupdate-on, plugin-autoupdate-off, theme-activate, theme-update, theme-delete (con name), plugins-update-all e core-update (senza name). Plugin e tema attivi non si eliminano. La modifica si mette in coda sul server e si applica in pochi secondi, una alla volta per sito: la risposta è 202 con queued: true. L'esito si legge in Stato di WordPress, campo lastAction.

Errori specifici

StatoCodiceDescrizione
422invalid_fieldsUn campo manca o non è valido: error.details.fields dice quale.
422invalidL'azione non esiste, oppure name manca, non è valido o non serve per l'azione.
404not_foundIl plugin o il tema non c'è.
409in_useIl plugin o il tema è attivo e non si elimina.
409not_activeIl sito non è attivo.
409busyC'è già una modifica in corso sul sito, oppure hai fatto più di 60 modifiche all'ora: riprova tra poco.
503unavailableIl server non risponde: riprova più tardi.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
actiontestoobbligatorioAzione dell'elenco qui sopra.
nametestofacoltativoNome del plugin o del tema (campo name di Stato di WordPress): obbligatorio per le azioni su un plugin o un tema, da non mandare con plugins-update-all e core-update.

Permesso: hosting:write

POST/hosting/{domain}/wordpress/actionscURL
curl -X POST "https://sitelyra.it/api/v1/hosting/example.com/wordpress/actions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"plugin-update","name":"akismet"}'
202
{
  "data": {
    "queued": true
  }
}

Email

Domini di posta

Come funziona nel pannello: guida Domini di posta.

GET

Elenco dei domini di posta

/mail

Restituisce i domini con la posta dell'account, in ordine alfabetico, con i limiti del piano e quante caselle e inoltri hanno.

mainDomain è il dominio principale quando il dominio è aggiunto al piano di un altro: in quel caso i limiti sono condivisi.

Nei limiti -1 vuol dire illimitato. counts dice quante caselle e quante righe d'inoltro (una per destinatario) ha il dominio.

Parametri della query

NomeTipoObbligatorioDescrizione
pagenumerofacoltativoPagina, da 1.
per_pagenumerofacoltativoDomini per pagina (predefiniti 100, al massimo 500).

Permesso: mail:read

GET/mailcURL
curl "https://sitelyra.it/api/v1/mail" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "domain": "example.com",
      "domainUnicode": "example.com",
      "active": true,
      "mainDomain": null,
      "limits": {
        "mailboxes": 10,
        "storageMb": 51200,
        "forwards": 100,
        "dailySend": 500
      },
      "counts": {
        "mailboxes": 3,
        "forwards": 2
      }
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 100,
    "total": 1
  }
}
GET

Dettagli di un dominio di posta

/mail/{domain}

Restituisce un dominio di posta con i limiti e quanto è utilizzato: caselle, spazio assegnato in MB e inoltri.

usage.mailboxes e usage.assignedStorageMb sono di tutto il piano, anche quando è condiviso con altri domini. usage.forwards conta le righe d'inoltro di questo dominio (una per destinatario), mentre limits.forwards conta gli indirizzi inoltrati.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: mail:read

GET/mail/{domain}cURL
curl "https://sitelyra.it/api/v1/mail/example.com" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "domain": "example.com",
    "domainUnicode": "example.com",
    "active": true,
    "mainDomain": null,
    "limits": {
      "mailboxes": 10,
      "storageMb": 51200,
      "forwards": 100,
      "dailySend": 500
    },
    "usage": {
      "mailboxes": 3,
      "assignedStorageMb": 15360,
      "forwards": 2
    }
  }
}
GET

Elenco delle caselle

/mail/{domain}/mailboxes

Restituisce le caselle del dominio con spazio, messaggi e ultimo accesso IMAP e POP3. Le password non si leggono mai.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: mail:read

GET/mail/{domain}/mailboxescURL
curl "https://sitelyra.it/api/v1/mail/example.com/mailboxes" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "id": "cm3mbx0000001qz8f1a2b3c4d",
      "address": "info@example.com",
      "displayName": "Info",
      "active": true,
      "quotaMb": 5120,
      "protocols": {
        "imap": true,
        "pop3": true,
        "smtp": true
      },
      "sendCopyTo": null,
      "createdAt": "2026-02-01T09:00:00.000Z",
      "usedBytes": 104857600,
      "messages": 1250,
      "lastLogin": {
        "imap": "2026-11-07T08:30:00.000Z",
        "pop3": null
      }
    }
  ]
}
POST

Creare una casella

/mail/{domain}/mailboxes

Crea una casella email. La password la generiamo noi e si vede solo in questa risposta.

Errori specifici

StatoCodiceDescrizione
422invalid_local_partLa parte prima della @ non è valida.
422invalid_quotaLo spazio non è tra 100 e 102400 MB.
409already_existsL'indirizzo esiste già, come casella o come inoltro.
409mailbox_limitIl piano non ha altre caselle disponibili.
409storage_limitLo spazio chiesto supera quello libero del piano.
409domain_inactiveLa posta del dominio non è attiva.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
localParttestoobbligatorioParte prima della @, per esempio info: da 1 a 64 caratteri tra lettere senza accenti, cifre, ., - e _, con una lettera o una cifra all'inizio e alla fine e senza ... Le maiuscole diventano minuscole.
quotaMbnumeroobbligatorioSpazio della casella in MB, da 100 a 102400 (100 GB), entro lo spazio libero del piano.
displayNametestofacoltativoNome mostrato a chi riceve, per esempio «Info» (al massimo 128 caratteri).

Permesso: mail:write

POST/mail/{domain}/mailboxescURL
curl -X POST "https://sitelyra.it/api/v1/mail/example.com/mailboxes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"localPart":"info","quotaMb":5120,"displayName":"Info"}'
200
{
  "data": {
    "id": "cm3mbx0000001qz8f1a2b3c4d",
    "address": "info@example.com",
    "displayName": "Info",
    "active": true,
    "quotaMb": 5120,
    "protocols": {
      "imap": true,
      "pop3": true,
      "smtp": true
    },
    "sendCopyTo": null,
    "createdAt": "2026-02-01T09:00:00.000Z",
    "password": "Kp4mW8tQ2xRz7nVs"
  }
}
GET

Dettagli di una casella

/mail/{domain}/mailboxes/{id}

Restituisce le impostazioni di una casella: nome, spazio, stato, protocolli ammessi e copia dei messaggi inviati.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
idtestoobbligatorioId della casella, dall'elenco delle caselle.

Permesso: mail:read

GET/mail/{domain}/mailboxes/{id}cURL
curl "https://sitelyra.it/api/v1/mail/example.com/mailboxes/cm3mbx0000001qz8f1a2b3c4d" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "id": "cm3mbx0000001qz8f1a2b3c4d",
    "address": "info@example.com",
    "displayName": "Info",
    "active": true,
    "quotaMb": 5120,
    "protocols": {
      "imap": true,
      "pop3": true,
      "smtp": true
    },
    "sendCopyTo": null,
    "createdAt": "2026-02-01T09:00:00.000Z"
  }
}
PATCH

Modificare una casella

/mail/{domain}/mailboxes/{id}

Cambia le impostazioni di una casella. I campi che non mandi restano come sono.

Errori specifici

StatoCodiceDescrizione
422invalid_quotaLo spazio non è tra 100 e 102400 MB.
422invalid_addressL'indirizzo per la copia non è valido.
409storage_limitLo spazio chiesto supera quello libero del piano.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
idtestoobbligatorioId della casella, dall'elenco delle caselle.

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
displayNametestofacoltativoNome mostrato a chi riceve (al massimo 128 caratteri); null per toglierlo.
quotaMbnumerofacoltativoSpazio della casella in MB, da 100 a 102400 (100 GB), entro lo spazio libero del piano.
activevero/falsofacoltativofalse sospende la casella: non riceve e non si accede.
protocolsoggettofacoltativoProtocolli ammessi: imap, pop3, smtp (true o false).
sendCopyTotestofacoltativoIndirizzo che riceve una copia di ogni messaggio inviato; null per toglierlo.

Permesso: mail:write

PATCH/mail/{domain}/mailboxes/{id}cURL
curl -X PATCH "https://sitelyra.it/api/v1/mail/example.com/mailboxes/cm3mbx0000001qz8f1a2b3c4d" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"quotaMb":10240,"protocols":{"pop3":false}}'
200
{
  "data": {
    "id": "cm3mbx0000001qz8f1a2b3c4d",
    "address": "info@example.com",
    "displayName": "Info",
    "active": true,
    "quotaMb": 10240,
    "protocols": {
      "imap": true,
      "pop3": false,
      "smtp": true
    },
    "sendCopyTo": null,
    "createdAt": "2026-02-01T09:00:00.000Z"
  }
}
DELETE

Eliminare una casella

/mail/{domain}/mailboxes/{id}

Elimina una casella con tutti i suoi messaggi.

L'eliminazione non si può annullare.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
idtestoobbligatorioId della casella, dall'elenco delle caselle.

Permesso: mail:write

DELETE/mail/{domain}/mailboxes/{id}cURL
curl -X DELETE "https://sitelyra.it/api/v1/mail/example.com/mailboxes/cm3mbx0000001qz8f1a2b3c4d" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "deleted": true
  }
}
POST

Nuova password della casella

/mail/{domain}/mailboxes/{id}/password

Genera una nuova password per la casella. La vecchia smette subito di funzionare; la nuova si vede solo in questa risposta.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
idtestoobbligatorioId della casella, dall'elenco delle caselle.

Permesso: mail:write

POST/mail/{domain}/mailboxes/{id}/passwordcURL
curl -X POST "https://sitelyra.it/api/v1/mail/example.com/mailboxes/cm3mbx0000001qz8f1a2b3c4d/password" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "address": "info@example.com",
    "password": "Wq7nT3kP9mRz2xVs"
  }
}
GET

Elenco degli inoltri

/mail/{domain}/forwards

Restituisce gli inoltri del dominio: una riga per ogni destinatario, come nel pannello.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Permesso: mail:read

GET/mail/{domain}/forwardscURL
curl "https://sitelyra.it/api/v1/mail/example.com/forwards" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "id": "cm3fwd0000001qz8f1a2b3c4d",
      "source": "vendite@example.com",
      "destination": "mario@example.org",
      "active": true
    }
  ]
}
POST

Creare un inoltro

/mail/{domain}/forwards

Inoltra i messaggi di un indirizzo del dominio a uno o più destinatari. Restituisce le righe dell'indirizzo.

Se l'indirizzo ha già un inoltro, i destinatari nuovi si aggiungono a quelli che ci sono e la risposta contiene tutte le righe dell'indirizzo.

Errori specifici

StatoCodiceDescrizione
422invalid_local_partLa parte prima della @ non è valida.
422invalid_addressUn destinatario non è valido o l'elenco è vuoto.
409forward_loopL'indirizzo inoltrerebbe a sé stesso.
409already_existsL'indirizzo è già una casella.
409forward_limitIl piano non ha altri inoltri disponibili (il limite conta gli indirizzi, non i destinatari).
409domain_inactiveLa posta del dominio non è attiva.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).

Corpo della richiesta

In JSON, con l'intestazione Content-Type: application/json.

NomeTipoObbligatorioDescrizione
localParttestoobbligatorioParte prima della @ dell'indirizzo da inoltrare, per esempio vendite: da 1 a 64 caratteri tra lettere senza accenti, cifre, ., - e _, con una lettera o una cifra all'inizio e alla fine e senza ... Le maiuscole diventano minuscole.
destinationselencoobbligatorioIndirizzi che ricevono i messaggi, almeno uno, anche fuori dal dominio.

Permesso: mail:write

POST/mail/{domain}/forwardscURL
curl -X POST "https://sitelyra.it/api/v1/mail/example.com/forwards" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"localPart":"vendite","destinations":["mario@example.org"]}'
200
{
  "data": [
    {
      "id": "cm3fwd0000001qz8f1a2b3c4d",
      "source": "vendite@example.com",
      "destination": "mario@example.org",
      "active": true
    }
  ]
}
DELETE

Eliminare un inoltro

/mail/{domain}/forwards/{id}

Elimina una riga dell'inoltro, cioè un destinatario. Gli altri destinatari dello stesso indirizzo restano.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
domaintestoobbligatorioNome del dominio, per esempio example.com (anche con gli accenti, come caffè.it).
idtestoobbligatorioId della riga, dall'elenco degli inoltri.

Permesso: mail:write

DELETE/mail/{domain}/forwards/{id}cURL
curl -X DELETE "https://sitelyra.it/api/v1/mail/example.com/forwards/cm3fwd0000001qz8f1a2b3c4d" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "deleted": true
  }
}

Fatturazione

Ordini

Come funziona nel pannello: guida Ordini.

GET

Elenco degli ordini

/billing/orders

Restituisce gli ordini dell'account dal più recente, con le righe e la proforma.

Serve il permesso «Fatturazione» e un ruolo che veda la fatturazione nel pannello (proprietario o amministratore, non limitato ad alcuni domini). Gli importi sono in centesimi di euro. Stati: pending_payment, paid, processing, completed, partial, failed, cancelled. Tipo dell'ordine (kind): purchase (acquisto) o topup (ricarica del credito). Pagamento (paymentMethod): stripe (carta o PayPal), bank_transfer (bonifico), credit (credito prepagato) o free (ordine gratuito, senza proforma: proforma è null). Tipi delle righe: domain_register, domain_transfer, domain_renew, hosting, hosting_renew, email, mail_pack, mail_storage, mail_renew, credit_topup; stato delle righe: pending, done, failed.

Parametri della query

NomeTipoObbligatorioDescrizione
statustestofacoltativoSolo gli ordini con questi stati, separati da virgola (per esempio pending_payment,processing); gli stati sconosciuti si ignorano e senza stati validi arrivano tutti gli ordini.
pagenumerofacoltativoPagina, da 1.
per_pagenumerofacoltativoOrdini per pagina (predefiniti 100, al massimo 500).

Permesso: billing:read

GET/billing/orderscURL
curl "https://sitelyra.it/api/v1/billing/orders?status=completed" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "number": "DLC-2026-000123",
      "kind": "purchase",
      "status": "completed",
      "paymentMethod": "credit",
      "currency": "EUR",
      "subtotalCents": 1500,
      "discountCents": 0,
      "vatPercent": 22,
      "vatCents": 330,
      "totalCents": 1830,
      "couponCode": null,
      "proforma": {
        "number": "PF-2026-000098",
        "issuedAt": "2026-11-02T09:58:00.000Z"
      },
      "createdAt": "2026-11-02T09:58:00.000Z",
      "paidAt": "2026-11-02T10:00:00.000Z",
      "expiresAt": null,
      "cancelledAt": null,
      "items": [
        {
          "type": "domain_register",
          "domain": "example.com",
          "years": 1,
          "quantity": 1,
          "priceCents": 1500,
          "status": "done"
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 100,
    "total": 1
  }
}
GET

Dettagli di un ordine

/billing/orders/{number}

Restituisce un ordine dal suo numero, con le righe e la proforma.

Serve il permesso «Fatturazione» e un ruolo che veda la fatturazione nel pannello (proprietario o amministratore, non limitato ad alcuni domini). Gli importi sono in centesimi di euro; i campi sono quelli dell'elenco degli ordini.

Parametri nell'indirizzo

NomeTipoObbligatorioDescrizione
numbertestoobbligatorioNumero dell'ordine, per esempio DLC-2026-000123 (anche in minuscolo). Un numero in un altro formato dà 404.

Permesso: billing:read

GET/billing/orders/{number}cURL
curl "https://sitelyra.it/api/v1/billing/orders/DLC-2026-000123" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "number": "DLC-2026-000123",
    "kind": "purchase",
    "status": "completed",
    "paymentMethod": "credit",
    "currency": "EUR",
    "subtotalCents": 1500,
    "discountCents": 0,
    "vatPercent": 22,
    "vatCents": 330,
    "totalCents": 1830,
    "couponCode": null,
    "proforma": {
      "number": "PF-2026-000098",
      "issuedAt": "2026-11-02T09:58:00.000Z"
    },
    "createdAt": "2026-11-02T09:58:00.000Z",
    "paidAt": "2026-11-02T10:00:00.000Z",
    "expiresAt": null,
    "cancelledAt": null,
    "items": [
      {
        "type": "domain_register",
        "domain": "example.com",
        "years": 1,
        "quantity": 1,
        "priceCents": 1500,
        "status": "done"
      }
    ]
  }
}

Fatturazione

Credito prepagato

Come funziona nel pannello: guida Credito prepagato.

GET

Saldo del credito

/billing/credit

Restituisce il saldo del credito prepagato dell'account. Se l'account non ha mai avuto credito, balanceCents è 0 e updatedAt è null.

Serve il permesso «Fatturazione» e un ruolo che veda la fatturazione nel pannello (proprietario o amministratore, non limitato ad alcuni domini). Gli importi sono in centesimi di euro.

Permesso: billing:read

GET/billing/creditcURL
curl "https://sitelyra.it/api/v1/billing/credit" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": {
    "currency": "EUR",
    "balanceCents": 5000,
    "updatedAt": "2026-11-02T10:00:00.000Z"
  }
}
GET

Movimenti del credito

/billing/credit/transactions

Restituisce i movimenti del credito dal più recente: accrediti positivi, addebiti negativi, con il saldo dopo ogni movimento.

Serve il permesso «Fatturazione» e un ruolo che veda la fatturazione nel pannello (proprietario o amministratore, non limitato ad alcuni domini). Gli importi sono in centesimi di euro. Tipi: topup (ricarica), order (pagamento di un ordine), refund (rimborso), manual (rettifica).

Parametri della query

NomeTipoObbligatorioDescrizione
pagenumerofacoltativoPagina, da 1.
per_pagenumerofacoltativoMovimenti per pagina (predefiniti 100, al massimo 500).

Permesso: billing:read

GET/billing/credit/transactionscURL
curl "https://sitelyra.it/api/v1/billing/credit/transactions" \
  -H "Authorization: Bearer $API_KEY"
200
{
  "data": [
    {
      "type": "order",
      "amountCents": -1830,
      "balanceAfterCents": 5000,
      "order": "DLC-2026-000123",
      "note": null,
      "createdAt": "2026-11-02T10:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 100,
    "total": 1
  }
}