Content Publishing API

Authorized server applications can query and publish official-site knowledge articles and news, and query knowledge-page readership analytics. New content is published directly to the COS content snapshot and served through the existing site APIs and pages.

1. Endpoints and credentials

Production API origin: https://project.xiaotunqifu.com. All operations use HTTPS, POST and Content-Type: application/json.

All endpoints share the same credentials: the assigned KNOWLEDGE_RELEASE_SECRET_ID and KNOWLEDGE_RELEASE_SECRET_KEY. The key is a 64-character hexadecimal string representing 32 bytes. Configure credentials on your own server; web pages never hold them.

2. Encryption and authentication (all endpoints)

Requests and successful responses use AES-256-GCM. The plaintext is UTF-8 JSON; each encryption uses a fresh random 12-byte IV and a 16-byte authentication tag. iv, ciphertext and tag use standard padded Base64, with the tag separate from the ciphertext.

The request JSON envelope contains:

The AAD is the UTF-8 encoding of these lines, joined with \n, with no trailing newline. path is the full endpoint path from the table in section 1, without origin, query string or trailing slash. Each endpoint binds its AAD to its own path: a request encrypted for one endpoint is rejected by another:

BW-RELEASE-V1
request
POST
{path}
{secretId}
{timestamp}
{nonce}

A successful response is {"code":0,"status":200,"data":{...encrypted envelope...}}. Take data and decrypt it with the same key; the second AAD line becomes response, the timestamp is the one from the response, and everything else is unchanged. The response nonce matches the request. Verify the GCM tag and confirm the Secret ID, nonce and timestamp before using the result. HTTP errors return an unencrypted error object with message and status.

Each nonce may be used only once. On timeout or retry, regenerate the nonce, timestamp and IV while keeping the article ID and content identical. The Node.js Crypto documentation covers GCM, AAD and authentication tags.

3. Error handling (all endpoints)

4. List knowledge articles POST /api/openapi/knowledge/list

Input (JSON before encryption):

{"page":1,"size":20}

The decrypted result contains version, page, size, total and records. Each record has id, routeSlug, aliases, hash and zh/en metadata (title, summary, category, tags, updatedAt); bodies are not included. The Chinese URL is /faq/{routeSlug} and the English URL is /en/faq/{routeSlug}.

5. Create a knowledge article POST /api/openapi/knowledge/create

Input:

{
  "id": "faq-api-crm-approval-guide",
  "zh": {
    "q": "CRM 审批流程如何设计？",
    "summary": "从审批角色、权限和记录追溯规划 CRM 审批。",
    "category": "软件定制",
    "tags": ["CRM", "审批流程"],
    "updatedAt": "2026-09-24T10:00:00+08:00",
    "a": "## 审批角色\n\n先确定发起人、审批人和可见范围。"
  },
  "en": {
    "q": "How to design CRM approval workflows",
    "summary": "Plan approval roles, permissions and an auditable history for your CRM.",
    "category": "Custom Software",
    "tags": ["CRM", "Approvals"],
    "updatedAt": "2026-09-24T10:00:00+08:00",
    "a": "## Approval roles\n\nDefine who submits, who approves and who can view each request."
  }
}

This endpoint only creates. Retrying with the same ID and identical content is safe; the same ID with different content returns 409, and a URL conflicting with an existing article or topic returns 409.

Decrypted result example:

{
  "id": "faq-api-crm-approval-guide",
  "version": "64-character release digest",
  "created": true,
  "published": true,
  "status": "complete",
  "pending": [],
  "urls": {
    "zh": "/faq/how-to-design-crm-approval-workflows",
    "en": "/en/faq/how-to-design-crm-approval-workflows"
  }
}

published: true means the COS release succeeded; status: complete means search and website-cache synchronization finished. With status: pending, pending contains search or website-cache, and resubmitting the identical article resumes synchronization. A duplicate submission returns created: false. On timeout or 503 the outcome may be uncertain; retry with the original ID and content.

6. Knowledge analytics POST /api/openapi/knowledge/statistics

Query the readership of boilingwater.cn knowledge pages over a selected period, with Chinese and English paths counted separately.

Input (pass {} for defaults):

Decrypted result example:

{
  "generatedAt": "2026-09-27T02:00:00.000Z",
  "site": "boilingwater.cn",
  "timezone": "Asia/Shanghai",
  "startDate": "2026-09-24",
  "endDate": "2026-09-26",
  "startedAt": "2026-09-01T01:00:00.000Z",
  "visitorsStartedAt": "2026-09-23T01:00:00.000Z",
  "visitorsComplete": true,
  "page": 1,
  "size": 10,
  "sortBy": "views",
  "sortOrder": "desc",
  "total": 1,
  "totalPages": 1,
  "records": [{
    "path": "/faq/example", "title": "示例文章", "locale": "zh",
    "views": 12, "visitors": 8, "durationMs": 240000, "averageMs": 20000
  }]
}

total is the number of matching pages; pages beyond the range return empty records. The full date range is aggregated before filtering, sorting and pagination; ties order by path and missing metrics sort last. Statistics keep updating as visits continue, so cross-page queries are not a frozen snapshot.

Views come from the site's browser analytics and are not merged with legacy article counters; heartbeats and retries do not add views. Duration only counts visible time reported while the page is visible, attributed to the visit's start day; averageMs = durationMs / views, rounded to milliseconds, and null when there are no samples. Statistics include all collected traffic without bot filtering.

visitors deduplicates browser identities across the selected dates; one visitor viewing the same page repeatedly counts once. It is not a count of real people and per-page visitor counts cannot be summed into a site-wide figure. Visitor counting starts from the collection start visitorsStartedAt (null when never collected). A range covering the start day or earlier returns visitorsComplete=false with visitors=null; missing history is not treated as zero. Compare visitor counts only over complete ranges after the start; today's figures still grow. startedAt is the overall browser-analytics start; data earlier than that is incomplete.

This endpoint only returns knowledge paths with collected data in the period, which may include historical pages; it is not the list of currently published articles — use list for article metadata. Invalid filters return HTTP 400; an invalid date range returns HTTP 422. Queries never publish or modify articles.

7. List news POST /api/openapi/news/list

Paged metadata of official-site news (the insights channel), sorted by createTime and id descending.

Input:

The decrypted result contains version, page, size, total and records. Each record is the metadata of one news article: id, title, description, image, type, flag, status, siteStatus, siteHiddenStatus, wxStatus, appStatus, createTime, updateTime, labels, plus optional legacy fields such as url, feedId and contentType. The body (content) is not included. Records with flag=0 are deleted (retained but not displayed); status=0 means unlisted.

8. Create a news article POST /api/openapi/news/create

Input:

{
  "id": "8001790000000000000",
  "type": 1,
  "title": "【今日资讯】示例主标题",
  "description": "本期 5 条，覆盖平台规则与产品动态。",
  "image": "https://file.boilingwater.cn/website/news/2026-09-27-example-cover.png",
  "labels": ["日资讯"],
  "markdown": "## 主资讯\n\n正文内容。"
}

This endpoint only creates. Retrying with the same ID and identical content is safe (created: false); the same ID with different content returns 409; a concurrent publication returns 409 — retry later with identical content. On timeout or 503 the outcome may be uncertain; retry with the original ID and content.

Decrypted result example:

{
  "id": "8001790000000000000",
  "version": "64-character snapshot digest",
  "created": true,
  "published": true,
  "urls": { "zh": "/article/8001790000000000000/1", "en": "/en/article/8001790000000000000/1" },
  "record": { "id": "8001790000000000000", "title": "…", "content": "<h2>主资讯</h2>…" }
}

URL rules: types 1/2/3 produce /article/{id}/{type}, type 4 produces /info/{id}; the English URL adds the /en prefix. record is the complete stored record including the rendered HTML body.

After publishing:

• The news is written to the same COS snapshot that serves all existing news. The running Server refreshes within about 30 seconds and serves it through /api/news and the insights pages; the site sitemap reads the news API dynamically, so no extra update is needed.
• To keep repository source backups, save the returned record as website/src/content/news/{id}.json (that directory is the news source-backup directory).
• This endpoint only creates; use news.update for status changes (withdrawal, unlisting, relisting) — do not modify the COS snapshot directly.

9. Update news status POST /api/openapi/news/update

Update the display and withdrawal status of a published news article. Only status fields are accepted; content fields such as title, body, type and createTime cannot be changed here. Typical uses: withdrawal, unlisting, per-channel visibility and relisting.

Input:

At least one of the six status fields (flag, status, siteStatus, siteHiddenStatus, wxStatus, appStatus) is required; no other fields are accepted. A full withdrawal usually passes flag: 0, status: 0 and siteStatus: 0 together; passing only status: 0 hides the article from lists while the detail page remains reachable. flag is the shared deletion state — when a record also serves the mini-program/App, do not zero the other channels for a website-only withdrawal.

{"id":"8001790000000000000","flag":0,"status":0,"siteStatus":0}

Decrypted result example:

{
  "id": "8001790000000000000",
  "version": "64-character snapshot digest",
  "updated": true,
  "published": true,
  "record": { "id": "8001790000000000000", "flag": 0, "status": 0, "updateTime": "2026-09-28T09:00:00+08:00" }
}

updated: false means the target status already matches the current state — a no-op that creates no new version, so identical requests are safe to retry. An unknown ID returns 404; a concurrent publication returns 409 — retry later; on timeout or 503 retry with the identical request (status changes are idempotent). Status changes take effect through the /api/news lists and details within about 30 seconds.

10. Complete Node.js example

Download release-client.mjs — it performs request encryption, the HTTP call and response decryption on Node.js 24. With credentials in the environment:

import { readFile } from 'node:fs/promises';
import { releaseRequest } from './release-client.mjs';

// Knowledge actions: list / create / statistics.
// News actions: news.list / news.create.
console.log(await releaseRequest('list', { page: 1, size: 20 }));
console.log(await releaseRequest('news.list', { page: 1, size: 20 }));

// article.json follows section 5, news.json follows section 8; run only when ready to publish.
const article = JSON.parse(await readFile('./article.json', 'utf8'));
console.log(await releaseRequest('create', article));
const news = JSON.parse(await readFile('./news.json', 'utf8'));
console.log(await releaseRequest('news.create', news));

Set KNOWLEDGE_RELEASE_BASE_URL to use another configured API environment. The function also accepts a third argument { baseUrl, secretId, secretKey }.