Page Spec

The Page Spec is the canonical JSON format for ChatBlocks pages. Every page, manual or AI-generated, is validated against this structure.

Structure


{
  "slug": "my-page",
  "title": "My Page Title",
  "description": "Optional description for SEO",
  "components": [
    {
      "type": "hero",
      "props": {
        "headline": "Welcome"
      }
    },
    {
      "type": "text",
      "props": {
        "content": "Page body here"
      }
    }
  ],
  "theme": {
    "preset": "clean-modern",
    "overrides": {
      "primary": "#ff3333"
    }
  },
  "customCss": ".cb-page h1 { letter-spacing: 0.05em; }",
  "meta": {
    "ogImage": "https://example.com/og.png",
    "favicon": "https://example.com/favicon.ico"
  }
}

Top-level fields

Field	Type	Required	Description
`slug`	string	Yes	URL path segment. 2-60 chars, lowercase alphanumeric + hyphens, cannot start/end with hyphen
`title`	string	No	Page title, max 200 chars
`description`	string	No	SEO description, max 2000 chars
`components`	array	One of `components` or `prompt`	Array of typed component objects, max 50
`prompt`	string	One of `components` or `prompt`	AI generation prompt, max 5000 chars
`model`	string	No	Prompt mode model key: `gpt-5-mini` or `gpt-5.2`
`theme`	object	No	Theme preset and/or overrides
`customCss`	string	No	Scoped CSS, max 10240 chars
`meta`	object	No	Metadata like `ogImage` and `favicon`

Slug rules

Minimum 2 characters, maximum 60
Lowercase letters, numbers, and hyphens only
Must start and end with a letter or number
Regex: ^[a-z0-9][a-z0-9-]*[a-z0-9]$

Schema endpoint

Get the full JSON Schema (draft-2020-12):


GET /api/schema

Useful for external validators, typed clients, and LLM function calling.