Ogni articolo che scriviamo per Lei può essere letto via HTTP: il titolo, i metadati, il Markdown, l'HTML, l'immagine hero e le FAQ. Li porti nel Suo sito Next.js, Astro o personalizzato quando la build viene eseguita, li pubblichi e ci comunichi l'indirizzo finale di ciascuno.
Un bearer token. JSON in ingresso, JSON in uscita. Nessun SDK da installare e nulla da configurare oltre a una chiave.
Trasportano lo stesso articolo nello stesso formato, quindi un parser scritto per uno legge anche l'altro senza modifiche. La differenza è chi avvia la conversazione.
Chiamiamo il Suo endpoint nel momento in cui un articolo è pronto, e di nuovo quando cambia. Nulla da interrogare, nulla da pianificare. WordPress, Shopify, Ghost, un trigger Zapier o una route scritta da Lei.
Un sito statico non può accettare un post alle sei e mezza del mattino; prima qualcosa deve essere ricompilato. Quindi la Sua build chiede cosa è in attesa, lo prende e poi ci comunica l'indirizzo. Sceglie Lei quando.
Sono connessioni separate e nessuna esclude l'altra. Un webhook che alimenta una newsletter e un'API che alimenta il sito web è una configurazione normale.
Crei una chiave nella dashboard in Impostazioni, poi Connessioni. Viene mostrata una sola volta, quando viene creata, perché viene memorizzato solo il suo hash: se la perde, la revochi e ne crei un'altra. Una chiave legge ogni sito dell'account e si revoca dalla stessa schermata.
Ogni richiesta
Authorization: Bearer sns_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Accept: application/json
Verifichi che funzioni
curl https://seonis.ai/api/v1/me \ -H "Authorization: Bearer $SEONIS_API_KEY"
{
"organisation": { "id": 12, "name": "Peppervale", "country": "GB" },
"key": {
"name": "Production build",
"prefix": "sns_live_ab",
"created_at": "2026-09-06T09:12:44+00:00",
"last_used_at": "2026-09-06T09:31:02+00:00"
},
"sites": 2
}
Limite di richieste
120 richieste al minuto, conteggiate sulla chiave anziché sull'indirizzo da cui provengono, perché i runner di build condividono gli indirizzi. Oltre questo limite riceverà un 429 con le intestazioni standard Retry-After e X-RateLimit. Recuperare gli articoli per una build richiede una manciata di richieste, quindi non è un limite che dovrebbe raggiungere per errore.
Tenga la chiave fuori dal repository
Legge tutto ciò che abbiamo scritto per il Suo account, compresi gli articoli non ancora pubblicati. La inserisca nell'ambiente di build, non nel codice sorgente. La revochi qui nel momento in cui si trova dove non dovrebbe essere, e tutto ciò che la usa riceverà subito un 401.
Tutto si trova sotto /api/v1/. La versione è nel percorso fin dal primo giorno, così un giorno potrà esistere una v2 senza rompere ciò che scrive oggi.
L'account a cui appartiene la chiave, e il nome e prefisso della chiave stessa. Utile soprattutto per una cosa: dirLe che la chiave in questo ambiente è la chiave che pensa che sia.
Esempio
curl https://seonis.ai/api/v1/me \ -H "Authorization: Bearer $SEONIS_API_KEY"
Ogni sito dell'account. L'id è ciò su cui filtra l'elenco degli articoli, e il dominio è presente così uno script di build può confrontarlo con qualcosa che già conosce invece di portarsi dietro un id.
Esempio
curl https://seonis.ai/api/v1/sites \ -H "Authorization: Bearer $SEONIS_API_KEY"
{
"sites": [
{
"id": 5,
"name": "Peppervale",
"domain": "peppervale.co.uk",
"url": "https://peppervale.co.uk",
"language": "en",
"country": "GB",
"market": "en-GB",
"status": "active",
"articles_published": 34,
"created_at": "2026-06-02T11:04:19+00:00"
}
]
}
Una pagina di articoli, con la modifica più recente per prima, senza il testo. Ordinati in base all'ultima modifica di ciascun articolo anziché a quando è stato scritto, ed è questo che rende utile updated_since: un articolo già pubblicato può essere modificato in seguito, quando vi viene inserito o rimosso un link.
Parametri di query
| Nome | Che cosa fa |
|---|---|
| site_id | Un sito, da /sites. Un id che non appartiene al Suo account risponde con 404. |
| status | Uno tra draft, qa, needs_repair, review, ready, published, failed. Qualsiasi altro valore restituisce un 422 anziché una pagina vuota. "ready" è ciò che una build vuole: scritto, controllato e non ancora pubblicato da nessuna parte. |
| updated_since | ISO 8601, ad esempio 2026-09-06T00:00:00Z. Ricordi il timestamp dell'ultima esecuzione e lo ripassi alla successiva. |
| per_page | Fino a 100. Il valore predefinito è 25. |
| page | Da 1. meta.has_more indica se chiederne un'altra. |
Esempio
curl -G https://seonis.ai/api/v1/articles \ -H "Authorization: Bearer $SEONIS_API_KEY" \ -d site_id=5 \ -d status=ready \ -d updated_since=2026-09-01T00:00:00Z \ -d per_page=50
{
"articles": [
{
"id": 918,
"site_id": 5,
"language": "en",
"status": "ready",
"title": "How to choose a pepper grinder",
"slug": "how-to-choose-a-pepper-grinder",
"meta_title": "How to choose a pepper grinder | Peppervale",
"meta_description": "Burr or blade, ceramic or steel: what matters in a grinder.",
"meta_keywords": ["pepper grinder", "burr grinder"],
"tags": ["Kitchen"],
"excerpt": "A burr grinder gives an even grind; a blade one does not.",
"key_takeaways": ["A burr grinder gives an even grind; a blade one does not."],
"faq": [{ "question": "Ceramic or steel?", "answer": "Steel for pepper, ceramic for salt." }],
"hero_image": { "url": "https://seonis.ai/storage/images/5/918.jpg", "alt": "A pepper grinder" },
"infographic_url": null,
"word_count": 1812,
"published_url": null,
"published_at": null,
"updated_at": "2026-09-06T06:31:12+00:00",
"created_at": "2026-09-05T02:14:55+00:00",
"quality": { "seo_score": 88, "language_score": 96, "language_findings": [] }
}
],
"meta": { "page": 1, "per_page": 50, "total": 1, "last_page": 1, "has_more": false }
}
Un articolo, con tutto ciò che l'elenco omette: content_markdown, content_html, le FAQ come schema.org JSON-LD pronte da inserire nella pagina ed eventuali link di scambio presenti nell'articolo.
I nomi dei campi sono quelli che il nostro webhook invia, volutamente. Se ha già un ricevitore webhook, lo stesso parser legge anche questo.
Esempio
curl https://seonis.ai/api/v1/articles/918 \ -H "Authorization: Bearer $SEONIS_API_KEY"
{
"article": {
"id": 918,
"site_id": 5,
"language": "en",
"status": "ready",
"title": "How to choose a pepper grinder",
"slug": "how-to-choose-a-pepper-grinder",
"meta_description": "Burr or blade, ceramic or steel: what matters in a grinder.",
"content_markdown": "Grinders differ.\n\n## Burr or blade\n\nA **burr** grinder ...",
"content_html": "<p>Grinders differ.</p>\n<h2>Burr or blade</h2> ...",
"faq_schema": { "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [] },
"hero_image": { "url": "https://seonis.ai/storage/images/5/918.jpg", "alt": "A pepper grinder" },
"word_count": 1812,
"published_url": null,
"updated_at": "2026-09-06T06:31:12+00:00",
"quality": { "seo_score": 88, "language_score": 96, "language_findings": [] },
"exchange_links": []
}
}
È Lei a mettere online l'articolo; qui ci comunica l'indirizzo. È l'unico endpoint che modifica qualcosa.
Fa esattamente ciò che fa una consegna effettuata da noi: l'articolo viene contrassegnato come pubblicato, viene conteggiato nel Suo limite mensile, l'elemento del piano si chiude, eventuali link di scambio al suo interno ricevono l'indirizzo che il verificatore stava aspettando e la Sua Pagina Facebook viene avvisata se ne ha collegata una. Senza questa chiamata l'articolo resta pronto per sempre e nulla di tutto questo accade.
Esempio
curl -X POST https://seonis.ai/api/v1/articles/918/published \
-H "Authorization: Bearer $SEONIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://peppervale.co.uk/blog/how-to-choose-a-pepper-grinder"}'
Risposte
| 200 | Registrato. L'articolo torna con il nuovo stato, published_at e published_url. |
| 422 | L'url manca o non è un indirizzo completo http:// o https://. |
| 409 | L'articolo non è pronto per essere pubblicato, oppure risulta già registrato come pubblicato. L'articolo viene restituito con il rifiuto, così può vedere quale dei due casi è. |
In Settings, poi Publishing, c'è un motore chiamato "REST API: Lei recupera e pubblica". Non chiede nulla, perché non c'è nulla da inviare da parte nostra. Quello che cambia è ciò che accade ogni mattina: un articolo completato resta pronto senza indirizzo, e la schermata di pubblicazione indica che è in attesa che Lei lo recuperi invece di mostrare una consegna non riuscita.
Può usare l'API senza collegarla: gli endpoint funzionano per qualsiasi account con una chiave. Collegarla è il modo in cui il resto del prodotto sa che deve smettere di aspettarsi un proprio indirizzo, ed è ciò che impedisce che un articolo pubblicato da Lei venga conteggiato come errore.
Un solo formato ovunque, sia che il rifiuto provenga dal controllo della chiave sia dal validatore, così nulla deve analizzarne due.
{ "message": "That API key is not valid, or it has been revoked." }
| Stato | Che cosa significa |
|---|---|
| 401 | Nessuna chiave, una chiave che non è nostra o una chiave che è stata revocata. |
| 404 | Nessun articolo o sito di questo tipo su questo account. L'articolo di un altro account risponde con 404 anziché 403: un'API che dice "non è suo" ha confermato che la cosa esiste. |
| 409 | La richiesta era valida, ma l'articolo non è in uno stato adatto. |
| 422 | Manca un parametro o è errato. La risposta contiene un oggetto errors che indica il campo, oltre al messaggio. |
| 429 | Oltre il limite di richieste. Retry-After indica quanto attendere. |
#!/usr/bin/env bash
set -euo pipefail
# 1. What is finished and not yet on the site?
ready=$(curl -sG https://seonis.ai/api/v1/articles \
-H "Authorization: Bearer $SEONIS_API_KEY" \
-d site_id=5 -d status=ready -d per_page=100)
for id in $(echo "$ready" | jq -r '.articles[].id'); do
# 2. Take the article, body and all.
curl -s https://seonis.ai/api/v1/articles/$id \
-H "Authorization: Bearer $SEONIS_API_KEY" \
| jq -r '.article.content_markdown' > "content/posts/$id.md"
# 3. Your build puts it live, and you know where it landed.
slug=$(echo "$ready" | jq -r ".articles[] | select(.id==$id) | .slug")
curl -s -X POST https://seonis.ai/api/v1/articles/$id/published \
-H "Authorization: Bearer $SEONIS_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"url\": \"https://peppervale.co.uk/blog/$slug\"}"
done
La prova è sufficiente per leggere l'API: gli articoli scritti durante questo periodo sono articoli reali e tornano tramite questi endpoint come tutti gli altri.
Inizi la prova gratuita