L'API REST Notiondesk consente al tuo codice di gestire i tuoi centri di assistenza. Puoi elencare i tuoi centri di assistenza, leggere i relativi articoli, raccolte e registro delle modifiche, gestire i reindirizzamenti di pagina, modificare le impostazioni e il branding, estrarre dati analitici e feedback dei lettori e attivare la sincronizzazione con Notion.
Questo articolo spiega cosa può fare l'API Notiondesk, chi può utilizzarla e come effettuare la prima richiesta in pochi minuti.
Cosa puoi fare con l'API Notiondesk
| Compito | Esempio | Guida |
|---|---|---|
| Consulta i centri di assistenza. | Elenca tutti i centri di assistenza presenti nel tuo spazio di lavoro e le relative lingue. | Consulta i centri di assistenza. |
| Leggi il contenuto | Esporta ogni articolo in formato Markdown oppure elenca le voci del registro delle modifiche. | Leggi articoli, raccolte e voci del registro delle modifiche |
| Pubblicare le modifiche alla nozione | Sincronizza il tuo centro assistenza da una pipeline CI dopo aver modificato Notion | Sincronizzazione di Trigger Notion |
| Gestire i reindirizzamenti | Importa centinaia di reindirizzamenti dopo la migrazione da un altro centro assistenza | Gestire i reindirizzamenti di pagina |
| Cambia lingua | Aggiungi una lingua o attiva la traduzione automatica | Gestione delle lingue e della traduzione automatica |
| Modifica le impostazioni | Aggiorna i titoli SEO, llms.txt, il modulo di contatto o il registro delle modifiche | Aggiorna le impostazioni del centro assistenza |
| Cambiare il marchio | Applica i colori e il tema del tuo marchio a diversi centri di assistenza. | Personalizza il marchio e i temi |
| Gestisci le integrazioni | Configura Google Analytics, Plasible, Intercom o Crisp | Gestisci le integrazioni |
| Analisi dei dati | Invia visitatori, ricerche e articoli più popolari al tuo strumento di BI | Ottieni analisi del centro assistenza |
| Leggi i commenti | Invia ogni mattina le reazioni negative agli articoli su Slack. | Esporta il feedback dei lettori |
Per gli script pronti all'uso, vedere Automatizzare le attività comuni del centro assistenza con l'API Notiondesk .
Chi può utilizzare l'API Notiondesk?
- Piano: l'accesso alle API è incluso nei piani Enterprise.
- Creazione delle chiavi: i proprietari e gli amministratori dello spazio di lavoro creano le chiavi API nella dashboard.
- Autorizzazioni: una chiave o un'app non possono mai fare più di quanto la persona che la possiede possa fare nel tuo spazio di lavoro. Vedi Autenticazione con l'API Notiondesk tramite chiavi API .
Effettua la tua prima richiesta API Notiondesk
1. Crea una chiave API
Nella dashboard di Notiondesk, apri Impostazioni , quindi Sviluppatori > Chiavi API e fai clic su Crea chiave . Assegna un'etichetta, seleziona l'ambito di lettura e copia la chiave quando viene visualizzata. La chiave inizia con nd_wsk_ e viene visualizzata una sola volta.
Memorizzalo in una variabile d'ambiente:
2. Elenca i tuoi centri di assistenza
La risposta elenca tutti i centri di assistenza presenti nel tuo spazio di lavoro:
3. Elenca gli articoli di un centro assistenza
Ecco fatto! Stai leggendo il tuo centro assistenza direttamente dal codice sorgente.
Notiondesk Nozioni di base sull'API
export NOTIONDESK_API_KEY="nd_wsk_..."curl "<https://api.notiondesk.so/sites>" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16"{
"object": "list",
"data": [
{
"id": "c74781f6-1aea-4e17-ab23-bbb8b4d174b6",
"full_domain": "help.example.com",
"enabled": true,
"default_locale": "en",
"locales": ["en", "fr"]
}
],
"has_more": false,
"next_cursor": null
}curl "<https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles?page_size=10>" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16"| Argomento | Cosa sapere |
|---|---|
| URL di base | https://api.notiondesk.so |
| Autenticazione | Authorization: Bearer <key or access token>. Vedi chiavi API e OAuth |
| Cannocchiali | read, write, sync e admin. Ogni percorso richiede uno |
| Versione | Intestazione facoltativa nd-version |
| Formato | Corpi di richiesta e risposta JSON con nomi di campo in formato snake_case |
| Paginazione | Basato sul cursore: page_size (da 1 a 100, predefinito 20) e cursor. Vedi Richieste di impaginazione e versione . |
| Errori | Un singolo pacchetto JSON con un code leggibile dalla macchina. Vedi Gestione degli errori, dei limiti di frequenza e dei tentativi. |
Notiondesk API o Workspace MCP?
Notiondesk offre due modi per gestire i centri di assistenza al di fuori della dashboard. Consentono di accedere alle stesse funzionalità attraverso modalità diverse.
| Notiondesk API REST | Area di lavoro MCP | |
|---|---|---|
| Chi lo chiama | Il tuo codice: script, pipeline CI, strumenti interni, app dei partner | Un assistente basato sull'intelligenza artificiale come Claude, ChatGPT, Cursor o VS Code. |
| Come si firma | Una chiave API dell'area di lavoro o un token di accesso OAuth | OAuth, tramite il tuo client AI |
| Ideale per | Automazione ripetibile e deterministica | Lavoro di conversazione: "individuare gli articoli che i lettori non apprezzano e suggerire delle soluzioni" |
Notiondesk Endpoint API
| Metodo | Sentiero | Ambito di applicazione | Guida |
|---|---|---|---|
GET | /sites | read | Centri di assistenza |
GET | /sites/{site_id} | read | Centri di assistenza |
GET | /sites/{site_id}/sync-status | read | Centri di assistenza |
GET | /sites/{site_id}/articles | read | Contenuto |
GET | /sites/{site_id}/articles/{article_id} | read | Contenuto |
GET | /sites/{site_id}/categories | read | Contenuto |
GET | /sites/{site_id}/categories/{category_id} | read | Contenuto |
GET | /sites/{site_id}/changelog | read | Contenuto |
POST | /sites/{site_id}/sync | sync | Sincronizzazioni |
POST | /sites/{site_id}/articles/{article_id}/sync | sync | Sincronizzazioni |
POST | /sites/{site_id}/categories/{category_id}/sync | sync | Sincronizzazioni |
PATCH | /sites/{site_id}/settings/auto-sync | sync | Sincronizzazioni |
GET | /sites/{site_id}/page-redirects | read | Reindirizzamenti |
POST | /sites/{site_id}/page-redirects | write | Reindirizzamenti |
PATCH | /sites/{site_id}/page-redirects/{redirect_id} | write | Reindirizzamenti |
DELETE | /sites/{site_id}/page-redirects/{redirect_id} | admin | Reindirizzamenti |
PATCH | /sites/{site_id}/settings/supported-languages | write | Lingue |
PATCH | /sites/{site_id}/settings/auto-translate | write | Lingue |
PATCH | /sites/{site_id}/settings/content | write | Impostazioni |
PATCH | /sites/{site_id}/settings/ai-optimization | write | Impostazioni |
PATCH | /sites/{site_id}/settings/contact-form | write | Impostazioni |
PATCH | /sites/{site_id}/settings/changelog | write | Impostazioni |
GET | /sites/{site_id}/settings/customize | read | Branding |
PATCH | /sites/{site_id}/settings/customize | admin | Branding |
GET | /sites/{site_id}/themes | read | Branding |
GET | /sites/{site_id}/integrations | read | Integrazioni |
PATCH | /sites/{site_id}/integrations/{type} | admin | Integrazioni |
POST | /sites/{site_id}/integrations/{type}/disable | admin | Integrazioni |
GET | /sites/{site_id}/analytics/{report} | read | Analisi |
GET | /sites/{site_id}/feedback | read | Feedback |
Domande frequenti
Posso creare o modificare articoli con l'API Notiondesk?
No. Articoli, raccolte e voci del registro delle modifiche vengono scritti in Notion e ogni sincronizzazione sovrascrive quanto memorizzato in Notiondesk. Modifica la pagina Notion, utilizzando l'editor di Notion o l'API di Notion, quindi attiva la sincronizzazione per pubblicare la modifica.
Una singola chiave API è valida per tutti i miei centri di assistenza?
Sì. Una chiave API dello spazio di lavoro funziona per ogni centro assistenza presente in quello spazio di lavoro. Ogni richiesta specifica il centro assistenza nel suo percorso, ad esempio /sites/{site_id}/articles.
Dove posso trovare il site_id del centro assistenza?
site_id del centro assistenza?Chiama GET /sites per visualizzare l'elenco dei tuoi centri di assistenza con il relativo id. È anche l'identificativo che segue /s/ nella barra degli indirizzi della tua dashboard.