REST: WordPress Push-Content (/api/wordpress/push-content)

This page describes the incoming REST endpoint of the cockpitOS Dashboard, through which a registered WordPress website (e.g., with the cockpitOS plugin) can send shops, events, news, offers, services, and static pages to the central database.

Implementation in the Monorepo: apps/dashboard/src/app/api/wordpress/push-content/route.ts

Note on Base URL

Replace {DASHBOARD_ORIGIN} with the public URL of your dashboard instance (e.g., https://dashboard.example.com). Locally often http://localhost:3000.

Overview

Aspect	Details
Method	POST
Path	/api/wordpress/push-content
Authentication	HTTP Header Authorization: Bearer <apiKey>
API Key	The website API key of the WordPress instance, as stored in cockpitOS under WordPress management (WordPressWebsite.apiKey in the database)
Content-Type	application/json
CORS	Access-Control-Allow-Origin: * (Preflight OPTIONS is supported)

Without a valid key, the API responds with 401; if no matching website entry exists, with 404.

Request Body

The body is a JSON object. All top-level fields are optional. You can send any combination (only news, only shops, etc.).

{
  "shops": [],
  "events": [],
  "news": [],
  "offers": [],
  "services": [],
  "pages": []
}

shops (Array)

For each entry, the following fields are evaluated (additional keys are ignored):

Field	Type	Description
id	string (optional)	If set and present in the same center → Update, otherwise Create
name	string	Required (empty → entry is skipped)
category	string	Default: "Other"
description, floor, location, logo, phone, email, website, openingHours	string or null	Optional
status	string	Default: "Active"
shopChainId / chainId	string (UUID, optional)	Links the shop with an existing Shop Chain (ShopChain). Invalid/missing UUID → error entry in data.errors, shop is not saved.
chainName, shopChainName, brandName, kette, marke, …	string (optional)	AI/editor-friendly aliases: chain is searched by name (case insensitive); if missing, it is created (only additive data, category from shop or chainCategory / chainCategoryId).
chainCategory, kettenKategorie	string (optional)	Only for newly created chain: category name (matched against cockpit categories).
chainCategoryId, kettenKategorieId	string (UUID, optional)	Only for new chain: direct Category UUID.
clearShopChain, unlinkFromChain, standaloneShop, einzelshop	boolean (optional)	true → remove link to the chain (Standalone Shop).
modus / shopTyp	string (optional)	Values like single, standalone, without chain → like above disconnect.
agencyosId, externalId, clientReference	string (optional)	Stored in shop metadata under agencyosPushId; same value in the same center → Update instead of duplicate (sensible for AgencyOS; WordPress usually ignores).

The same Shop Push Logic is also used for AgencyOS Content Push.

events (Array)

Field	Type	Description
id	string (optional)	Update if ID exists in center
title	string	Required
startDate, endDate	string (ISO) / date	Optional; Default: startDate = now, endDate = one hour later
description, location, image	string or null	Optional
status	string	Default: "Active"

Internally, source is set to wordpress.

news (Array)

Field	Type	Description
id	string (optional)	Update if ID exists in center
title	string	Required
excerpt, summary, content, author, category, image	string or null	Optional
publishDate	string (ISO) / date	Optional; Default: current date
status	string	Default: "Published"

Internally, source is set to wordpress.

offers (Array)

Field	Type	Description
id	string (optional)	Update if ID exists in center
title	string	Required
startDate, endDate	string (ISO) / date	Optional; Default: endDate = 7 days after startDate
description, discount, image	string or null	Optional
status	string	Default: "Active"

Internally, source is set to wordpress.

services (Array)

Field	Type	Description
id	string (optional)	Update if ID exists in center
name	string	Required
category, description, floor, location, phone, email, website, openingHours	string or null	Optional
status	string	Default: "Active"

pages (Array)

Static WordPress pages (e.g., directions, house rules) for context (e.g., chatbot). They are not mirrored as normal CMS page entities like in the website tab, but stored in WordPressWebsite.staticPages.

Field	Type	Description
slug	string
title	string
content	string	Will be truncated to 10,000 characters

Additional Logic: If a page titled "Opening Hours" is included (recognized by title/slug), and the field openingHours is still empty in the center, a truncated text (HTML tags removed, max. 500 characters) will be adopted into the center.

Response

Success (HTTP 200)

{
  "success": true,
  "data": {
    "summary": {
      "shops": 0,
      "events": 0,
      "news": 0,
      "offers": 0,
      "services": 0
    },
    "errors": ["optional: error messages per record"]
  },
  "message": "Push-Content processed"
}

errors is omitted if no individual errors occurred. In case of partial failure, individual records may fail while others are still processed.

The associated WordPress website receives an updated lastSync; in case of errors, lastError (truncated) can be set.

Errors

HTTP	Meaning
401	No Authorization: Bearer header
404	No WordPressWebsite with this API key
400	Invalid JSON
500	Unexpected server error

Example: curl

curl -sS -X POST "${DASHBOARD_ORIGIN}/api/wordpress/push-content" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORDPRESS_WEBSITE_API_KEY" \
  -d '{
    "news": [
      {
        "title": "Sample News",
        "excerpt": "Short text",
        "content": "<p>HTML content</p>",
        "status": "Published"
      }
    ]
  }'

Related Endpoints

• Register / link website: POST /api/wordpress/websites (Dashboard session or API key matching in header with body – see apps/dashboard/src/app/api/wordpress/websites/route.ts).
• Embedding configuration (public with website key): GET /api/wordpress/embed-config – see comment in apps/dashboard/src/app/api/wordpress/embed-config/route.ts.
• Outgoing notifications to external systems (not for writing to cockpit): Webhooks – see Integration & Webhooks.

Further API Documentation

A complete OpenAPI reference of all dashboard endpoints is still in planning; this endpoint is currently the centrally documented interface for content from WordPress to Cockpit.