Come funziona
Contivo scrive e pubblica secondo la programmazione che hai impostato. Quando un post va online riceve uno slug permanente e viene segnato come pubblicato: lì finisce il ruolo di Contivo. È il tuo sito a chiedere i post quando gli servono.
Questa direzione è importante: Contivo non ha mai accesso in scrittura al tuo codice, alla tua pipeline di deploy o al tuo CMS. Se disattivi Contivo, il tuo sito continua a mostrare ciò che ha recuperato l'ultima volta.
Autenticazione
Ogni richiesta include una chiave del sito come bearer token. Creala in Connessioni → Siti web. Viene mostrata una sola volta, al momento della creazione, e non si può recuperare: se la perdi, crea una nuova connessione al sito.
Authorization: Bearer ctv_your_site_keyTieni la chiave lato server. Può leggere tutto ciò che questo workspace ha mai pubblicato. Gli endpoint inviano header CORS permissivi, quindi un browser può chiamarli — ma così facendo consegni la tua chiave a ogni visitatore. Fai la richiesta in un server component, in un route handler, in fase di build o dal tuo backend.
Elenco dei post
GET https://www.contivo.app/api/v1/postsRestituisce i post pubblicati del workspace a cui appartiene la chiave, dal più recente.
| Parametro | Tipo | Significato |
|---|---|---|
| limit | 1–100, default 20 | Quanti post restituire. I valori fuori intervallo vengono riportati nei limiti, non rifiutati. |
| cursor | string | Il nextCursor di una risposta precedente. Omettilo per la prima pagina. |
| channel | default "blog" | Quale canale restituire. Passa "all" per includere anche i post social — di solito non li vuoi su un sito. |
{
"posts": [
{
"id": "cmtj8m9cw0004669budmzpagu",
"slug": "eliminating-the-triage-bottleneck",
"title": "Eliminating the Triage Bottleneck",
"content": "Manual bug triage remains a major source of friction…",
"excerpt": "Manual bug triage remains a major source of friction for engineering teams…",
"channel": "blog",
"publishedAt": "2026-09-02T02:00:00.000Z",
"updatedAt": "2026-09-02T02:00:04.118Z"
}
],
"nextCursor": "cmtj8m9cw0004669budmzpagu"
}nextCursor è null quando non ci sono altre pagine. È l'unico segnale affidabile di fine elenco: non fermarti solo perché una pagina è più corta.
Un singolo post
GET https://www.contivo.app/api/v1/posts/{slug}Restituisce { "post": { … } } con lo stesso oggetto visto sopra. Costruisci le route delle tue pagine su slug, mai su id: lo slug viene assegnato una volta sola alla pubblicazione e non cambia mai, ed è questo che mantiene stabili i tuoi URL.
L'oggetto post
| Campo | Tipo | Note |
|---|---|---|
| id | string | Identificativo interno stabile. Va bene come key di React, non per gli URL. |
| slug | string | Sicuro per gli URL, unico per workspace, permanente dal momento della pubblicazione. |
| title | string | L'argomento del post. |
| content | string | Il testo completo, in Markdown. Renderizzalo con quello che usi già. |
| excerpt | string | I primi ~200 caratteri senza Markdown. Per card, elenchi e meta description. |
| channel | string | Di norma "blog". Altri valori solo se hai chiesto channel=all. |
| publishedAt | string | null | ISO 8601 UTC. |
| updatedAt | string | ISO 8601 UTC. Utile per le chiavi di cache, le sitemap e lastmod. |
Errori
| Stato | Errore nel body | Cosa significa |
|---|---|---|
| 401 | unauthorized | Chiave mancante, malformata, sconosciuta o revocata — oppure la connessione al sito non è attiva. Tutti e quattro i casi restituiscono di proposito la stessa risposta, così nessuno può usare questo endpoint per scoprire quali chiavi esistono. |
| 404 | not_found | Solo per il singolo post. Nessun post pubblicato con quello slug in questo workspace. Anche uno slug di un altro cliente restituisce 404, mai 403. |
Un array posts vuoto non è un errore. Significa che la chiave è valida e che su quel canale non è ancora stato pubblicato nulla: l'Autopilot deve pubblicare qualcosa prima che qui compaia qualcosa.
Caching e aggiornamento
Le risposte vengono inviate con Cache-Control: no-store, quindi l'API non chiede mai a una CDN o a un browser di conservarle. Il caching lo decidi interamente tu, ed è giusto così: il tuo framework conosce il tuo traffico e quanto puoi tollerare contenuti non aggiornati.
const res = await fetch("https://www.contivo.app/api/v1/posts", {
headers: { Authorization: `Bearer ${process.env.CONTIVO_SITE_KEY}` },
next: { revalidate: 300 },
});Una finestra di cinque minuti è un default sensato. Per aggiornamenti istantanei, abbina un revalidate lungo al webhook qui sotto invece di interrogare l'API più spesso.
Webhook di revalidate
Facoltativo. Imposta un URL di revalidate sulla connessione al sito e Contivo lo chiamerà subito dopo ogni pubblicazione, così la tua cache si svuota immediatamente invece che all'intervallo successivo.
POST <your revalidate URL>
Content-Type: application/json
Authorization: Bearer <your revalidate secret> // only if you set one
{ "slug": "eliminating-the-triage-bottleneck", "event": "post.published" }import { revalidatePath } from "next/cache";
export async function POST(req: Request) {
if (req.headers.get("authorization") !== `Bearer ${process.env.CONTIVO_REVALIDATE_SECRET}`) {
return new Response("Unauthorized", { status: 401 });
}
const { slug } = await req.json();
revalidatePath("/blog");
revalidatePath(`/blog/${slug}`);
return Response.json({ revalidated: true });
}La chiamata va in timeout dopo 8 secondi e il suo stato viene registrato sulla connessione al sito. Un errore viene annotato e non blocca mai la pubblicazione: il post è già online e il tuo sito lo recupererà comunque alla prossima richiesta programmata.
Esempi pratici
Verifica la chiave dal terminale
curl -sS -H "Authorization: Bearer $CONTIVO_SITE_KEY" \
"https://www.contivo.app/api/v1/posts?limit=1" | jqRecupera tutti i post, una pagina alla volta
async function allPosts(key) {
const out = [];
let cursor = null;
do {
const url = new URL("https://www.contivo.app/api/v1/posts");
url.searchParams.set("limit", "100");
if (cursor) url.searchParams.set("cursor", cursor);
const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
if (!res.ok) throw new Error(`Contivo returned ${res.status}`);
const page = await res.json();
out.push(...page.posts);
cursor = page.nextCursor; // null ends the loop
} while (cursor);
return out;
}Generazione di siti statici
export async function generateStaticParams() {
const res = await fetch("https://www.contivo.app/api/v1/posts?limit=100", {
headers: { Authorization: `Bearer ${process.env.CONTIVO_SITE_KEY}` },
});
const { posts } = await res.json();
return posts.map((p) => ({ slug: p.slug }));
}Python
import os, requests
r = requests.get(
"https://www.contivo.app/api/v1/posts",
headers={"Authorization": f"Bearer {os.environ['CONTIVO_SITE_KEY']}"},
params={"limit": 20},
timeout=10,
)
r.raise_for_status()
for post in r.json()["posts"]:
print(post["slug"], "-", post["title"])PHP / WordPress
$response = wp_remote_get(
'https://www.contivo.app/api/v1/posts?limit=20',
['headers' => ['Authorization' => 'Bearer ' . getenv('CONTIVO_SITE_KEY')]]
);
$posts = json_decode(wp_remote_retrieve_body($response), true)['posts'];Limiti e garanzie
| Proprietà | Valore | Note |
|---|---|---|
| Metodi | GET, OPTIONS | Sola lettura. Non c'è modo di scrivere contenuti tramite questa API. |
| Dimensione pagina | max 100 | I valori più alti vengono riportati al massimo, non rifiutati. |
| Ambito | un workspace | Una chiave può leggere solo il workspace in cui è stata creata. |
| Slug | permanenti | Assegnati alla pubblicazione, mai riscritti. Sicuri da usare negli URL e nelle sitemap. |
| Revoca | immediata | Eliminando o disattivando una connessione al sito, la sua chiave restituisce 401 già dalla richiesta successiva. |
Oggi non c'è un rate limit dichiarato. Metti comunque in cache le risposte: un sito che fa una richiesta a ogni visualizzazione di pagina è fragile per motivi suoi, non solo nostri.
Qualcosa di sbagliato o mancante? Questa pagina è generata dallo stesso codice che serve l'API, quindi ogni discrepanza è un bug da segnalare. Stampa la pagina per salvarla in PDF.