Content API

Toast exposes a public API for reading published content without authentication. Use it to build custom frontends, headless sites, or content integrations.

Base URL

All public endpoints are under /api/public/ or /api/site:

https://your-toast-api.example.com/api/public/content
https://your-toast-api.example.com/api/site

No API key or authentication is required.

List Published Content

Retrieve a paginated list of published posts and pages.

GET /api/public/content

Query Parameters

Parameter	Type	Default	Description
`page`	number	`1`	Page number (1-indexed)
`limit`	number	`10`	Items per page (1-100)
`type`	string	—	Filter by content type: `post` or `page`
`include`	string	—	Include computed fields: `computed_excerpt`

Example Request

curl "https://api.example.com/api/public/content?type=post&limit=5&include=computed_excerpt"

Example Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "slug": "welcome-to-toast",
      "title": "Welcome to Toast",
      "excerpt": "An introduction to the Toast publishing platform.",
      "computedExcerpt": "An introduction to the Toast publishing platform...",
      "body": { "type": "doc", "content": [] },
      "contentType": "post",
      "publishedAt": "2025-01-15T09:00:00.000Z",
      "featureImage": "https://cdn.example.com/images/welcome.jpg",
      "metaTitle": "Welcome to Toast",
      "metaDescription": "An introduction to the Toast publishing platform.",
      "ogImage": null
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 5,
      "pages": 3,
      "total": 12
    }
  }
}

Response Fields

Field	Type	Description
`id`	string (UUID)	Unique identifier
`slug`	string	URL-friendly slug (e.g., `welcome-to-toast`)
`title`	string	Content title
`excerpt`	string \| null	Author-provided excerpt
`computedExcerpt`	string \| null	Auto-generated excerpt (only with `include=computed_excerpt`)
`body`	object	Content body as TipTap JSON
`contentType`	string	`"post"` or `"page"`
`publishedAt`	string	ISO 8601 timestamp
`featureImage`	string \| null	Feature image URL
`metaTitle`	string \| null	SEO title override
`metaDescription`	string \| null	SEO description override
`ogImage`	string \| null	Open Graph image URL

Get Content by Slug

Retrieve a single published content item by its slug.

GET /api/public/content/:slug

Path Parameters

Parameter	Type	Description
`slug`	string	Content slug (lowercase alphanumeric with hyphens: `my-post`)

Query Parameters

Parameter	Type	Description
`include`	string	Include computed fields: `computed_excerpt`

Example

curl "https://api.example.com/api/public/content/welcome-to-toast"

Returns a single content object with the same fields as the list endpoint.

Site Metadata

Retrieve site-level information for rendering headers, footers, and SEO tags.

GET /api/site

Example Request

curl "https://api.example.com/api/site"

Example Response

{
  "name": "My Publication",
  "description": "A blog about interesting things.",
  "logo": "https://cdn.example.com/logo.png",
  "icon": "https://cdn.example.com/icon.png",
  "coverImage": "https://cdn.example.com/cover.jpg",
  "accentColor": "#4f46e5",
  "timezone": "America/New_York",
  "locale": "en",
  "metaTitle": "My Publication — Interesting Things",
  "metaDescription": "A blog about interesting things.",
  "ogImage": "https://cdn.example.com/og.jpg"
}

Response Fields

Field	Type	Description
`name`	string	Site name
`description`	string \| null	Site description
`logo`	string \| null	Site logo URL
`icon`	string \| null	Favicon/icon URL
`coverImage`	string \| null	Cover image URL
`accentColor`	string \| null	Brand color (hex)
`timezone`	string	IANA timezone
`locale`	string	Language locale
`metaTitle`	string \| null	SEO title for the site homepage
`metaDescription`	string \| null	SEO description
`ogImage`	string \| null	Default Open Graph image

Capabilities

Check which optional features are enabled on a Toast instance.

GET /api/capabilities

Example Response

{
  "collaboration": {
    "enabled": true,
    "config": { "appId": "abc123" }
  },
  "ai": {
    "enabled": false,
    "config": null
  },
  "storage": {
    "enabled": true,
    "config": {
      "maxUploadSize": 10485760,
      "allowedTypes": ["image/jpeg", "image/png", "image/gif", "image/webp", "image/svg+xml"]
    }
  },
  "email": {
    "enabled": true,
    "config": null
  }
}

Use this endpoint to conditionally enable features in your frontend (e.g., hide the image upload button when storage is disabled).

Content Body Format

The body field contains content as TipTap JSON — a ProseMirror-based document format. Each node has a type and optional content array:

{
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": { "level": 1 },
      "content": [{ "type": "text", "text": "Hello World" }]
    },
    {
      "type": "paragraph",
      "content": [{ "type": "text", "text": "This is a paragraph." }]
    }
  ]
}

To render this in your frontend, use a TipTap-compatible renderer:

React: @tiptap/react with EditorContent in read-only mode
Plain HTML: @tiptap/html with generateHTML()
Custom: Walk the JSON tree and map node types to your own components

Building a Custom Frontend

A typical integration fetches site metadata once and content per page:

const API = 'https://api.example.com';

// Fetch site metadata (cache this — it rarely changes)
const site = await fetch(`${API}/api/site`).then((r) => r.json());

// Fetch paginated posts
const posts = await fetch(`${API}/api/public/content?type=post&limit=10`).then((r) => r.json());

// Fetch a single post by slug
const post = await fetch(`${API}/api/public/content/${slug}`).then((r) => r.json());

Pagination

Use the meta.pagination object to build page navigation:

const { page, pages, total } = posts.meta.pagination;

// Next page
if (page < pages) {
  const next = await fetch(`${API}/api/public/content?page=${page + 1}&limit=10`).then((r) =>
    r.json()
  );
}

Server-Side Rendering with HTML Routes

Toast also renders content as HTML at the root URL for simple use cases:

Route	Description
`GET /`	Homepage with paginated published posts (HTML)
`GET /:slug`	Single content page by slug (HTML)

These HTML routes are suitable for simple sites that don't need a custom frontend. If a UUID is provided instead of a slug, the server redirects to the canonical slug URL.

API Reference

For complete OpenAPI schemas, request/response details, and all authenticated endpoints, see the API Reference.

Content API

On this page