Sync your Knowledgebase

4. Set access, then publish

For this private-center example, first connect verified customer sign-in. Create the audience and save its returned data.id:

curl --fail-with-body -X POST "$BASE/audiences" \
  -H "Authorization: Bearer $SONNY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pro customers","rules":{"match":"all","conditions":[{"trait":"plan","op":"in","value":["pro","business"]}]}}'

Replace AUDIENCE_ID, ARTICLE_ID, and the login URL below. The first request makes the help center Live and restricts it to Pro customers. The second publishes the article. Your app’s login flow must exchange a signed customer JWT with the help center; setting signInUrl alone does not sign anyone in.

curl --fail-with-body -X PATCH "$BASE/help-center" \
  -H "Authorization: Bearer $SONNY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"title":"Acme Help Center","audience":"verified","audienceId":"AUDIENCE_ID","signInUrl":"https://app.example.com/login"}'

# Replace ARTICLE_ID and AUDIENCE_ID with the returned data.id values.
curl --fail-with-body -X PATCH "$BASE/articles/ARTICLE_ID" \
  -H "Authorization: Bearer $SONNY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"audienceId":"AUDIENCE_ID","status":"published"}'

Use the URL returned by GET /help-center to test the signed-in reader view and a signed-out browser. API keys and MCP act as staff and can read content within their scopes; their successful response does not prove that a customer can see the article.

For a public center, use audience: "everyone" and audienceId: null on the center and article, and check the category’s access too. To remove only a named group, send audienceId: null; verified-only access remains unless you explicitly change audience. An omitted audienceId retains the previous assignment. All help-center, category, and article restrictions must match.

Named rules use match: "all" or "any", up to 10 conditions, and strictly typed values. Operators: eq, neq, in, not_in, exists, not_exists, gt, gte, lt, lte. Numeric comparisons take numbers; in/not_in take arrays of 1–100 scalar values; exists/not_exists omit value. Missing traits fail comparisons. See rule behavior, inheritance, and access troubleshooting.

5. Keep the sync current

curl --fail-with-body --get "$BASE/articles" \
  -H "Authorization: Bearer $SONNY_API_KEY" \
  --data-urlencode "page=1" --data-urlencode "limit=100" \
  --data-urlencode "status=published" \
  --data-urlencode "updatedSince=2026-09-01T00:00:00Z"

# Get the full sanitized HTML and read-only analytics for one article.
curl --fail-with-body "$BASE/articles/ARTICLE_ID" \
  -H "Authorization: Bearer $SONNY_API_KEY"

curl --fail-with-body -X POST "$BASE/media" \
  -H "Authorization: Bearer $SONNY_API_KEY" \
  -F "file=@billing.png;type=image/png"

curl --fail-with-body -X PUT "$BASE/articles/reorder" \
  -H "Authorization: Bearer $SONNY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids":["ARTICLE_ID_1","ARTICLE_ID_2"]}'

Use the same workflow through MCP

1. Connect your MCP client and choose the correct workspace. Confirm it has kb:read and kb:write, with access to your channel.
2. Use the dashboard’s channel ID, or call list_sources if your credential also has conversations:read. Never substitute the widget’s siteId.
3. Run the first five examples below in order. Replace SOURCE_ID with your channel ID, and ARTICLE_ID/AUDIENCE_ID with each earlier result’s data.id. Replace the login URL and connect sign-in before publishing.
4. Use list_kb_articles to review changes. Only run a reorder after collecting the complete unfiltered list, including drafts. Refresh your lists after successful writes.

Each example shows the tool name and its arguments. Upsert fields go directly in arguments; update tools put changed fields inside updates. These are tool-call inputs, not an HTTP request to the MCP endpoint.

{
  "name": "upsert_kb_category",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "externalId": "billing",
    "name": "Billing",
    "position": 0
  }
}

{
  "name": "upsert_kb_article",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "externalId": "billing-guide",
    "title": "Manage billing",
    "body": "## Find your invoices\n\nOpen **Settings → Billing** in your account.",
    "bodyFormat": "markdown",
    "categoryExternalId": "billing",
    "status": "draft"
  }
}

{
  "name": "create_kb_audience",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "name": "Pro customers",
    "rules": {
      "match": "all",
      "conditions": [
        {
          "trait": "plan",
          "op": "in",
          "value": [
            "pro",
            "business"
          ]
        }
      ]
    }
  }
}

{
  "name": "update_help_center",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "updates": {
      "enabled": true,
      "title": "Acme Help Center",
      "audience": "verified",
      "audienceId": "AUDIENCE_ID",
      "signInUrl": "https://app.example.com/login"
    }
  }
}

{
  "name": "update_kb_article",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "articleId": "ARTICLE_ID",
    "updates": {
      "audience": "verified",
      "audienceId": "AUDIENCE_ID",
      "status": "published"
    }
  }
}

{
  "name": "list_kb_articles",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "page": 1,
    "limit": 100,
    "updatedSince": "2026-09-01T00:00:00Z"
  }
}

{
  "name": "reorder_kb_articles",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "ids": [
      "ARTICLE_ID_1",
      "ARTICLE_ID_2"
    ]
  }
}

{
  "name": "update_kb_audience",
  "arguments": {
    "sourceId": "SOURCE_ID",
    "audienceId": "AUDIENCE_ID",
    "updates": {
      "name": "Paid customers"
    }
  }
}