SeoAuto.ai

Riferimento API

Riferimento completo per l'API REST AutoSEO. Tutti gli endpoint richiedono un token Bearer valido salvo diversa indicazione. URL base: https://panel.seoauto.ai

Panoramica

L'API di automazione PSEO di AutoSEO consente di creare siti web (PSEO) in modo programmatico, attivare la generazione di contenuti basata sull'IA, monitorare i lavori di generazione e gestire la pipeline di contenuti. Tutti gli endpoint si trovano sotto il prefisso di percorso /pseo-endpoints, montato sul backend Directus.

URL base

https://panel.seoauto.ai

Autenticazione

Bearer Token (JWT)

Formato

JSON (REST)

Autenticazione

Tutte le chiamate API (eccetto il controllo di integrità) richiedono un token utente Directus passato come intestazione Bearer. Ottieni un token di accesso di breve durata effettuando il login, oppure usa un token statico di lunga durata generato dalla tua dashboard.

Opzione 1 — Login (JWT di breve durata)

POSThttps://panel.seoauto.ai/auth/login
json — request body
{
  "email": "you@example.com",
  "password": "••••••••"
}
json — response
{
  "data": {
    "access_token": "eyJhbGciO...",
    "expires": 3600000,
    "refresh_token": "..."
  }
}

Opzione 2 — Token statico (dashboard)

Vai su Dashboard → Chiave API e genera un token statico permanente. Usalo direttamente come valore Bearer — nessuna scadenza da monitorare.

Utilizzo del token

http header
Authorization: Bearer <your_access_token>

Controllo integrità

GEThttps://panel.seoauto.ai/pseo-endpoints/

Restituisce lo stato dell'estensione e un elenco degli endpoint disponibili. Nessuna autenticazione richiesta.

json — response 200
{
  "status": "ok",
  "extension": "pseo-automation",
  "version": "1.0.0",
  "timestamp": "2026-03-10T12:00:00.000Z",
  "endpoints": [
    "GET /",
    "POST /pseo",
    "POST /trigger/on-demand-generation",
    "POST /trigger/bulk-generation",
    "GET /generations/:id",
    "GET /generations?pseo_id=X",
    "POST /generate/main-json",
    "GET /fetch-sitemap?pseo_id=X"
  ]
}

Crea sito web

POSThttps://panel.seoauto.ai/pseo-endpoints/pseo

Crea una nuova voce PSEO (sito web) per l'utente autenticato. Il record PSEO è l'entità radice che contiene tutte le impostazioni di generazione dei contenuti per un sito web specifico.

Corpo della richiesta

CampoTipoObbligatorioDescrizione
website_urlstringobbligatorioURL completo del sito web di destinazione (es. https://example.com)
master_promptstringobbligatorioIstruzioni che guidano l'IA nella generazione di contenuti per questo sito web
website_softwarestringfacoltativoIdentificatore CMS/piattaforma. Predefinito "wordpress"
json — request body
{
  "website_url": "https://example.com",
  "website_software": "wordpress",
  "master_prompt": "This website sells handmade leather bags targeting fashion-conscious adults in the US. Write SEO-friendly product content in English using a professional yet warm tone."
}
json — response 201
{
  "success": true,
  "message": "PSEO created successfully",
  "data": {
    "id": 42,
    "website_url": "https://example.com",
    "website_software": "wordpress",
    "directus_user_id": "uuid-...",
    "post_counts_total": 0
  },
  "timestamp": "2026-03-10T12:00:00.000Z"
}

Avvia generazione (Test)

POSThttps://panel.seoauto.ai/pseo-endpoints/trigger/on-demand-generation

Avvia un processo di generazione di contenuti IA su richiesta per un PSEO. Limitato a 1 pagina (modalità test). Il processo viene eseguito in modo asincrono in background. I token vengono dedotti immediatamente alla velocità token_per_page.

Modalità test — max 1 pagina

La generazione on-demand è limitata a 1 pagina ed è pensata per testare la configurazione. Per generare più pagine, usa l'endpoint di Generazione massiva con Claude Batch API.

Corpo della richiesta

CampoTipoObbligatorioDescrizione
pseo_idnumberobbligatorioID del PSEO (sito web) per cui generare contenuti
post_countnumberobbligatorioNumero di pagine da generare. Deve essere 1 (limite di test)
json — request body
{
  "pseo_id": 42,
  "post_count": 1
}
json — response 202
{
  "success": true,
  "message": "Generation started in background",
  "generation_id": 7,
  "status": "pending",
  "timestamp": "2026-03-10T12:00:00.000Z"
}

Limite di generazione simultanea

È consentita solo una generazione attiva per PSEO alla volta. Se esiste già un lavoro con stato in attesa o in esecuzione, la richiesta restituirà 409 Conflict.

Generazione in blocco

POSThttps://panel.seoauto.ai/pseo-endpoints/trigger/bulk-generation

Avvia un processo di generazione massiva di contenuti IA tramite Claude Batch API. Supporta qualsiasi numero di pagine. I token vengono dedotti alla velocità token_per_batch_page.

Corpo della richiesta

CampoTipoObbligatorioDescrizione
pseo_idnumberobbligatorioID del PSEO (sito web) per cui generare contenuti
post_countnumberobbligatorioNumero di pagine da generare (intero positivo, senza limite superiore)
json — request body
{
  "pseo_id": 42,
  "post_count": 100
}
json — response 202
{
  "success": true,
  "message": "Bulk generation started in background",
  "generation_id": 12,
  "status": "pending",
  "timestamp": "2026-03-10T12:00:00.000Z"
}

Limite di generazione simultanea

È consentita solo una generazione attiva per PSEO alla volta. Se esiste già un lavoro con stato in attesa o in esecuzione, la richiesta restituirà 409 Conflict.

Ottieni generazione

GEThttps://panel.seoauto.ai/pseo-endpoints/generations/:id

Restituisce il record di stato completo per un singolo lavoro di generazione. Interroga questo endpoint dopo aver avviato una generazione per monitorare i progressi.

Parametri del percorso

CampoTipoObbligatorioDescrizione
idnumberobbligatorioIl generation_id restituito dall'endpoint di avvio della generazione
json — response 200
{
  "success": true,
  "data": {
    "id": 7,
    "pseo_id": 42,
    "status": "running",        // pending | running | completed | failed
    "requested_count": 10,
    "created_count": 4,
    "failed_count": 0,
    "failed_routes": [],
    "date_created": "2026-03-10T12:00:00.000Z",
    "date_updated": "2026-03-10T12:01:30.000Z",
    "date_completed": null
  },
  "timestamp": "2026-03-10T12:01:35.000Z"
}
StatoSignificato
pendingLavoro in coda, non ancora avviato
runningL'IA sta generando pagine attivamente
completedTutte le pagine generate con successo
failedLavoro interrotto a causa di un errore critico; controllare failed_routes

Elenca generazioni

GEThttps://panel.seoauto.ai/pseo-endpoints/generations?pseo_id=:pseo_id

Restituisce un elenco degli ultimi 50 lavori di generazione per un determinato PSEO, ordinati dal più recente. Restituisce solo i lavori dell'utente autenticato.

Parametri di query

CampoTipoObbligatorioDescrizione
pseo_idnumberobbligatorioL'ID del PSEO (sito web) per cui elencare le generazioni
http — example request
GET https://panel.seoauto.ai/pseo-endpoints/generations?pseo_id=42
Authorization: Bearer <token>
json — response 200
{
  "success": true,
  "data": [
    {
      "id": 8,
      "pseo_id": 42,
      "status": "completed",
      "requested_count": 5,
      "created_count": 5,
      "failed_count": 0,
      "failed_routes": [],
      "date_created": "2026-03-10T13:00:00.000Z",
      "date_completed": "2026-03-10T13:04:21.000Z"
    },
    { "id": 7, "status": "completed", "..." : "..." }
  ],
  "timestamp": "2026-03-10T14:00:00.000Z"
}

Genera sitemap

POSThttps://panel.seoauto.ai/pseo-endpoints/generate/main-json

Utilizza l'IA per generare un piano di contenuti strutturato (main_json) per il PSEO — essenzialmente un elenco di percorsi di pagina, titoli e metadati che verrà utilizzato come modello per la generazione di contenuti. I token vengono dedotti alla velocità token_per_main_json.

Corpo della richiesta

CampoTipoObbligatorioDescrizione
pseo_idnumberobbligatorioID del PSEO di destinazione
language_codestringobbligatorioLingua per il piano dei contenuti, es. en-US, tr-TR, de-DE
descriptionstringobbligatorioDescrizione aziendale (150–1000 caratteri). Deve coprire settore, servizi, pubblico target e obiettivi.
json — request body
{
  "pseo_id": 42,
  "language_code": "en-US",
  "description": "We sell premium handmade leather goods including bags, wallets, and belts targeting fashion-conscious adults aged 25–45 in the United States. Our USP is ethically sourced full-grain leather with lifetime repair guarantee."
}
json — response 200
{
  "success": true,
  "message": "main_json generated and saved successfully",
  "data": {
    "main_json": {
      "pages": [
        { "route": "/leather-bags", "title": "Premium Leather Bags", "priority": 1 },
        { "route": "/leather-wallets", "title": "Handmade Leather Wallets", "priority": 2 }
      ]
    },
    "total_pages": 28
  },
  "timestamp": "2026-03-10T12:00:00.000Z"
}

Limite di generazione simultanea

È possibile eseguire solo una generazione main_json per utente alla volta. Le richieste simultanee restituiscono 409 Conflict.

Recupera sitemap

GEThttps://panel.seoauto.ai/pseo-endpoints/fetch-sitemap?pseo_id=:pseo_id

Recupera e analizza la sitemap del sito web associato a un PSEO. Tenta automaticamente più percorsi comuni di sitemap (compresi gli indici della sitemap). Restituisce un elenco piatto di tutti gli URL delle pagine trovate. Utile per importare la struttura URL di un sito web esistente.

Parametri di query

CampoTipoObbligatorioDescrizione
pseo_idnumberobbligatorioID PSEO — la sitemap viene recuperata dal website_url memorizzato in questo record

Percorsi della sitemap tentati (in ordine): /sitemap.xml → /sitemap_index.xml → /wp-sitemap.xml → /sitemap

http — example request
GET https://panel.seoauto.ai/pseo-endpoints/fetch-sitemap?pseo_id=42
Authorization: Bearer <token>
json — response 200
{
  "success": true,
  "urls": [
    "https://example.com/",
    "https://example.com/leather-bags",
    "https://example.com/leather-wallets",
    "https://example.com/about"
  ]
}

Restituisce un array urls vuoto se non viene trovata alcuna sitemap o il sito non e raggiungibile. Non genera un errore.

Codici di errore

Tutte le risposte di errore seguono la stessa struttura:

json — error shape
{
  "success": false,
  "error": "Human-readable error message",
  "timestamp": "2026-03-10T12:00:00.000Z"
}
StatoSignificato
400Bad RequestParametri di richiesta mancanti o non validi
401UnauthorizedToken Bearer mancante o non valido
402Payment RequiredSaldo token insufficiente per l'operazione richiesta
403ForbiddenL'utente autenticato non è il proprietario della risorsa richiesta
404Not FoundIl record PSEO o di generazione non esiste
409ConflictUn lavoro di generazione simultanea è già attivo
500Internal Server ErrorErrore lato server imprevisto; controllare i log dell'estensione
Riferimento API | SeoAuto.ai | SeoAuto.ai