Leia artigos, coleções e entradas do changelog com a API Notiondesk

A API Notiondesk lê tudo o que sua central de ajuda publica: todos os artigos e coleções em qualquer idioma, com seu conteúdo em Markdown, seu status de publicação e seu estado de sincronização, além das suas entradas de changelog publicadas. Use-a para fazer backup da sua central de ajuda, enviar seu conteúdo para outra ferramenta ou verificar quais artigos não foram sincronizados.

A API lê o conteúdo, mas nunca o grava. Seus artigos e coleções permanecem no Notion: para alterar um deles, edite-o no Notion e inicie uma sincronização .

Na API Notiondesk, uma coleção é chamada de categoria .

Escolha o idioma

Cada rota nesta página aceita um parâmetro de consulta opcional locale, como ?locale=fr. Sem ele, a resposta usa o idioma padrão da central de ajuda. Nas rotas de lista, locale deve ser um dos idiomas que a central de ajuda oferece: o supported_locales da central de ajuda . Leia Suporte a vários idiomas na sua Central de Ajuda para adicionar idiomas.

Artigos da lista

A lista inclui todos os artigos em todos os status, rascunhos e artigos arquivados também, na ordem em que foram criados. Navegue pelas páginas com page_size e cursor, conforme descrito em Paginate e solicitações de API da versão 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"
}

Observação: Filtre os resultados no seu código para encontrar todos os artigos cuja última sincronização falhou, corrija-os no Notion e sincronize-os novamente .sync_failed: true

Leia um artigo em 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
}

Cada status é legível, então você pode ler um rascunho antes de publicá-lo. Um artigo sem tradução no campo locale solicitado retorna 404 not_found.

Listar coleções

Cada item é uma coleção no idioma solicitado, na ordem em que as coleções foram criadas:

Reconstrua sua árvore de coleção com três campos:

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
}

A lista não contém a contagem de artigos. Para contar os artigos de uma coleção, liste-os e agrupe-os por categories. Saiba como as coleções organizam sua central de ajuda em Usar coleções para organizar seus artigos .

Leia uma coleção

A resposta tem o mesmo formato que um artigo: type é category, title, slug, url, status, os campos de sincronização e text com o conteúdo próprio da coleção em Markdown, vazio quando não houver nenhum.

Listar entradas do changelog

O changelog lista os artigos publicados e arquivados em suas coleções de changelog, do mais recente para o mais antigo. Configure-o seguindo as instruções em "Configurando changelogs" na sua central de ajuda .

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"
}

Bom saber:

• Uma entrada só aparece quando sua coleção de registros de alterações é publicada no idioma solicitado.

• Em uma central de ajuda que utiliza contas de convidado, a lista exibe apenas as entradas que todos os leitores podem visualizar.

• A lista atinge, no máximo, as 1.000 entradas mais recentes. Depois disso, has_more é false, mesmo quando existem entradas mais antigas.

• Raramente, durante uma falha temporária do serviço, a leitura de uma lista pode pular ou repetir uma entrada. Leia-a novamente mais tarde para obter a lista completa.

Erros

Cada rota também pode responder a invalid_version, authentication_error, rate_limited e internal_error. Consulte Erros de API, limites de taxa e novas tentativas de tratamento de Notiondesk .

Perguntas frequentes

O que vem a seguir?

• O Trigger Notion sincroniza com a API Notiondesk

• Gerencie idiomas e tradução automática com a API Notiondesk

• Automatize tarefas comuns da central de ajuda com a API Notiondesk