Table Of Contents
Who is this for
Summary
This page will document SCOS REST API routes and related endpoints for custom integrations. There is no published endpoint catalogue yet — check Social Amplification technical docs for webhook payload examples until this reference is completed.
API and End points that codebase registers
Auth note: The token is the Brighter X API Token (brighter_api_token option), passed as header X-Brighter-Token (not brighter-x-token. )
Token is managed in Site Essentials → API Settings.
1. brighter-core/v1 — External / GPT / MCP
Base: /wp-json/brighter-core/v1/
Auth: X-Brighter-Token required on every route (Brighter_API_Auth::verify_token)
No per-endpoint on/off toggle — routes register automatically if the post type exists.
Content list endpoints (same shape for all)
| Route | When available | Purpose |
|---|---|---|
GET /posts | Always (if post exists) | Paginated blog posts |
GET /pages | Always | Paginated pages |
GET /faqs | If faq CPT registered | Paginated FAQ posts |
GET /our-work | If folio CPT exists (BW sites) | Portfolio items |
GET /kb | If kb CPT exists (BW) | Knowledge base articles |
GET /news | If news CPT exists (BW) | News articles |
GET /project | If projects CPT exists (GS) | Project posts |
Query params: page, per_page (max 10), status (publish / draft / any)
Response per item (Phase 1 — minimal, not full post body):
id,title,excerpt,url,status- Plus pagination:
total,total_pages,current_page,per_page,has_more
Does not currently return full content, dates, featured image, categories, or SCOS fields on these list routes. A richer format_content_item() exists in code but is unused.
GET /scos
Purpose: CAR / strategy data for a single post or page (mirrors window.brighterSCOS).
Query: url (path or full URL) or post_id
Sample fields (~5):
car.cluster,car.topic,car.intent,car.purpose,car.maturity- Special extras:
pillar,service_pathway,content_plan,google_index_status,search_intent_goal,car.metrics(word count, reading time, link counts),tracking.ga4_id
Uses legacy bw_* meta keys internally (not the newer scos_* keys everywhere).
Social amplification + image routes (same namespace, same token)
| Route | Method | Purpose |
|---|---|---|
/social-amplification/inventory | GET | All publishable content for social workflows |
/social-amplification/talking-points | GET | Post framing / talking point library |
/social-amplification/content-types | GET | Content type taxonomy list |
/social-amplification/generate-prompt | GET | Structured JSON for Make.com / AI caption pipeline |
/social-amplification/create-shortlink | POST | Create YOURLS shortlink with UTM |
/image-optimization/get-data | GET | Post + image metadata for AI image optimisation |
Sample data per route:
- inventory —
id,title,url,post_type,content_type,date - talking-points —
name,context,example,cta_example,word_count_min/max - generate-prompt —
source_material,source_tldr,framing_options,context(title/type/purpose/intent),count_h2 - create-shortlink — returns
shorturl,keyword,destination_url(+ platform/format in request) - image-optimization/get-data —
content(plain text),tldr,featured_image,attached_images(url, alt, dimensions, caption)
2. bw-social/v1 — Internal amplification pipeline
Auth: secret param must match bw_social_webhook_secret — not X-Brighter-Token.
| Route | Method | Purpose |
|---|---|---|
/amplify | POST | Run amplification pipeline for one post |
/backfill | POST | Batch amplify projects posts by IDs or date range |
Params: post_id + secret (amplify); secret + post_ids or date_from/date_to + limit (backfill)
Returns: pipeline result — scheduled posts, errors per post, etc.
Used by Publish_Hook loopback and admin backfill UI.
3. site-essentials/v1 — Editor-only (Gutenberg / meta box)
Auth: current_user_can('edit_posts') — WP session, not X-Brighter-Token.
Explicitly not for external API consumers.
| Route | Method | Purpose |
|---|---|---|
/faqs | GET | All published FAQs for FAQ Selector block |
/faqs | POST | Create draft stub FAQ from Content Architecture intent-goal picker |
/faqs/search | GET | Keyword search (?q=; ?context=intent_goal includes drafts) |
FAQ item fields: id, question/title, answer, schema_answer, topic, status, edit_url, incomplete
4. Not REST, but public URL endpoints (SEO module)
| URL | Purpose |
|---|---|
/sitemap.xml | SCOS sitemap index |
/sitemap-{posttype}.xml | Per post-type sitemaps |
/llms.txt | Virtual LLM instructions file (if enabled) |
/robots.txt | Custom robots (if enabled) |
These are rewrite/virtual-file routes, not register_rest_route.
5. Reserved namespaces (whitelisted, no routes in code)
Tweaks module whitelists these for unauthenticated access when REST is locked down:
/wp-json/brighter//wp-json/brighter-x/
No register_rest_route calls exist for either namespace yet — placeholders only.
6. Endpoint restrictions — WordPress Tweaks module
Site Essentials → WordPress Tweaks (not a separate “perf module”, but includes performance + security groups).
Security tweaks that affect API access
| Toggle | Effect |
|---|---|
Restrict REST API to Logged-In Users (disable_rest_api) | Returns 401 for all unauthenticated REST requests except whitelisted prefixes: /wp-json/wc/, /wp-json/brighter/, /wp-json/brighter-core/, /wp-json/brighter-x/ |
Restrict REST API Users Endpoint (restrict_rest_users) | Removes /wp/v2/users for unauthenticated requests |
Disable Inbound Embeds (disable_embeds_inbound) | Removes WordPress oEmbed REST route (wp_oembed_register_route) |
Remove REST API Discovery Links (remove_rest_api_links) | Strips <link rel="https://api.w.org/"> from <head> — cosmetic, doesn’t block endpoints |
| Disable XML-RPC | Blocks /xmlrpc.php POST requests |
Important gap
When Restrict REST API is on:
brighter-core/v1/*stays reachable (whitelisted) — still needsX-Brighter-Tokenat route levelbw-social/v1/*andsite-essentials/v1/*are not whitelisted → unauthenticated loopback/internal calls to amplify/backfill would get 401 before the secret check runs
What you cannot configure per endpoint
- No admin toggle to enable/disable individual
brighter-core/v1routes - Optional routes (
/our-work,/kb,/news,/project) appear only when the CPT is registered on that site - Token generate/delete is the only API access gate (
brighter_api_token)
7. Stale docs to be aware of
site-essentials/Views/settings-api.php lists under brighter-core/v1:
GET /faqs/search— actually lives atsite-essentials/v1/faqs/search(editor auth)GET /faqs/export— not implemented anywhere in the codebase
Quick reference — auth by namespace
| Namespace | Auth |
|---|---|
brighter-core/v1 | X-Brighter-Token |
bw-social/v1 | secret body param |
site-essentials/v1 | Logged-in editor (edit_posts) |
wp/v2/* | WP default (cookie/app password) — subject to Tweaks restrictions |
brighter/, brighter-x/ | Reserved — nothing registered yet |
If you want this turned into a maintained spec doc or want the Tweaks whitelist updated to include bw-social/v1, switch to Agent mode and I can do that.