CBGAccount developer documentation
Public and token-protected APIs for reading, checking, saving, and publishing SEO-ready CBGAccount blog stories.
Publishing workflow
External systems should follow the same flow as the admin editor: read categories and tags, save a draft with all SEO fields, run the publishing check, fix blocking items, then publish.
https://www.cbgaccount.comMedia URL Basehttps://media.cbgaccount.comAuthentication
Published posts, categories, tags, authors, RSS, sitemap, robots, and OpenAPI JSON are publicly readable.
SEO checks, saving posts, publishing, unpublishing, deleting, and taxonomy writes use API Tokens. Third-party systems never log in to the admin backend; a CBGAccount admin creates a scoped token once and gives it to the integration owner.
Authorization: Bearer cbg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx X-API-Token: cbg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Contract basics
JSON APIs return the same wrapper shape used by the admin backend. Treat code=0000 as success; all other codes should be handled as business or validation failures.
{
"code": "0000",
"message": "success",
"data": "{ endpoint specific payload }"
}Use blog:read for read audit, blog:write for SEO checks, drafts, taxonomy writes, author writes, and media uploads, and blog:publish for publishing, unpublishing, deleting, and status operations.
Authorization: Bearer <API_TOKEN> X-API-Token: <API_TOKEN>
Each token plus IP is limited to 120 requests per minute. Token usage, required scope, path, status, message, IP, and latency are visible in the admin Token logs.
HTTP 200 + business error code when the request is rejected by API policy.
The public docs cover external /api/v1/blog/* contracts. Third-party callers use token auth only. Token creation, token rotation, online debugging, webhook receiver setup, Search Console actions, and moderation remain admin-only.
Go to Blog API documentation and Token Management in the admin backend. The raw token is displayed only once after creation, then only a masked value is stored for listing. External users receive the token value, not an admin account.
Give external readers blog:read only. Give importers blog:write for drafts and SEO checks. Only trusted publishing systems should receive blog:publish.
Never ship a write or publish token in browser JavaScript. Store it in a backend secret manager or environment variable and rotate it when staff, vendors, or integrations change.
Recommended sequence
Best practices
A third-party CMS can publish the same article shape as the admin editor when it saves these fields explicitly. Empty canonical means self-canonical; CloudFlare-ImgBed HTTPS URLs can be saved directly.
language, title, summary, contentHtml, coverImage, coverAlt, categoryId, tagIds, authorId, slug, alternateSlug, seoTitle, seoDescription, canonicalUrl, robots, indexable, ogTitle, ogDescription, ogImage, answerSummary, keyTakeaways, faqBlocks, relatedProductIds, status
Endpoint coverage
Paginated public articles for blog lists, archives, internal link pickers, and external readers.
/api/v1/blog/postscurl "https://www.cbgaccount.com/api/v1/blog/posts?language=en¤t=1&size=10"
{
"code": "0000",
"message": "success",
"data": "Result<PageBlogPostRes>"
}Full SEO article payload: HTML body, meta fields, canonical, robots, Open Graph, author, tags, TOC, related posts, and engagement counts.
/api/v1/blog/posts/{slug}curl "https://www.cbgaccount.com/api/v1/blog/posts/account-infrastructure-growth-workflows?language=en"
{
"code": "0000",
"message": "success",
"data": "Result<BlogPostRes>, 301 for old slug redirects"
}Preflight check using the same rules as the admin editor: score, AEO score, canPublish, blocking items, generated slug, title, description, excerpt, and TOC.
/api/v1/blog/posts/checkcurl -X POST -H "Authorization: Bearer <API_TOKEN>" -H "content-type: application/json" -d @draft.json "https://www.cbgaccount.com/api/v1/blog/posts/check"
{
"code": "0000",
"message": "success",
"data": "Result<BlogSeoCheckRes>"
}Persists every editor SEO field and content block. Create a draft with id empty, update an article with id present.
/api/v1/blog/posts/savecurl -X POST -H "Authorization: Bearer <API_TOKEN>" -H "content-type: application/json" -d @post-save.json "https://www.cbgaccount.com/api/v1/blog/posts/save"
{
"code": "0000",
"message": "success",
"data": "Result<BlogPostRes>"
}Runs the SEO check again, publishes the saved draft, refreshes public discovery outputs, and dispatches webhook events.
/api/v1/blog/posts/{id}/publishcurl -X POST -H "Authorization: Bearer <API_TOKEN>" "https://www.cbgaccount.com/api/v1/blog/posts/1/publish"
{
"code": "0000",
"message": "success",
"data": "Result<BlogPostRes>"
}Status operation for admin-style workflows. Use publish for normal releases; use this mainly for taking posts offline.
/api/v1/blog/posts/operatecurl -H "Authorization: Bearer <API_TOKEN>" "https://www.cbgaccount.com/api/v1/blog/posts/operate?id=1&status=2"
{
"code": "0000",
"message": "success",
"data": "Result<boolean>"
}Deletes a post and removes it from public discovery. Prefer unpublishing when SEO history should be preserved.
/api/v1/blog/posts/deletecurl -H "Authorization: Bearer <API_TOKEN>" "https://www.cbgaccount.com/api/v1/blog/posts/delete?id=1"
{
"code": "0000",
"message": "success",
"data": "Result<boolean>"
}Returns clap count, approved comment count, and approved public comments without private moderation fields.
/api/v1/blog/posts/{id}/engagementcurl "https://www.cbgaccount.com/api/v1/blog/posts/1/engagement"
{
"code": "0000",
"message": "success",
"data": "Result<BlogEngagementRes>"
}Adds a clap-style recommendation with a client idempotency key.
/api/v1/blog/posts/{id}/reactionscurl -X POST -H "content-type: application/json" -d '{"reactionKey":"clap","clientKey":"browser-session-1","count":1}' "https://www.cbgaccount.com/api/v1/blog/posts/1/reactions"{
"code": "0000",
"message": "success",
"data": "Result<BlogEngagementRes>"
}Creates a pending comment. Public responses hide email, IP, user agent, spam reason, and internal post title.
/api/v1/blog/posts/{id}/commentscurl -X POST -H "content-type: application/json" -d '{"authorName":"Alex","authorEmail":"[email protected]","content":"Useful guide."}' "https://www.cbgaccount.com/api/v1/blog/posts/1/comments"{
"code": "0000",
"message": "success",
"data": "Result<BlogPublicCommentRes>"
}Enabled public categories for primary grouping and crawlable category pages.
/api/v1/blog/categoriescurl "https://www.cbgaccount.com/api/v1/blog/categories"
{
"code": "0000",
"message": "success",
"data": "Result<BlogCategoryRes[]>"
}Creates or updates a category with localized names and descriptions.
/api/v1/blog/categories/savecurl -X POST -H "Authorization: Bearer <API_TOKEN>" -H "content-type: application/json" -d '{"nameEn":"Growth Playbooks","nameZh":"增长业务剧本","slug":"growth-playbooks","status":1}' "https://www.cbgaccount.com/api/v1/blog/categories/save"{
"code": "0000",
"message": "success",
"data": "Result<BlogCategoryRes>"
}Enabled tags grouped by language so public topic pages and admin filters stay aligned.
/api/v1/blog/tagscurl "https://www.cbgaccount.com/api/v1/blog/tags?language=en"
{
"code": "0000",
"message": "success",
"data": "Result<BlogTagRes[]>"
}Creates or updates a language-aware tag.
/api/v1/blog/tags/savecurl -X POST -H "Authorization: Bearer <API_TOKEN>" -H "content-type: application/json" -d '{"language":"all","nameEn":"Account Operations","nameZh":"账号业务运营","slug":"account-operations","status":1}' "https://www.cbgaccount.com/api/v1/blog/tags/save"{
"code": "0000",
"message": "success",
"data": "Result<BlogTagRes>"
}Creates or updates the structured author profile used by author pages, publication cards, and Person JSON-LD. Use author text only as a fallback; authorId gives stronger SEO output.
/api/v1/blog/authors/savecurl -X POST -H "Authorization: Bearer <API_TOKEN>" -H "content-type: application/json" -d '{"language":"en","slug":"cbgaccount-editorial-team","name":"CBGAccount Editorial Team","title":"Account operations editorial team","status":1}' "https://www.cbgaccount.com/api/v1/blog/authors/save"{
"code": "0000",
"message": "success",
"data": "Result<BlogAuthorRes>"
}Enabled structured authors for public author cards, author pages, and Person JSON-LD.
/api/v1/blog/authorscurl "https://www.cbgaccount.com/api/v1/blog/authors?language=en"
{
"code": "0000",
"message": "success",
"data": "Result<BlogAuthorRes[]>"
}Public author profile with bio, credentials, avatar, social links, and post count.
/api/v1/blog/authors/{slug}curl "https://www.cbgaccount.com/api/v1/blog/authors/cbgaccount-editorial-team?language=en"
{
"code": "0000",
"message": "success",
"data": "Result<BlogAuthorRes>"
}Paginated published posts linked to an enabled author.
/api/v1/blog/authors/{slug}/postscurl "https://www.cbgaccount.com/api/v1/blog/authors/cbgaccount-editorial-team/posts?language=en¤t=1&size=10"
{
"code": "0000",
"message": "success",
"data": "Result<PageBlogPostRes>"
}Returns the public publication mark used by blog home, article pages, author cards, and publication cards. It never exposes admin-only SEO, AI, Search Console, or media provider secrets.
/api/v1/blog/publication-settingscurl "https://www.cbgaccount.com/api/v1/blog/publication-settings"
{
"code": "0000",
"message": "success",
"data": "Result<BlogPublicationSettingsRes>"
}Returns public account/business resource categories so external publishers can build the same resource picker as the admin editor.
/api/v1/blog/resources/categoriescurl -H "Authorization: Bearer <API_TOKEN>" "https://www.cbgaccount.com/api/v1/blog/resources/categories"
{
"code": "0000",
"message": "success",
"data": "Result<BlogResourceCategoryRes[]>"
}Searches active public account/business resources. Use the returned id, name, description, category, and price to build a readable resource card, then set relatedProductIds on the post. Product descriptions can contain storefront HTML, so strip tags for picker summaries and escape any inserted card text. Product prices use the main storefront storage unit: display usdtPrice as usdtPrice / 10000. The crawlable public resource URL is /en/products/{id}-{slugified nameEn} for English content and /cn/products/{id}-{slugified nameZh or product} for Chinese content.
/api/v1/blog/resources/searchcurl -X POST -H "Authorization: Bearer <API_TOKEN>" -H "content-type: application/json" -d '{"current":1,"size":12,"keywords":"regional account","status":1}' "https://www.cbgaccount.com/api/v1/blog/resources/search"{
"code": "0000",
"message": "success",
"data": "Result<PageBlogResourceRes>"
}Uploads cover, body, OG, author, or publication media for external publishing integrations. CBGAccount defaults this workflow to CloudFlare-ImgBed, so data is the final public HTTPS URL and must not be prefixed with the API base URL.
/api/v1/blog/media/uploadcurl -X POST -H "Authorization: Bearer <API_TOKEN>" -F "file=@./cover.webp" "https://www.cbgaccount.com/api/v1/blog/media/upload"
{
"code": "0000",
"message": "success",
"data": "https://media.cbgaccount.com/file/blog-assets/account-infrastructure-growth-workflows.webp"
}RSS 2.0 feed for subscription tools and readers.
/api/v1/blog/rss.xmlcurl "https://www.cbgaccount.com/api/v1/blog/rss.xml?language=en"
{
"code": "0000",
"message": "success",
"data": "application/xml"
}Sitemap mirror for crawlers and integrations. The primary public route is /sitemap.xml.
/api/v1/blog/sitemap.xmlcurl "https://www.cbgaccount.com/api/v1/blog/sitemap.xml"
{
"code": "0000",
"message": "success",
"data": "application/xml"
}Robots directives mirror. The primary public route is /robots.txt.
/api/v1/blog/robots.txtcurl "https://www.cbgaccount.com/api/v1/blog/robots.txt"
{
"code": "0000",
"message": "success",
"data": "text/plain"
}Machine-readable OpenAPI 3.0 document with schemas, request bodies, auth scopes, and responses.
/api/v1/blog/openapi.jsoncurl "https://www.cbgaccount.com/api/v1/blog/openapi.json"
{
"code": "0000",
"message": "success",
"data": "application/json"
}Post body
Leave empty to create a new draft. Send the existing article id to update or publish a saved post.
Determines public route, language-specific tags, alternate links, and localized rendering.
Visible article title and primary H1 source. Use reader language, not internal campaign names.
Public excerpt and fallback meta description. Explain what problem the article solves.
URL short name. Keep it stable after publish; the check endpoint can generate a draft slug.
Slug of the translated counterpart used for bilingual alternates.
Semantic article body. It can include figures, responsive images, videos, tables, quotes, code, FAQ blocks, internal links, and account/resource cards.
Primary visual URL and human-readable alt text. Prefer URLs returned by /api/v1/blog/media/upload; CloudFlare-ImgBed HTTPS URLs can be saved directly.
Primary category for navigation, archive grouping, and related content matching.
Topic tags for public topic pages, recommendations, and internal link discovery.
Bind authorId whenever possible; author text is only a fallback display name.
Search title and description. Blank values can be generated by /posts/check, then saved explicitly.
Canonical URL used when this post should consolidate signals to another official URL.
Indexing controls. Normal publishable posts should be indexable with robots=index,follow.
Open Graph metadata for social sharing and external previews.
Short answer and takeaways used by article summaries, structured content, and reader scanning.
FAQ blocks used in the article body and FAQPage JSON-LD when valid.
Comma-separated real resource ids selected from the resource search API, for example "12,18".
Last expert or editor review timestamp.
0 draft, 1 published, 2 offline.
Examples
Send this body to POST /api/v1/blog/posts/save with status=0 to create a draft that already contains the same SEO fields exposed by the admin editor.
{
"language": "en",
"title": "Account Infrastructure for Global Growth Workflows",
"summary": "How teams use ready-to-operate accounts for marketplace launches, regional access, creator operations, and support workflows.",
"slug": "account-infrastructure-growth-workflows",
"alternateSlug": "account-infrastructure-growth-workflows-zh",
"contentHtml": "<h1>Account Infrastructure for Global Growth Workflows</h1><p>Explain the business use case in the first paragraph.</p><h2>Validate regional access before scaling</h2><p>Add concrete workflow evidence and an internal link.</p><figure><img src=\"https://media.cbgaccount.com/file/blog-assets/account-infrastructure-growth-workflows.webp\" alt=\"Account infrastructure workflow diagram for marketplace launch and regional access\" width=\"1200\" height=\"675\" /></figure><h2>Frequently asked questions</h2>",
"coverImage": "https://media.cbgaccount.com/file/blog-assets/account-infrastructure-growth-workflows.webp",
"coverAlt": "Account infrastructure workflow diagram for marketplace launch and regional access",
"categoryId": 1,
"tagIds": [
1,
2
],
"authorId": 1,
"seoTitle": "Account Infrastructure for Global Growth Workflows | CBGAccount",
"seoDescription": "Learn how account infrastructure supports marketplace launches, regional access, creator operations, and safer support workflows.",
"canonicalUrl": "",
"robots": "index,follow",
"indexable": true,
"ogTitle": "Account Infrastructure for Global Growth Workflows",
"ogDescription": "A practical operating guide for marketplace, regional, creator, and support account workflows.",
"ogImage": "https://media.cbgaccount.com/file/blog-assets/account-infrastructure-growth-workflows.webp",
"answerSummary": "Account infrastructure helps teams validate access, ownership, support, and workflow evidence before scaling account-led operations.",
"keyTakeaways": [
"Map ownership and recovery before launch",
"Keep internal links and evidence visible",
"Review high-value posts after operational changes"
],
"faqBlocks": [
{
"question": "When should a team prepare account infrastructure?",
"answer": "Before launching a new market, creator workflow, support queue, or marketplace operation that depends on repeatable account access."
}
],
"relatedProductIds": "12,18",
"reviewedAt": "2026-05-25 12:00:00",
"status": 0
}POST /api/v1/blog/posts/check does not save data. Use its suggestions to fill slug, meta, excerpt, OG, and table of contents before saving again.
{
"code": "0000",
"message": "success",
"data": {
"score": 92,
"aeoScore": 88,
"canPublish": true,
"scoreSummary": "Ready to publish after confirming the canonical URL and final image alt text.",
"generatedSlug": "account-infrastructure-growth-workflows",
"generatedSeoTitle": "Account Infrastructure for Global Growth Workflows | CBGAccount",
"generatedSeoDescription": "Learn how account infrastructure supports marketplace launches, regional access, creator operations, and support workflows.",
"generatedOgTitle": "Account Infrastructure for Global Growth Workflows",
"generatedExcerpt": "A practical operating guide for account-led growth teams.",
"toc": [
{
"id": "validate-regional-access-before-scaling",
"title": "Validate regional access before scaling",
"level": 2
},
{
"id": "frequently-asked-questions",
"title": "Frequently asked questions",
"level": 2
}
],
"items": [
{
"key": "title-length",
"passed": true,
"severity": "info",
"message": "SEO title length is in range."
},
{
"key": "internal-links",
"passed": true,
"severity": "info",
"message": "The article includes internal links."
}
]
}
}POST /api/v1/blog/posts/{id}/publish runs the SEO check again and only publishes when blocking items pass.
{
"code": "0000",
"message": "success",
"data": {
"id": 42,
"slug": "account-infrastructure-growth-workflows",
"title": "Account Infrastructure for Global Growth Workflows",
"status": 1,
"publishedAt": "2026-05-25 12:30:00",
"canonicalUrl": "https://www.cbgaccount.com/blog/account-infrastructure-growth-workflows",
"robots": "index,follow",
"seoScore": 92,
"sitemapUpdated": true,
"rssUpdated": true,
"webhookQueued": true
}
}Do not publish when code is not 0000. Show message and failedItems to the operator so they can fix the article.
{
"code": "BLOG_SEO_BLOCKED",
"message": "The draft cannot be published because blocking SEO checks failed.",
"data": {
"canPublish": false,
"failedItems": [
"missing-cover-alt",
"thin-content",
"duplicate-slug"
]
}
}Automation
Configure webhook receivers in the admin backend. Public docs describe the contract; the secret and delivery logs stay behind admin login.
X-CBG-Event: blog.post.published X-CBG-Signature: t=1710000000,v1=hex(hmac_sha256(secret, t + "." + rawBody))
Verify the timestamp, raw body, and HMAC before accepting a delivery. Failed deliveries retry at 5, 10, and 15 minute intervals up to five attempts.
/api/admin/blog/webhooks/saveAdmin-only setup endpoint. External developers provide a receiver URL and secret to the CBGAccount admin; they do not log in to the admin backend./api/admin/blog/webhooks/eventsAdmin-only delivery log for status, response body, retry count, and failure diagnosis.Import /api/v1/blog/openapi.json into Postman, Apifox, Swagger UI, or an SDK generator. Use the generated schema as the source of truth for automated tests.
The public page intentionally does not execute token-protected writes. Use the admin API documentation page for online debugging after login.
When the site is published, expose /blog/api and /zh/blog/api on the public internet so partners can read docs without admin access.