Content API

Create and manage news articles, announcements, and editorial content.

GET/v1/content

List all content items. Results are paginated.

Query Parameters

page

integerPage number (default: 1)

limit

integerItems per page, max 100 (default: 20)

shopId

uuidFilter by shop ID

contentType

stringFilter by type: news, announcement, store_opening, editorial, promotion

active

booleanFilter by active status

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "uuid",
        "contentType": "news",
        "title": "Spring Collection Now Available",
        "summary": "Our new spring collection has arrived...",
        "body": "Full article content here...",
        "imageUrl": "https://example.com/spring-collection.jpg",
        "imageAlt": "Spring collection preview",
        "linkUrl": "https://yourshop.com/spring",
        "linkText": "Shop the collection",
        "authorName": "Style Team",
        "authorAvatarUrl": "https://example.com/avatar.jpg",
        "isFeatured": false,
        "isPinned": false,
        "publishedAt": "2026-02-06T10:00:00Z",
        "expiresAt": null,
        "isActive": true,
        "source": "api",
        "createdAt": "2026-02-06T10:00:00Z",
        "shop": {
          "id": "uuid",
          "slug": "your-shop",
          "name": "Your Shop"
        }
      }
    ],
    "total": 50,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

POST/v1/content

Create a new content item. Content can be associated with a shop or be general (mall-wide).

Request Body

contentType

stringContent type: news, announcement, store_opening, editorial, promotion (default: news)

titlerequired

stringContent title (max 500 chars)

summary

stringShort summary (max 1000 chars)

body

stringFull content body, supports markdown (max 50000 chars)

imageUrl

stringMain image URL

imageAlt

stringAlt text for image

linkUrl

stringCall-to-action link URL

linkText

stringCall-to-action link text

authorName

stringAuthor display name

authorAvatarUrl

stringAuthor avatar URL

shopId

uuidAssociated shop ID (optional)

shopSlug

stringAssociated shop slug (alternative to shopId)

publishedAt

datetimeWhen to publish (ISO 8601 format)

expiresAt

datetimeWhen content expires (ISO 8601 format)

isFeatured

booleanFeature this content (default: false)

isPinned

booleanPin to top of feed (default: false)

Example Request

curl -X POST https://api.thevirtualmall.co.uk/v1/content \
  -H "Authorization: Bearer tvm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "news",
    "title": "Spring Collection Now Available",
    "summary": "Our new spring collection has arrived with fresh styles",
    "body": "We are excited to announce our spring collection...",
    "imageUrl": "https://yourshop.com/images/spring-collection.jpg",
    "imageAlt": "Spring 2026 Collection",
    "linkUrl": "https://yourshop.com/spring",
    "linkText": "Shop Now",
    "shopSlug": "your-shop",
    "publishedAt": "2026-03-01T00:00:00Z"
  }'

Response

{
  "success": true,
  "data": {
    "id": "content_abc123",
    "contentType": "news",
    "title": "Spring Collection Now Available",
    "status": "needs_review",
    "shop": {
      "id": "uuid",
      "slug": "your-shop",
      "name": "Your Shop"
    },
    "createdAt": "2026-02-06T10:30:00Z"
  }
}

GET/v1/content/:id

Retrieve a single content item by ID.

PUT/v1/content/:id

Update an existing content item. Only include fields you want to change. Updated content will require re-review before going live.

DELETE/v1/content/:id

Delete a content item. This action cannot be undone.

Content Types

newsGeneral news articles and updates

announcementImportant announcements and notices

store_openingNew store opening announcements

editorialEditorial content, guides, and how-tos

promotionPromotional content highlighting deals

Required Scopes

content:readRequired for GET endpoints

content:writeRequired for POST, PUT, DELETE endpoints