Admin API

This endpoint requires admin-level roles (platform_admin, tenant_admin, or system_admin). Accessible via the API gateway at /v1/platform/*.

CMS API

Manage content pages, reusable blocks, media assets, and publishing workflows.

Overview

Attribute	Value
Base Path	`/api/v1/cms`
Authentication	Bearer Token
Required Roles	`content_creator`, `marketing`, `manager`, `tenant_admin`, `platform_admin`, `system_admin`, `super_admin`

Pages

List Pages

Retrieve all content pages.

GET /api/v1/cms/pages

Query Parameters

Parameter	Type	Description
`tenant_id`	uuid	Filter by tenant
`status`	string	`draft`, `published`, `archived`
`type`	string	Page type filter
`parent_id`	string	Filter by parent page
`search`	string	Search title/content
`page`	integer	Page number
`limit`	integer	Results per page

Response

{
  "data": [
    {
      "id": "page_001",
      "slug": "about-us",
      "title": "About Us",
      "type": "static",
      "status": "published",
      "parent_id": null,
      "template": "default",
      "meta": {
        "description": "Learn about our company",
        "keywords": ["about", "company", "team"]
      },
      "version": 5,
      "published_at": "2026-01-20T10:00:00Z",
      "updated_at": "2026-01-24T15:00:00Z",
      "author": {
        "id": "user_001",
        "name": "John Smith"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}

Page Status Values

Status	Description
`draft`	Work in progress
`review`	Pending review
`published`	Live on site
`scheduled`	Scheduled to publish
`archived`	No longer active

Get Page

Retrieve page details with content.

GET /api/v1/cms/pages/{page_id}

Query Parameters

Parameter	Type	Description
`version`	integer	Specific version
`include_blocks`	boolean	Include block content

Response

{
  "id": "page_001",
  "slug": "about-us",
  "title": "About Us",
  "type": "static",
  "status": "published",
  "template": "default",
  "content": {
    "body": "<p>Welcome to our restaurant...</p>",
    "blocks": [
      {
        "id": "block_001",
        "type": "hero",
        "data": {
          "title": "Our Story",
          "image_url": "https://..."
        }
      },
      {
        "id": "block_002",
        "type": "text",
        "data": {
          "content": "Founded in 2020..."
        }
      }
    ]
  },
  "meta": {
    "title": "About Us | Restaurant Name",
    "description": "Learn about our company",
    "og_image": "https://..."
  },
  "settings": {
    "show_in_nav": true,
    "nav_order": 2,
    "allow_comments": false
  },
  "versions": [
    {"version": 5, "created_at": "2026-01-24T15:00:00Z", "author": "John Smith"},
    {"version": 4, "created_at": "2026-01-20T10:00:00Z", "author": "John Smith"}
  ]
}

Create Page

POST /api/v1/cms/pages

Request Body

{
  "slug": "new-page",
  "title": "New Page",
  "type": "static",
  "template": "default",
  "content": {
    "body": "<p>Page content here...</p>",
    "blocks": []
  },
  "meta": {
    "description": "Page description for SEO"
  },
  "status": "draft"
}

Update Page

PUT /api/v1/cms/pages/{page_id}

Request Body

{
  "title": "Updated Title",
  "content": {
    "body": "<p>Updated content...</p>"
  },
  "create_version": true
}

Publish Page

Publish a draft page.

POST /api/v1/cms/pages/{page_id}/publish

Request Body

{
  "publish_at": null,
  "notify_subscribers": false
}

Unpublish Page

Take page offline.

POST /api/v1/cms/pages/{page_id}/unpublish

Delete Page

DELETE /api/v1/cms/pages/{page_id}

Revert to Version

Restore a previous version.

POST /api/v1/cms/pages/{page_id}/revert

Request Body

{
  "version": 3
}

Blocks

List Blocks

Get reusable content blocks.

GET /api/v1/cms/blocks

Response

{
  "data": [
    {
      "id": "block_001",
      "name": "Homepage Hero",
      "type": "hero",
      "global": true,
      "data": {
        "title": "Welcome",
        "subtitle": "Best food in town",
        "image_url": "https://...",
        "cta_text": "Order Now",
        "cta_url": "/order"
      },
      "used_on_pages": ["page_001", "page_002"],
      "updated_at": "2026-01-24T10:00:00Z"
    }
  ]
}

Block Types

Type	Description
`hero`	Hero banner with image
`text`	Rich text content
`image`	Single image
`gallery`	Image gallery
`video`	Video embed
`menu`	Menu display
`hours`	Business hours
`location`	Location/map
`testimonials`	Customer reviews
`cta`	Call to action
`form`	Contact form
`html`	Custom HTML

Create Block

POST /api/v1/cms/blocks

Request Body

{
  "name": "Special Offer Banner",
  "type": "cta",
  "global": true,
  "data": {
    "title": "20% Off Today",
    "description": "Use code SAVE20",
    "button_text": "Order Now",
    "button_url": "/order?promo=SAVE20",
    "background_color": "#FF5722"
  }
}

Update Block

PUT /api/v1/cms/blocks/{block_id}

Delete Block

DELETE /api/v1/cms/blocks/{block_id}

Assets

List Assets

Get media library assets.

GET /api/v1/cms/assets

Query Parameters

Parameter	Type	Description
`type`	string	`image`, `video`, `document`, `audio`
`folder`	string	Folder path
`search`	string	Search filename

Response

{
  "data": [
    {
      "id": "asset_001",
      "filename": "hero-image.jpg",
      "type": "image",
      "mime_type": "image/jpeg",
      "size_bytes": 245000,
      "dimensions": {
        "width": 1920,
        "height": 1080
      },
      "url": "https://cdn.example.com/assets/hero-image.jpg",
      "thumbnail_url": "https://cdn.example.com/assets/hero-image_thumb.jpg",
      "folder": "/images/hero",
      "alt_text": "Restaurant interior",
      "uploaded_at": "2026-01-15T10:00:00Z",
      "uploaded_by": "user_001"
    }
  ]
}

Upload Asset

Upload a new media file.

POST /api/v1/cms/assets

Request Body (multipart/form-data)

file: [binary data]
folder: /images/menu
alt_text: Delicious burger photo

Response

{
  "asset_id": "asset_002",
  "url": "https://cdn.example.com/assets/burger.jpg",
  "thumbnail_url": "https://cdn.example.com/assets/burger_thumb.jpg",
  "size_bytes": 185000,
  "processing": false
}

Get Asset

GET /api/v1/cms/assets/{asset_id}

Update Asset Metadata

PUT /api/v1/cms/assets/{asset_id}

Request Body

{
  "alt_text": "Updated alt text",
  "folder": "/images/featured"
}

Delete Asset

DELETE /api/v1/cms/assets/{asset_id}

Create Folder

POST /api/v1/cms/assets/folders

Request Body

{
  "path": "/images/seasonal",
  "name": "Seasonal Images"
}

GET /api/v1/cms/menus

Response

{
  "data": [
    {
      "id": "menu_main",
      "name": "Main Navigation",
      "location": "header",
      "items": [
        {
          "id": "item_001",
          "label": "Home",
          "url": "/",
          "type": "page",
          "page_id": "page_home",
          "children": []
        },
        {
          "id": "item_002",
          "label": "Menu",
          "url": "/menu",
          "type": "page",
          "children": [
            {"id": "item_003", "label": "Lunch", "url": "/menu/lunch"},
            {"id": "item_004", "label": "Dinner", "url": "/menu/dinner"}
          ]
        }
      ]
    }
  ]
}

PUT /api/v1/cms/menus/{menu_id}

Request Body

{
  "items": [
    {
      "label": "Home",
      "url": "/",
      "type": "page",
      "page_id": "page_home"
    },
    {
      "label": "Order Online",
      "url": "/order",
      "type": "custom",
      "highlight": true
    }
  ]
}

Templates

List Templates

Get available page templates.

GET /api/v1/cms/templates

Response

{
  "data": [
    {
      "id": "template_default",
      "name": "Default",
      "description": "Standard page layout",
      "preview_url": "https://...",
      "regions": ["header", "content", "sidebar", "footer"],
      "default": true
    },
    {
      "id": "template_landing",
      "name": "Landing Page",
      "description": "Full-width landing page",
      "regions": ["hero", "content", "cta"],
      "default": false
    }
  ]
}

Workflows

Get Workflow Status

GET /api/v1/cms/pages/{page_id}/workflow

Response

{
  "page_id": "page_001",
  "current_status": "review",
  "workflow": "editorial",
  "stages": [
    {"stage": "draft", "completed": true, "completed_at": "2026-01-23T10:00:00Z"},
    {"stage": "review", "completed": false, "assigned_to": "user_002"},
    {"stage": "approved", "completed": false},
    {"stage": "published", "completed": false}
  ],
  "comments": [
    {
      "id": "comment_001",
      "user": "Editor Jane",
      "text": "Please update the pricing section",
      "created_at": "2026-01-24T09:00:00Z"
    }
  ]
}

Submit for Review

POST /api/v1/cms/pages/{page_id}/workflow/submit

Request Body

{
  "message": "Ready for review",
  "reviewer_ids": ["user_002"]
}

Approve Page

POST /api/v1/cms/pages/{page_id}/workflow/approve

Reject Page

POST /api/v1/cms/pages/{page_id}/workflow/reject

Request Body

{
  "reason": "Needs more detail in the FAQ section"
}

Scheduled Publishing

List Scheduled Content

GET /api/v1/cms/scheduled

Response

{
  "data": [
    {
      "id": "schedule_001",
      "page_id": "page_005",
      "page_title": "Summer Menu",
      "action": "publish",
      "scheduled_at": "2026-06-01T00:00:00Z",
      "created_by": "user_001"
    }
  ]
}

Schedule Publication

POST /api/v1/cms/pages/{page_id}/schedule

Request Body

{
  "action": "publish",
  "scheduled_at": "2026-06-01T00:00:00Z",
  "notify": true
}

Site Settings

Get Site Settings

GET /api/v1/cms/settings

Response

{
  "site_name": "Restaurant Name",
  "tagline": "Best food in town",
  "logo_url": "https://...",
  "favicon_url": "https://...",
  "primary_color": "#FF5722",
  "secondary_color": "#2196F3",
  "social_links": {
    "facebook": "https://facebook.com/...",
    "instagram": "https://instagram.com/...",
    "twitter": "https://twitter.com/..."
  },
  "footer_text": "© 2026 Restaurant Name",
  "analytics_id": "GA-XXXXXXX"
}

Update Site Settings

PUT /api/v1/cms/settings

Webhooks

Event	Description
`cms.page_created`	New page created
`cms.page_published`	Page published
`cms.page_unpublished`	Page taken offline
`cms.page_deleted`	Page deleted
`cms.asset_uploaded`	New asset uploaded
`cms.workflow_submitted`	Submitted for review
`cms.workflow_approved`	Page approved

Error Responses

Status	Code	Description
400	`slug_taken`	Page slug already exists
400	`invalid_template`	Template not found
403	`workflow_required`	Must use workflow
404	`page_not_found`	Page ID not found
409	`version_conflict`	Version conflict

CMS Guide - CMS setup guide
Content Workflows - Publishing workflows
Assets Guide - Media management

Overview​

Pages​

List Pages​

Page Status Values​

Get Page​

Create Page​

Update Page​

Publish Page​

Unpublish Page​

Delete Page​

Revert to Version​

Blocks​

List Blocks​

Block Types​

Create Block​

Update Block​

Delete Block​

Assets​

List Assets​

Upload Asset​

Get Asset​

Update Asset Metadata​

Delete Asset​

Create Folder​

Menus (Navigation)​

List Navigation Menus​

Update Navigation Menu​

Templates​

List Templates​

Workflows​

Get Workflow Status​

Submit for Review​

Approve Page​

Reject Page​

Scheduled Publishing​

List Scheduled Content​

Schedule Publication​

Site Settings​

Get Site Settings​

Update Site Settings​

Webhooks​

Error Responses​

Related Documentation​

Overview

Pages

List Pages

Page Status Values

Get Page

Create Page

Update Page

Publish Page

Unpublish Page

Delete Page

Revert to Version

Blocks

List Blocks

Block Types

Create Block

Update Block

Delete Block

Assets

List Assets

Upload Asset

Get Asset

Update Asset Metadata

Delete Asset

Create Folder

Menus (Navigation)

List Navigation Menus

Update Navigation Menu

Templates

List Templates

Workflows

Get Workflow Status

Submit for Review

Approve Page

Reject Page

Scheduled Publishing

List Scheduled Content

Schedule Publication

Site Settings

Get Site Settings

Update Site Settings

Webhooks

Error Responses

Related Documentation