API rewriter.io

Introduzione

L'URL di base dell'API è https://public-api.rewriter.io/v1. Tutte le risposte vengono restituite in formato JSON (chiavi in stile snake_case) e il corpo dell'articolo è disponibile come markdown e html. Ogni richiesta richiede una chiave API. L'API supporta esclusivamente l'accesso in lettura ai contenuti pubblicati.

Nell'ambiente di test, usa l'indirizzo https://dev-hooks.rewriter.io/v1.

Per gli agenti IA e gli LLM pubblichiamo un indice leggibile dalle macchine di questa documentazione in llms.txt.

Autenticazione

Passa la chiave nell'intestazione Authorization come token Bearer. La chiave è associata a un singolo progetto.

# Verifica a quale progetto appartiene la chiave
curl https://public-api.rewriter.io/v1/me \
  -H "Authorization: Bearer rw_live_3f8a…"

Limiti e versionamento

L'API è versionata nel percorso (/v1). Il limite di richieste dipende dal piano ed è conteggiato separatamente per ogni chiave API.

Le risposte dei piani con limite includono le intestazioni X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Con un piano senza limite le intestazioni X-RateLimit-* non vengono inviate.

• Le richieste GET sono accessibili dal browser (CORS).
• Tutti i timestamp in formato ISO 8601 (UTC).

Errori

Restituiamo gli errori con il codice HTTP appropriato e una struttura uniforme:

{
  "error": {
    "code": "not_found",
    "message": "Article not found."
  }
}

• 400 - parametri di query non validi
• 401 - chiave API mancante o non valida
• 403 - il tuo piano non include l'accesso all'API
• 404 - non trovato (articolo non pubblicato o esterno al progetto)
• 429 - limite di richieste superato
• 500 - errore del server

Paginazione e ordinamento

Restituiamo gli elenchi in un involucro con campi dati e metadati di pagina:

{
  "data": [
    "…"
  ],
  "page": 1,
  "per_page": 10,
  "total": 42
}

Controlli la paginazione con i parametri page (da 1) e limit (predefinito 10, max. 100). Imposti l'ordinamento con il parametro sort - il prefisso “-” indica l'ordine decrescente. Valori consentiti: published_at, -published_at, title, -title, updated_at, -updated_at.

Progetto

Restituisce informazioni sul progetto associato alla chiave e le lingue disponibili. Utile per verificare la chiave.

{
  "id": "k17a9c…",
  "name": "Kawiarnia Pod Lipą",
  "primary_language": "pl",
  "available_languages": [
    "pl",
    "en"
  ],
  "plan": "Pro",
  "rate_limit_per_minute": 300
}

Argomenti

Restituisce l'elenco degli argomenti del progetto. Usa il campo id come valore del filtro topic_id nell'elenco degli articoli.

{
  "data": [
    {
      "id": "j57b2…",
      "title": "Lokalne SEO"
    },
    {
      "id": "j58c1…",
      "title": "Porady baristów"
    }
  ]
}

Categorie

Restituisce l'elenco delle categorie del progetto. Usa il campo id come valore del filtro category_id nell'elenco degli articoli. I nomi seguono il parametro language (predefinito: lingua principale).

{
  "data": [
    {
      "id": "k20a1…",
      "name": "Pielęgnacja ogrodu",
      "slug": "pielegnacja-ogrodu"
    },
    {
      "id": "k20a2…",
      "name": "Porady",
      "slug": "porady"
    }
  ]
}

Elenca articoli

Restituisce un elenco paginato di articoli pubblicati (campi di riepilogo, senza il corpo).

Parametri di query

• topic_id - string, opzionale. Filtra per identificatore dell'argomento.
• category_id - string, opzionale. Filtra per identificatore della categoria.
• language - string, opzionale. Codice lingua; per impostazione predefinita la lingua principale del progetto. Un codice diverso restituisce le traduzioni pubblicate.
• q - string, opzionale. Ricerca per titolo (senza distinzione tra maiuscole e minuscole).
• published_after - data ISO 8601, opzionale. Solo articoli pubblicati a partire da questa data.
• published_before - data ISO 8601, opzionale. Solo articoli pubblicati fino a questa data.
• sort - string, predefinito -published_at. Vedi la sezione Paginazione e ordinamento.
• page - numero, predefinito 1.
• limit - numero, predefinito 10, max. 100.

Ometti semplicemente un parametro che non usi: un valore vuoto (per esempio sort=) viene trattato come un parametro assente.

{
  "data": [
    {
      "id": "m93f7…",
      "title": "10 sposobów na lokalne SEO",
      "slug": "10-sposobow-na-lokalne-seo",
      "language": "pl",
      "topic_id": "j57b2…",
      "category": {
        "id": "k20a1…",
        "name": "Pielęgnacja ogrodu",
        "slug": "pielegnacja-ogrodu"
      },
      "status": "published",
      "seo_score": 96,
      "readability_score": 72,
      "fact_check_status": "passed",
      "cover_image": "https://cdn.example.com/articles/m93f7/cover.png",
      "published_at": "2026-05-21T09:12:00.000Z",
      "updated_at": "2026-05-22T10:00:00.000Z"
    }
  ],
  "page": 1,
  "per_page": 10,
  "total": 42
}

Ottieni articolo

Restituisce il corpo completo di un articolo pubblicato insieme ai metadati SEO. Il corpo è disponibile come Markdown e come frammento HTML. Il parametro :id accetta l'id completo dell'articolo; il blog rewriter.io accetta anche un riferimento slug-8 caratteri.

Parametri di query

• language - string, opzionale. Codice lingua per ottenere una traduzione pubblicata anziché la versione nella lingua principale.
• format - markdown o html, opzionale. Per impostazione predefinita restituiamo entrambi i campi del corpo.

{
  "id": "m93f7…",
  "title": "10 sposobów na lokalne SEO",
  "slug": "10-sposobow-na-lokalne-seo",
  "topic_id": "j57b2…",
  "category": {
    "id": "k20a1…",
    "name": "Pielęgnacja ogrodu",
    "slug": "pielegnacja-ogrodu"
  },
  "language": "pl",
  "status": "published",
  "body_markdown": "## Wstęp\n\nLokalne SEO to…",
  "body_html": "<h2>Wstęp</h2>\n<p>Lokalne SEO to…</p>",
  "cover_image": "https://cdn.example.com/articles/m93f7/cover.png",
  "meta_title": "Lokalne SEO dla kawiarni",
  "meta_description": "Praktyczny przewodnik po lokalnym SEO.",
  "seo_score": 96,
  "readability_score": 72,
  "readability_label": "łatwy",
  "fact_check_status": "passed",
  "uniqueness_score": 98,
  "alternate_slugs": [
    {
      "language": "pl",
      "slug": "10-sposobow-na-lokalne-seo"
    },
    {
      "language": "en",
      "slug": "10-ways-to-improve-local-seo"
    }
  ],
  "json_ld": {
    "@context": "https://schema.org",
    "@type": "BlogPosting",
    "headline": "10 sposobów na lokalne SEO",
    "inLanguage": "pl",
    "wordCount": 1240,
    "…": "…"
  },
  "published_at": "2026-05-21T09:12:00.000Z",
  "updated_at": "2026-05-22T10:00:00.000Z"
}

Articolo in un modello HTML

Restituisce una pagina HTML pronta dell'articolo pubblicato, racchiusa nel modello del progetto (text/html anziché JSON). Supporta il parametro language. Ideale per l'incorporamento diretto in un sito.

curl https://public-api.rewriter.io/v1/articles/m93f7…/html \
  -H "Authorization: Bearer rw_live_3f8a…"

Webhook

I webhook inviano richieste POST firmate al tuo URL quando si verificano eventi di contenuto nel progetto. Configurali nel pannello, nella sezione Account → API e integrazioni.

Puoi registrarli anche via API, con la sola chiave API e senza passare dal pannello. Vedi Sottoscrizioni webhook.

Eventi disponibili

• article.published - un articolo è stato pubblicato.
• article.scheduled - è stata pianificata la pubblicazione di un articolo.
• article.unpublished - è stata annullata la pubblicazione di un articolo.
• article.archived - un articolo è stato archiviato.
• article.restored - un articolo è stato ripristinato dall'archivio.
• article.translated - è stata pubblicata una traduzione di un articolo.
• topic.created - è stato creato un nuovo argomento.
• headline.created - sono stati generati nuovi suggerimenti di articoli (titoli).

Corpo della richiesta

Ogni richiesta contiene un involucro JSON con id (l'identificatore di consegna - usalo per la deduplicazione), event, created_at, project_id e data con i dettagli dell'evento:

{
  "id": "whd_4f2a…",
  "event": "article.published",
  "created_at": "2026-05-21T09:12:00.000Z",
  "project_id": "k17a9c…",
  "data": {
    "id": "m93f7…",
    "title": "10 sposobów na lokalne SEO",
    "slug": "10-sposobow-na-lokalne-seo",
    "language": "pl",
    "status": "published",
    "topic_id": "j57b2…",
    "category": {
      "id": "k20a1…",
      "name": "Pielęgnacja ogrodu",
      "slug": "pielegnacja-ogrodu"
    },
    "seo_score": 96,
    "readability_score": 72,
    "fact_check_status": "passed",
    "published_at": "2026-05-21T09:12:00.000Z",
    "updated_at": "2026-05-21T09:12:00.000Z"
  }
}

Verifica della firma

Ogni richiesta contiene l'intestazione X-Rewriter-Webhook-Signature con una firma HMAC-SHA256 sul timestamp (intestazione X-Rewriter-Webhook-Timestamp), un punto e il corpo della richiesta, nel formato sha256=<hex>. Ricalcolala con il tuo segreto e confrontala in tempo costante.

const ts = req.headers["x-rewriter-webhook-timestamp"];
const sig = req.headers["x-rewriter-webhook-signature"];
const expected = "sha256=" + crypto
  .createHmac("sha256", WEBHOOK_SECRET)
  .update(ts + "." + rawBody)
  .digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));

Tentativi e disattivazione automatica

Le consegne non riuscite vengono ritentate con un intervallo crescente (fino a 5 tentativi), inviando lo stesso identificatore di consegna a ogni tentativo. Dopo molti fallimenti consecutivi il webhook viene disattivato automaticamente: riattivalo nel pannello.

Sottoscrizioni webhook

Puoi registrare e rimuovere i callback dei webhook via API, con la sola chiave API e senza passare dal pannello. Questi endpoint alimentano i trigger istantanei delle nostre app Zapier e Make.com e puoi usarli anche nella tua integrazione.

POST e GET richiedono inoltre un piano che includa i webhook, altrimenti restituiscono 403 forbidden. DELETE è autorizzato dalla sola chiave API, quindi la rimozione di una sottoscrizione continua a funzionare anche dopo un cambio di piano.

Crea una sottoscrizione

Registra un URL di callback per esattamente un evento e restituisce l'oggetto sottoscrizione con stato 201 (senza involucro data). Conserva l'id restituito: lo passi per eliminare la sottoscrizione.

Corpo della richiesta

• target_url - obbligatorio. Un URL di callback HTTPS su uno degli host consentiti.
• event - obbligatorio. Un evento tra quelli elencati sopra.

curl -X POST https://public-api.rewriter.io/v1/webhooks \
  -H "Authorization: Bearer rw_live_3f8a…" \
  -H "Content-Type: application/json" \
  -d '{"target_url":"https://hook.eu2.make.com/abc123","event":"article.published"}'

{
  "id": "n41c8…",
  "event": "article.published",
  "target_url": "https://hook.eu2.make.com/abc123",
  "status": "enabled"
}

Oggetto sottoscrizione

• id - l'identificatore della sottoscrizione: passalo a DELETE.
• event - l'evento per cui la sottoscrizione è registrata.
• target_url - l'URL di callback registrato.
• status - enabled oppure disabled: una sottoscrizione viene disattivata automaticamente dopo ripetute consegne fallite.

Host consentiti per target_url

target_url deve essere un URL di hook HTTPS di una piattaforma di automazione su uno di questi host:

• hooks.zapier.com - URL catch hook di Zapier.
• hook.make.com, hook.<zona>.make.com - webhook di Make.com, per esempio hook.eu2.make.com.

Qualsiasi altro host, un URL non HTTPS, un URL con credenziali o un indirizzo privato, di loopback o di metadati viene rifiutato con 400 bad_request.

Inviare di nuovo la stessa coppia target_url ed event non crea un duplicato: la sottoscrizione esistente viene riattivata e restituita con lo stesso id. Un progetto può avere al massimo 20 sottoscrizioni per piattaforma.

Elenca le sottoscrizioni

Restituisce le sottoscrizioni create con questa chiave API in questo progetto. Le sottoscrizioni create con un'altra chiave e i webhook configurati nel pannello non vengono mai restituiti.

{
  "data": [
    {
      "id": "n41c8…",
      "event": "article.published",
      "target_url": "https://hook.eu2.make.com/abc123",
      "status": "enabled"
    }
  ]
}

Elimina una sottoscrizione

Elimina la sottoscrizione con l'id indicato. È idempotente: un id sconosciuto, già eliminato o di un altro progetto restituisce 200 con deleted: false invece di 404, quindi la pulizia non fallisce mai.

{
  "id": "n41c8…",
  "deleted": true
}

Errori

• 400 bad_request - target_url o event mancante, evento sconosciuto oppure target_url fuori dagli host consentiti.
• 401 unauthorized - chiave API mancante o non valida.
• 403 forbidden - il piano non include i webhook oppure è stato raggiunto il limite di 20 sottoscrizioni.

Queste risposte riportano gli stessi header X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset degli endpoint di lettura.