L'API Notiondesk legge tutto ciò che il tuo centro assistenza pubblica: ogni articolo e raccolta in qualsiasi lingua, con il relativo contenuto in formato Markdown, lo stato di pubblicazione e lo stato di sincronizzazione, oltre alle voci del registro delle modifiche pubblicate. Usala per eseguire il backup del tuo centro assistenza, inviare i tuoi contenuti a un altro strumento o verificare quali articoli non sono stati sincronizzati correttamente.
L'API legge i contenuti ma non li scrive mai. I tuoi articoli e le tue raccolte rimangono in Notion: per modificarne uno, modificalo in Notion e avvia la sincronizzazione .
Nell'API Notiondesk, una collezione viene chiamata categoria .
| Metodo | Sentiero | Ambito di applicazione | Fa |
|---|---|---|---|
GET | /sites/{site_id}/articles | read | Elenca articoli in una lingua |
GET | /sites/{site_id}/articles/{article_id} | read | Legge un articolo con il suo contenuto in formato markdown |
GET | /sites/{site_id}/categories | read | Elenca le collezioni in una lingua, con la loro gerarchia |
GET | /sites/{site_id}/categories/{category_id} | read | Legge una raccolta con il suo contenuto in saldo |
GET | /sites/{site_id}/changelog | read | Elenco delle voci del registro delle modifiche pubblicate, dalla più recente alla meno recente. |
Scegli la lingua
Ogni percorso in questa pagina accetta un parametro di query facoltativo locale, ad esempio ?locale=fr. Senza di esso, la risposta utilizza la lingua predefinita del centro assistenza. Nei percorsi elenco, locale deve essere una delle lingue supportate dal centro assistenza: la supported_locales del centro assistenza . Leggi Supporto per più lingue nel tuo Centro assistenza per aggiungere lingue.
Elenco degli articoli
L'elenco comprende tutti gli articoli in ogni stato, bozze e articoli archiviati, nell'ordine in cui sono stati creati. È possibile sfogliarlo con page_size e cursor, come descritto nelle richieste API di impaginazione e versione Notiondesk .
curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles?page_size=100&locale=en" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16"{
"object": "list",
"data": [
{
"id": "1761580412",
"title": "Connect your Notion workspace",
"slug": "connect-your-notion-workspace",
"status": "published",
"categories": [
{"id": "910000002", "name": "Connecting Notion", "slug": "connecting-notion", "locale": "en", "status": "published"}
],
"tags": [{"name": "Setup", "slug": "setup"}],
"locales_count": 2,
"updated_at": "2026-10-18T14:39:03+00:00",
"published_at": "2026-10-05T04:39:04+00:00",
"locale": "en",
"reading_time": 3,
"views_count": 42,
"reactions_percent": {"smiley": 50, "neutral_face": 25, "disappointed": 25},
"source_notion_page_id": "3d5001d0-2470-8122-a1b2-c3d4e5f60789",
"notion_article_page_url": "https://www.notion.so/3d5001d024708122a1b2c3d4e5f60789",
"sync_in_progress": false,
"sync_timeout": false,
"sync_failed": false,
"sync_error_code": null,
"auto_translated": false
}
],
"has_more": true,
"next_cursor": "OPAQUE_CURSOR"
}| Campo | Senso |
|---|---|
id | L'identificativo dell'articolo, utilizzato come article_id per leggere l'articolo |
title, slug | Il titolo dell'articolo e il relativo percorso nel centro assistenza |
status | draft, published, review o archived. Vedi Come controllare la visibilità degli articoli |
categories | Le collezioni a cui appartiene l'articolo, ciascuna con id, name, slug, locale e status |
tags | I tag dell'articolo, ciascuno con name e slug |
locales_count | In quante lingue esiste l'articolo? |
updated_at, published_at | Data dell'ultima modifica e data di pubblicazione dell'articolo. |
locale | La lingua di questo articolo |
reading_time | Tempo di lettura stimato, in minuti |
views_count | Quante volte i lettori hanno aperto l'articolo? |
reactions_percent | Ogni reazione del lettore con la sua quota sul totale delle reazioni, in percentuale. I nomi delle reazioni dipendono dal tuo stile di feedback. |
source_notion_page_id, notion_article_page_url | La pagina Notion da cui viene sincronizzato l'articolo e l'URL della pagina Notion di questa lingua (null per una traduzione automatica) |
sync_in_progress, sync_timeout, sync_failed, sync_error_code | Se è in corso una sincronizzazione dell'articolo, se l'ultima è andata in timeout o non è riuscita e perché. |
auto_translated | Se questo linguaggio sia stato prodotto da una traduzione automatica |
sync_failed: trueLeggi un articolo in formato markdown
curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles/1761580412?locale=en" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16"{
"id": "1761580412",
"type": "article",
"title": "Connect your Notion workspace",
"slug": "connect-your-notion-workspace",
"text": "# Connect your Notion workspace\n\nOpen **Settings**, then **Notion**...",
"url": "https://help.example.com/en/articles/connect-your-notion-workspace",
"locale": "en",
"last_updated": "2026-10-18T14:39:03+00:00",
"category": {"id": "910000002", "title": "Connecting Notion", "slug": "connecting-notion"},
"tags": ["setup"],
"truncated": false,
"author": {"name": "Ada Lovelace"},
"status": "published",
"content_available": true,
"sync_in_progress": false,
"sync_timeout": false,
"sync_failed": false,
"sync_error_code": null
}| Campo | Senso |
|---|---|
type | Sempre __PRESERVATO_69__ |
text | Il contenuto dell'articolo in formato Markdown. Vuoto se non è ancora stato memorizzato alcun contenuto. |
truncated | true quando text è stato tagliato a 200.000 byte. Il taglio cade sempre su un carattere intero |
content_available | Se Notiondesk contiene già contenuti per questa lingua |
url | L'indirizzo pubblico dell'articolo |
category | La raccolta principale dell'articolo: id, title e slug |
tags | Gli slug dei tag dell'articolo |
author | L'autore dell'articolo: name |
Ogni stato è leggibile, quindi puoi leggere una bozza prima di pubblicarla. Un articolo senza traduzione nella lingua richiesta locale risposte 404 not_found.
Elenca le raccolte
Ogni elemento è una collezione nella lingua richiesta, nell'ordine in cui le collezioni sono state create:
Ricostruisci la struttura ad albero della tua collezione con tre campi:
curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/categories?page_size=100" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16"{
"id": "910000001",
"name": "Getting Started",
"slug": "getting-started",
"updated_at": "2026-10-18T14:39:12+00:00",
"locale": "en",
"is_parent": true,
"source_notion_page_id": "5d5001d0-2470-8122-a1b2-c3d4e5f60789",
"notion_category_page_url": "https://www.notion.so/5d5001d024708122a1b2c3d4e5f60789",
"sync_in_progress": false,
"sync_timeout": false,
"sync_failed": false,
"sync_error_code": null,
"parent_ids": [],
"children_ids": ["910000002"],
"locales_count": 2,
"status": "published",
"auto_translated": false
}| Campo | Senso |
|---|---|
is_parent | true per una raccolta in cima alla gerarchia |
parent_ids | Le collezioni direttamente sopra questa |
children_ids | Le collezioni direttamente sotto questa |
L'elenco non contiene il numero di articoli. Per contare gli articoli di una raccolta, elenca gli articoli e raggruppali per categories. Scopri come le raccolte organizzano il tuo centro assistenza in Utilizzare le raccolte per organizzare i tuoi articoli .
Leggi una raccolta
La risposta ha la stessa forma di un articolo: type è category, title, slug, url, status, i campi di sincronizzazione e text con il contenuto della raccolta stessa come markdown, vuoto quando non ne ha.
Elenco delle voci del registro delle modifiche
Il registro delle modifiche elenca gli articoli pubblicati e archiviati nelle tue raccolte di registro delle modifiche, dal più recente al più vecchio. Puoi configurarlo seguendo la procedura di configurazione dei registri delle modifiche nel tuo centro assistenza .
curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/categories/910000001?locale=en" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16"curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/changelog?page_size=50&locale=en" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16"{
"object": "list",
"data": [
{
"id": "article:1761497350",
"title": "Multilingual sync is now available",
"slug": "multilingual-sync-is-now-available",
"text": "Help centers on the Enterprise plan can now sync every configured locale in a single run instead of one language at a time.",
"published_at": "2026-10-13T09:12:44+00:00",
"last_updated": "2026-10-18T14:39:03+00:00",
"tags": [],
"url": "https://help.example.com/en/changelogs",
"locale": "en"
}
],
"has_more": true,
"next_cursor": "OPAQUE_CURSOR"
}| Campo | Senso |
|---|---|
id | article: seguito dall'ID dell'articolo della voce. Rimuovere il prefisso per leggere la voce completa con il percorso dell'articolo |
text | Il testo semplice della voce, di solito un estratto di circa 30 parole |
published_at, last_updated | Quando la voce è stata pubblicata e quando è stata modificata l'ultima volta |
tags | Gli slug dei tag della voce |
url | La tua pagina del registro delle modifiche in questa lingua |
È utile saperlo:
- Una voce viene visualizzata solo quando la relativa raccolta di modifiche è pubblicata nella lingua richiesta.
- In un centro assistenza che utilizza account guest, l'elenco mostra solo le voci visibili a tutti i lettori.
- L'elenco raggiunge al massimo le 1.000 voci più recenti. Oltre tale soglia,
has_moreèfalseanche in presenza di voci più vecchie.
- Raramente, durante un problema temporaneo del servizio, la lettura dell'elenco potrebbe saltare o ripetere una voce. Rileggere l'elenco in seguito per visualizzarlo completo.
Errori
| Stato | Quando | code |
|---|---|---|
| 400 | page_size è al di fuori dell'intervallo da 1 a 100, cursor non è valido, locale non è una lingua supportata dal centro assistenza (elenchi) o non è compreso tra 2 e 10 caratteri (letture singole), oppure la query ha un parametro sconosciuto | validation_error |
| 403 | La chiave non ha l'ambito read | insufficient_scope |
| 403 | Solo registro delle modifiche: il registro delle modifiche è disattivato o non è incluso nel tuo piano, oppure le analisi del centro assistenza sono disattivate. | permission_denied |
| 404 | Il centro assistenza, l'articolo o la raccolta non esiste nel tuo spazio di lavoro, non ha una traduzione in locale oppure il registro delle modifiche è attivo ma non ha una raccolta di registro delle modifiche | not_found |
Ogni percorso può anche rispondere a invalid_version, authentication_error, rate_limited e internal_error. Vedi Gestione degli errori API, dei limiti di frequenza e dei tentativi di ripetizione per Notiondesk .
Domande frequenti
Posso creare o modificare articoli con l'API Notiondesk?
No. Notion è la fonte ufficiale dei tuoi contenuti. Modifica l'articolo in Notion, quindi avvia la sincronizzazione con l'API oppure attendi la sincronizzazione programmata.
L'elenco degli articoli comprende anche le bozze?
Sì. L'elenco e il percorso di lettura includono tutti gli stati: draft, published, review e archived. Filtra i risultati nel tuo codice in base a status per mantenere solo gli articoli pubblicati.
Come faccio a esportare tutti gli articoli in formato Markdown?
Elenca gli articoli, quindi leggi ciascuno di essi in base al suo id. L' articolo sugli esempi contiene uno script di backup completo.
Che cosa significa truncated: true?
truncated: true?Il markdown dell'articolo è più lungo di 200.000 byte, quindi text contiene i primi 200.000 byte, troncati a caratteri interi.
Perché notion_article_page_url è vuoto per alcune lingue?
notion_article_page_url è vuoto per alcune lingue?Quel linguaggio è stato prodotto tramite traduzione automatica, quindi non ha una pagina Notion dedicata.