API reference
Public endpoints used by the SDK, including config fetch, event reporting, public content and the key model.
Base URL https://api.soobro.com/v1. Public endpoints authenticate with the site public key and check the Origin allowlist; write endpoints need the server secret key or an API key.
GET /sdk/config
GET /sdk/config?site=pk_live_xxx&path=/blog/hello&locale=enResponse (excerpt):
{
"data": {
"site": { "publicKey": "pk_live_xxx", "brand": { "name": "Acme" }, "defaultLocale": "zh-CN", "locales": ["zh-CN", "en"], "urlStrategy": "path-prefix" },
"rule": { "id": "rule_01", "pageType": "article", "title": "{title} | Acme", "description": "{summary}", "canonical": "https://example.com/en/blog/hello", "noindex": false, "og": {}, "twitter": {} },
"jsonLd": [],
"hreflang": [{ "locale": "en", "hreflang": "en", "href": "https://example.com/en/blog/hello" }],
"webmcp": { "enabled": true, "tools": ["site_search"] },
"version": "1.4.0"
}
}Edge cached with max-age=300, invalidated on publish.
POST /sdk/events
{ "site": "pk_live_xxx", "events": [{ "type": "page_view", "path": "/blog/hello", "locale": "en", "ruleId": "rule_01", "ts": "2026-11-02T03:00:00Z" }] }Up to 100 events per request; aggregated statistics only, no cookies.
Public content endpoints
| Method | Path | Description |
|---|---|---|
| GET | /public/sites/{publicKey}/articles?locale=&categorySlug= | Published article list |
| GET | /public/sites/{publicKey}/articles/{slug}?locale= | Article detail with JSON-LD, source and related |
| GET | /public/sites/{publicKey}/categories?locale= | Category tree |
| GET | /public/sites/{publicKey}/search?locale=&q= | Site search |
Keys
| Key | Purpose | Where |
|---|---|---|
pk_live_… public key | Config fetch, events, public content | Safe in the frontend |
sk_live_… secret key | Server-side SSR fetch, signed requests | Server only |
| API key | Console Settings → API keys, scoped by permission and site | Third-party integrations |
After rotating the secret key the previous key stays valid for a 24-hour grace period.
Errors
The error body is { "error": { "code", "message", "requestId" } }; common codes are NOT_FOUND (wrong key), RATE_LIMITED and VALIDATION_FAILED.