Helpdesk Content API

Overview

The Helpdesk Content API exposes everything your help desk contains — help centers, the collection tree, and every article in every language — as raw JSON. Pull the content into your own database and render a fully custom help site with your own design, on your own domain. Content endpoints are read-only (GET); authoring stays in the dashboard, and the hosted help center keeps working unchanged alongside it.

Authentication

Use your existing Data API key from Settings → API Keys (the same sk_live_ key the External Data API uses), passed in the X-Api-Key header or as a Bearer token.

curl -H "X-Api-Key: sk_live_YOUR_KEY" \
  https://api.nextcap.ai/api/v1/external/help/centers

Localized Fields

Localized fields (title, summary, description, body) are locale maps like { "en": "…", "fr": "…" } — one response carries every translation, and article body values are Markdown. To match the hosted help center, treat an article as translated into a locale only when both title[locale] and body[locale] are non-empty, and fall back to the center's default_locale otherwise.

Help Centers

{
  "data": [
    {
      "id": "uuid",
      "slug": "acme-support",
      "name": "Acme Support",
      "description": "How to get the most out of Acme",
      "scope": "agent",
      "default_locale": "en",
      "locales": ["en", "fr", "es"],
      "primary_widget_id": "uuid",
      "custom_domain": "help.acme.com",
      "created_at": "2026-05-01T09:00:00.000Z",
      "updated_at": "2026-07-01T14:30:00.000Z"
    }
  ]
}

Collections & Categories

{
  "data": [
    {
      "id": "uuid",
      "help_center_id": "uuid",
      "parent_id": null,
      "slug": "billing",
      "title": { "en": "Billing", "fr": "Facturation" },
      "description": { "en": "Plans, invoices, refunds" },
      "icon": "RiBankCardLine",
      "position": 0,
      "created_at": "2026-05-01T09:00:00.000Z",
      "updated_at": "2026-06-20T11:00:00.000Z"
    }
  ]
}

Articles

{
  "data": [
    {
      "id": "uuid",
      "help_center_id": "uuid",
      "collection_id": "uuid",
      "category_id": null,
      "slug": "getting-started",
      "title":   { "en": "Getting started", "fr": "Premiers pas" },
      "summary": { "en": "Set up your account in five minutes" },
      "body":    { "en": "## Welcome\n\nFirst, …", "fr": "## Bienvenue\n\n…" },
      "cover_image_url": null,
      "seo_title": null,
      "seo_description": null,
      "og_image": null,
      "tags": ["onboarding"],
      "status": "published",
      "visibility": "both",
      "position": 0,
      "author": { "name": "Jane Doe", "avatar_url": "https://…" },
      "published_at": "2026-07-01T10:00:00.000Z",
      "created_at": "2026-06-20T09:00:00.000Z",
      "updated_at": "2026-07-02T14:30:00.000Z",
      "deleted_at": null
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 58, "total_pages": 3 }
}

Public visibility on the hosted help center means status = published and visibility of both or helpcenter_only — mirror that filter for parity (widget_only articles belong to the in-chat Help tab, hidden to neither surface).

Ordering

Collections, categories, and articles each carry a position — the manual order your content team sets by dragging rows in Help Desk → Content. It is the order the hosted help center and the in-widget Help tab render in, so honoring it keeps a custom-built site consistent with what your team arranged.

position is a rank within a sibling group, never a global one. Collections group by parent_id, categories by collection_id, articles by collection_id + category_id (articles with a null collection_id form their own unfiled group). Rank 0 means "first among my siblings", so many rows in one center legitimately hold 0 — sort within a group, not across the whole list.

Collections and categories already return in position order. Articles default to updated_at ascending and that default will not change — the incremental sync below walks pages against it. Ask for reading order one sibling group at a time instead:

curl "https://api.nextcap.ai/api/v1/external/help/centers/CENTER_ID/articles?collection_id=COLLECTION_ID&sort_by=position" \
  -H "X-Api-Key: sk_live_YOUR_KEY"

That query is a single group as long as the collection uses no categories — the normal case, since sub-collections replaced them. If a collection does hold categories, either pull one at a time with category_id, or fetch the whole collection and bucket the result by each article's category_id before rendering — within a bucket the rows are already in position order. Articles with no category come back as category_id: null, which is simply another bucket key.

Every sort ends with a unique key, so paging a sorted list never duplicates or skips a row: position breaks ties the way your own help site does (articles by newest published_at, collections and categories by created_at) and then by id; timestamp sorts go straight to id. An unrecognized sort_by or sort_order returns 400.

Keeping Your Copy in Sync

Webhook Events

Sixteen events cover the content graph: help_center.*, help_collection.*, help_category.* (created / updated / deleted), plus help_article.created / updated / published / deleted, plus help_collection.reordered / help_category.reordered / help_article.reordered. help_article.published fires on the draft → published transition and is the typical "rebuild my public site" trigger. The reordered events carry only the ids whose position moved, so re-fetching that one sibling group is enough. Setup, payload format, signature verification, and retry behavior are on the Webhooks page.

Engagement Beacons (Optional)

The hosted help center records page views and "was this helpful?" votes that power the dashboard's Insights. Your custom frontend can keep that data flowing through the same public, unauthenticated beacons — they are browser-safe and need no API key.