Documentazione API · v1

La flotta, dal tuo codice

Elenca i siti, applica aggiornamenti, avvia backup e scansioni da script, CI, Zapier o n8n. Una chiave con i permessi che scegli tu e un contratto che non cambia sotto i piedi.

Crea una chiave Vai agli endpoint

I primi cinque minuti

Dalla chiave alla prima risposta

Crea una chiave
In Impostazioni → Chiavi API scegli cosa può fare: solo leggere, o anche aggiornare e fare backup. Il valore si vede una volta sola.
site:readplugin:updatebackup:create
Chiama /me
È la prima chiamata da fare: se risponde, la chiave funziona e il piano include l’API.
Richiesta
```
curl https://tendfolio.com/api/v1/me \
  -H "Authorization: Bearer tendfolio_…"
```
Leggi i siti
Da qui il resto: aggiornamenti, backup, sicurezza, uptime e articoli, sito per sito.
GET /sites · 200
```
{ "items": [
  { "label": "Pasticceria Bianchi",
    "pendingUpdates": 3 }
] }
```

Tutti gli endpoint

Tutti i percorsi sono relativi a https://tendfolio.com/api/v1. Dove compare {siteId} va l'id restituito da GET /sites.

Endpoint	Cosa fa	Scope
Account
GET`/me`	Identità della chiave: organizzazione, piano, scope concessi. È l'endpoint da chiamare per primo quando si integra qualcosa — se risponde, chiave e piano sono a posto.	qualsiasi chiave
Siti
GET`/sites`	Elenco dei siti accessibili alla chiave, con stato di connessione, versioni e aggiornamenti in sospeso.	site:read
GET`/sites/{siteId}`	Come sopra per un singolo sito, più gli elenchi completi di plugin e temi.	site:read
Aggiornamenti
GET`/sites/{siteId}/updates`	Solo ciò che ha un aggiornamento disponibile: plugin, temi e core.	site:read
POST`/sites/{siteId}/updates`	Accoda aggiornamenti. La risposta è immediata: il lavoro prosegue nel worker e compare nel log attività del sito, attribuito al membro che ha creato la chiave.	plugin:update
Sicurezza
GET`/sites/{siteId}/security`	Ultima scansione e problemi ancora aperti — né risolti né ignorati.	security:read
POST`/sites/{siteId}/security/scan`	Accoda una scansione di sicurezza.	security:scan
Backup
GET`/sites/{siteId}/backups`	Ultimi 50 backup, solo metadati.	site:read
POST`/sites/{siteId}/backups`	Avvia un backup manuale.	backup:create
Uptime
GET`/sites/{siteId}/uptime`	Stato del monitoraggio e incidente aperto, se c'è.	site:read
Articoli
POST`/sites/{siteId}/articles`	Genera un articolo con l'AI e lo deposita sul sito come bozza, pubblicato o programmato. Se ometti topicPrompt, l'argomento lo sceglie il sistema a partire dalle categorie e dagli articoli già pubblicati, evitando i doppioni.	content:manage + ai:run
PATCH`/sites/{siteId}/articles/{articleId}/status`	Pubblica, riporta in bozza o programma un articolo già generato	content:manage
GET`/sites/{siteId}/articles`	Ultimi 50 articoli generati per il sito, senza il corpo del testo.	site:read
GET`/sites/{siteId}/articles/{articleId}`	Il singolo articolo con il testo completo e l'avanzamento della generazione.	site:read

Scope per chiave

Ogni chiave fa solo quello che le concedi: una chiave di sola lettura non può aggiornare niente.

120 richieste al minuto

Per chiave. Oltre arriva 429 con Retry-After: aspetta e riprova.

Errori con un codice

Ogni errore ha un campo code stabile da usare nel codice, oltre al messaggio.

Tutto nel registro

Quello che fai via API compare nel registro attività, a nome di chi ha creato la chiave.

Riferimento completo

API Tendfolio

Introduzione

Superficie REST versionata per far parlare Tendfolio con gli strumenti che già usi: dashboard di agenzia, CI, script di manutenzione, Zapier o n8n. Legge lo stato della flotta e comanda le operazioni principali senza passare dal pannello.

Il contratto è stabile: una modifica che rompe i client esistenti non viene applicata a v1, va su una versione nuova.

Base URL

https://tendfolio.com/api/v1

Autenticazione

Ogni richiesta porta la chiave in un header Authorization. Le chiavi si creano da Impostazioni → Chiavi API: serve il permesso org:manage (ruolo OWNER o ADMIN) e un piano che includa l'API pubblica.

Richiesta

curl -H "Authorization: Bearer tendfolio_a1b2c3d4e5f6_…" \
  https://tendfolio.com/api/v1/me

Il valore in chiaro è mostrato una sola volta, alla creazione: a riposo conserviamo solo un hash SHA-256, quindi non è recuperabile nemmeno da noi. Per ruotare una chiave se ne crea una nuova, si aggiorna l'integrazione e si revoca la vecchia.

Modello di autorizzazione

Una chiave agisce per conto del membro che l'ha creata. I permessi effettivi sono l'intersezione fra gli scope concessi alla chiave e i permessi che quel membro possiede in quel momento nell'organizzazione. Tre conseguenze pratiche:

una chiave non può mai fare più di chi l'ha creata;
declassare o rimuovere quel membro disattiva le sue chiavi all'istante, senza doverle revocare a mano;
lo scoping per-sito è ereditato: se il creatore vede 3 siti su 50, la chiave ne vede 3.

Una chiave non eredita mai i privilegi di amministratore di piattaforma, anche se il creatore li possiede.

Scope

Ogni chiave porta gli scope scelti alla creazione. Le rotte dichiarano quello che richiedono: senza, la risposta è 403 MISSING_SCOPE.

Scope	Consente
site:read	Leggere i siti e il loro stato
site:create	Aggiungere siti
site:update	Modificare i siti
plugin:update	Aggiornare plugin e temi
core:update	Aggiornare WordPress (core)
plugin:manage	Attivare / disattivare plugin
security:read	Leggere i risultati di sicurezza
security:scan	Avviare scansioni
backup:create	Creare backup
backup:download	Scaricare backup
ai:read	Leggere i suggerimenti AI
ai:run	Avviare generazioni AI (consuma crediti)
content:manage	Creare articoli e media sui siti

Restano deliberatamente fuori dall'API pubblica le operazioni che non dovrebbero avvenire senza una persona davanti: eliminazione di un sito, ripristino di un backup (sovrascrive il sito), 1-click login verso wp-admin, gestione del team e fatturazione.

Rate limit

120 richieste al minuto per chiave. Ogni risposta porta lo stato corrente della finestra; superato il limite arriva 429 con Retry-After.

Header di risposta

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1785000060

Errori

Formato uniforme, discriminabile sul campo code: è quello da usare nel codice. Il message è in inglese — l'API parla una lingua sola — ed è pensato per gli sviluppatori, quindi può cambiare.

Errore

{ "code": "MISSING_SCOPE", "message": "Missing scope for this key: backup:create." }

HTTP	code	Significato
`401`	`MISSING_KEY`	Header Authorization assente.
`401`	`MALFORMED_KEY`	La chiave non è nel formato tendfolio_<id>_<secret>.
`401`	`INVALID_KEY`	Chiave inesistente o segreto errato.
`401`	`REVOKED_KEY`	Chiave revocata dal pannello.
`401`	`EXPIRED_KEY`	Chiave oltre la data di scadenza.
`401`	`ORPHANED_KEY`	Il membro che ha creato la chiave non è più nell'organizzazione.
`403`	`FEATURE_NOT_IN_PLAN`	Il piano dell'organizzazione non include l'API pubblica.
`403`	`MISSING_SCOPE`	La chiave non ha lo scope richiesto dalla rotta.
`404`	`SITE_NOT_FOUND`	Sito inesistente oppure fuori dalla portata della chiave.
`429`	`RATE_LIMITED`	Limite di richieste superato. La risposta porta Retry-After.

Su un sito fuori portata la risposta è 404, non 403: un 403 confermerebbe l'esistenza di quell'id a chi non dovrebbe conoscerlo.

Endpoint

Tutti i percorsi sono relativi a https://tendfolio.com/api/v1. Dove compare {siteId} va l'id restituito da GET /sites.

GET/mequalsiasi chiave

Identità della chiave: organizzazione, piano, scope concessi. È l'endpoint da chiamare per primo quando si integra qualcosa — se risponde, chiave e piano sono a posto.

Risposta

{
  "organization": { "id": "clx…" },
  "plan": { "id": "clx…", "name": "Agency", "slug": "agency" },
  "key": { "id": "clx…", "name": "Integrazione monitoraggio", "scopes": ["site:read"] },
  "siteCount": 42
}

siteCount è il numero di siti visibili a questa chiave, non il totale dell'organizzazione: se chi l'ha creata vede 3 siti su 50, vale 3.

GET/sitessite:read

Elenco dei siti accessibili alla chiave, con stato di connessione, versioni e aggiornamenti in sospeso.

Risposta

{
  "items": [
    {
      "id": "clx…",
      "url": "https://esempio.it",
      "label": "Esempio",
      "status": "CONNECTED",
      "tags": ["cliente-a"],
      "wpVersion": "6.8.1",
      "phpVersion": "8.3",
      "multisite": false,
      "maintenanceMode": false,
      "uptimeStatus": "UP",
      "lastSeenAt": "2026-08-04T21:10:00.000Z",
      "lastLatencyMs": 187,
      "pendingUpdates": 3,
      "createdAt": "2026-05-02T09:00:00.000Z"
    }
  ]
}

GET/sites/{siteId}site:read

Come sopra per un singolo sito, più gli elenchi completi di plugin e temi.

Risposta

{
  "id": "clx…",
  "url": "https://esempio.it",
  "status": "CONNECTED",
  "plugins": [
    {
      "slug": "woocommerce",
      "name": "WooCommerce",
      "version": "9.1.2",
      "latestVersion": "9.2.0",
      "active": true,
      "updateAvailable": true
    }
  ],
  "themes": [ … ]
}

GET/sites/{siteId}/updatessite:read

Solo ciò che ha un aggiornamento disponibile: plugin, temi e core.

Risposta

{
  "items": [
    {
      "type": "plugin",
      "slug": "woocommerce",
      "name": "WooCommerce",
      "currentVersion": "9.1.2",
      "latestVersion": "9.2.0"
    }
  ]
}

POST/sites/{siteId}/updatesplugin:update

Accoda aggiornamenti. La risposta è immediata: il lavoro prosegue nel worker e compare nel log attività del sito, attribuito al membro che ha creato la chiave.

Corpo della richiesta

{
  "items": [
    { "type": "plugin", "slug": "woocommerce" },
    { "type": "theme", "slug": "storefront" }
  ],
  "backupFirst": true,
  "safeUpdate": true
}

Risposta

{ "ok": true, "queued": 2 }

backupFirst — backup del database prima di aggiornare (richiede la feature backups nel piano).
safeUpdate — verifica il sito prima e dopo, con rollback automatico se si rompe. Implica backupFirst.
Un elemento di tipo core richiede in più lo scope core:update.

GET/sites/{siteId}/securitysecurity:read

Ultima scansione e problemi ancora aperti — né risolti né ignorati.

Risposta

{
  "lastScan": {
    "id": "clx…",
    "status": "DONE",
    "findingsCount": 2,
    "startedAt": "2026-08-03T02:10:00.000Z",
    "finishedAt": "2026-08-03T02:14:00.000Z"
  },
  "findings": [
    {
      "id": "clx…",
      "severity": "HIGH",
      "title": "Vulnerabilità nota in Contact Form 7",
      "cve": "CVE-2026-1234",
      "component": "contact-form-7",
      "affectedVersion": "5.9.1",
      "fixedVersion": "5.9.4",
      "detectedAt": "2026-08-03T02:14:00.000Z"
    }
  ]
}

POST/sites/{siteId}/security/scansecurity:scan

Accoda una scansione di sicurezza.

Risposta

{ "ok": true }

GET/sites/{siteId}/backupssite:read

Ultimi 50 backup, solo metadati.

Risposta

{
  "items": [
    {
      "id": "clx…",
      "type": "DATABASE",
      "status": "DONE",
      "origin": "MANUAL",
      "sizeBytes": "184320512",
      "createdAt": "2026-08-04T03:00:00.000Z"
    }
  ]
}

I token di download non sono mai esposti dall'API pubblica.
sizeBytes è una stringa: un backup può superare i 2^53 byte, oltre i quali un numero JSON perderebbe precisione.

POST/sites/{siteId}/backupsbackup:create

Avvia un backup manuale.

Corpo della richiesta

{ "type": "DATABASE" }

Risposta

{ "ok": true }

type è opzionale: DATABASE (default), FILES o FULL.
Valgono la feature backups del piano, la quota di backup manuali del mese e lo spazio disponibile: se manca qualcosa la risposta è 403 con il code relativo.

POST/sites/{siteId}/articlescontent:manage + ai:run

Genera un articolo con l'AI e lo deposita sul sito come bozza, pubblicato o programmato. Se ometti topicPrompt, l'argomento lo sceglie il sistema a partire dalle categorie e dagli articoli già pubblicati, evitando i doppioni.

Corpo della richiesta

{
  "topicPrompt": "Come scegliere un commercialista per una startup",
  "count": 3,
  "length": "medium",
  "tone": "informative",
  "imageCount": 1,
  "destination": "DRAFT",
  "categories": ["Fisco"],
  "tags": ["startup"]
}

Risposta

{
  "id": "clx…",
  "ids": ["clx…", "cly…", "clz…"],
  "count": 3,
  "requested": 3,
  "status": "QUEUED",
  "credits": 18,
  "createdAt": "2026-08-07T09:12:00.000Z"
}

Asincrona: risponde subito con lo stato QUEUED, la generazione dura uno-due minuti. Si segue con GET sullo stesso id.
Richiede la feature ai_content nel piano e il connettore ≥ 2.20.0 sul sito. I crediti (articolo 1/2/3/5/7 secondo la lunghezza, più 3 per immagine) sono addebitati alla richiesta e rimborsati se la generazione fallisce senza depositare nulla sul sito.
Con count fino a 5 si generano più articoli in una volta: ognuno prende un argomento diverso, e se c'è topicPrompt il primo lo segue alla lettera mentre gli altri ne ricavano tagli distinti. Ogni articolo ha la sua prenotazione di crediti: se finiscono a metà gruppo, count nella risposta è minore di requested.

PATCH/sites/{siteId}/articles/{articleId}/statuscontent:manage

Pubblica, riporta in bozza o programma un articolo già generato

Corpo della richiesta

{
  "destination": "SCHEDULE",
  "scheduledFor": "2026-08-14T07:00:00.000Z"
}

Risposta

{
  "id": "clx…",
  "destination": "SCHEDULE",
  "scheduledFor": "2026-08-14T07:00:00.000Z",
  "wpStatus": "future",
  "wpPostUrl": "https://sito.it/?p=412"
}

Non costa crediti: il pezzo è già stato scritto e pagato. Si scrive prima su WordPress e solo dopo su Tendfolio, così il pannello non dice mai “pubblicato” mentre il sito mostra una bozza. Programmare richiede il connettore ≥ 2.21.0 e una data futura.
Un articolo programmato lo pubblica WordPress, non Tendfolio. WP-Cron però scatta alla prima visita dopo l'orario, quindi su un sito senza traffico può non scattare: ogni dieci minuti Tendfolio controlla chi è rimasto indietro di oltre un quarto d'ora e lo pubblica mantenendo la data prevista. Chi nel frattempo è tornato in bozza non viene toccato.

GET/sites/{siteId}/articlessite:read

Ultimi 50 articoli generati per il sito, senza il corpo del testo.

Risposta

[
  {
    "id": "clx…",
    "status": "READY",
    "title": "Come scegliere un commercialista per una startup",
    "destination": "SCHEDULE",
    "scheduledFor": "2026-08-14T07:00:00.000Z",
    "wordCount": 1180,
    "imageCount": 1,
    "wpPostId": 412,
    "wpPostUrl": "https://sito.it/?p=412",
    "wpStatus": "future",
    "creditsCharged": 6
  }
]

GET/sites/{siteId}/articles/{articleId}site:read

Il singolo articolo con il testo completo e l'avanzamento della generazione.

Risposta

{
  "id": "clx…",
  "status": "RUNNING",
  "topic": "Come scegliere un commercialista per una startup",
  "data": {
    "steps": [
      { "key": "context", "status": "done" },
      { "key": "topic",   "status": "done" },
      { "key": "text",    "status": "running" },
      { "key": "images",  "status": "pending" },
      { "key": "publish", "status": "pending" }
    ]
  }
}

Gli step vanno in ordine: context → topic → text → images → publish. Lo stato passa da QUEUED a RUNNING a READY, oppure FAILED con il campo error valorizzato.

GET/sites/{siteId}/uptimesite:read

Stato del monitoraggio e incidente aperto, se c'è.

Risposta

{
  "siteId": "clx…",
  "monitorEnabled": true,
  "status": "UP",
  "lastPingAt": "2026-08-04T21:11:00.000Z",
  "lastLatencyMs": 187,
  "failCount": 0,
  "openIncident": null
}

Note operative

Server-to-server. Il CORS resta ristretto al dominio del pannello: una chiave non va messa in JavaScript di browser, dove sarebbe leggibile da chiunque apra gli strumenti di sviluppo.
Solo HTTPS.
Tracciabilità. Ogni chiave registra ultimo utilizzo e ultimo IP; creazione e revoca finiscono nell'audit log, e le azioni avviate via API compaiono nel log attività attribuite al membro creatore.

Pronto a integrare?

Crea una chiave dal pannello e verifica l'integrazione con una chiamata a /me.

Crea una chiave Apri un account

La flotta, dal tuo codice

Dalla chiave alla prima risposta

Crea una chiave

Chiama /me

Leggi i siti

Tutti gli endpoint

Scope per chiave

120 richieste al minuto

Errori con un codice

Tutto nel registro

API Tendfolio

Introduzione

Autenticazione

Modello di autorizzazione

Scope

Rate limit

Errori

Endpoint

Note operative

Pronto a integrare?