API and End points
Reference for SCOS REST endpoints and webhook URLs — documentation shell pending full API listing.
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.