OpenAPI Specification
openapi: 3.0.3
info:
title: djangocms-rest Breadcrumbs Pages API
description: Read-only REST/JSON API for Django CMS that enables decoupled frontend applications to consume CMS-managed content. Built on Django REST Framework with OpenAPI 3 schema generation via drf-spectacular. Supports multi-language, multi-site, draft/preview access, and is compatible with Redis/Memcached caching.
version: 1.0.0
contact:
name: Django CMS Association
email: info@django-cms.org
url: https://www.django-cms.org/en/
license:
name: BSD 3-Clause
url: https://github.com/django-cms/djangocms-rest/blob/main/LICENSE
x-logo:
url: https://www.django-cms.org/static/img/django-cms-logo.svg
servers:
- url: https://example.com/api
description: Default server (customize per deployment)
tags:
- name: Pages
description: CMS page content and tree structure
paths:
/{language}/pages-tree/:
get:
operationId: page_tree_list_retrieve
summary: Page tree
description: Returns all pages for the given language as a nested tree structure.
tags:
- Pages
parameters:
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/preview'
responses:
'200':
description: Nested page tree
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PageMeta'
'404':
description: Language not found or no pages available
/{language}/pages-list/:
get:
operationId: page_list_retrieve
summary: Flat page list
description: Returns a paginated flat list of all pages for the given language.
tags:
- Pages
parameters:
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/preview'
- name: limit
in: query
description: Number of results to return per page
schema:
type: integer
- name: offset
in: query
description: The initial index from which to return the results
schema:
type: integer
responses:
'200':
description: Paginated page list
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedPageList'
'404':
description: Language not found
/{language}/pages/:
get:
operationId: page_root_retrieve
summary: Root page detail
description: Retrieve the root (home) page for the given language, including its placeholders.
tags:
- Pages
parameters:
- $ref: '#/components/parameters/language'
- $ref: '#/components/parameters/preview'
- $ref: '#/components/parameters/html'
responses:
'200':
description: Page content with placeholders
content:
application/json:
schema:
$ref: '#/components/schemas/PageContent'
'404':
description: Page not found
/{language}/pages/{path}/:
get:
operationId: page_detail_retrieve
summary: Page detail by path
description: Retrieve a specific page by its URL path for the given language, including its placeholders.
tags:
- Pages
parameters:
- $ref: '#/components/parameters/language'
- name: path
in: path
required: true
description: URL path of the page (e.g. "blog/my-post")
schema:
type: string
- $ref: '#/components/parameters/preview'
- $ref: '#/components/parameters/html'
responses:
'200':
description: Page content with placeholders
content:
application/json:
schema:
$ref: '#/components/schemas/PageContent'
'404':
description: Page not found
/{language}/page_search/:
get:
operationId: page_search_retrieve
summary: Search pages
description: Search pages by a query string for the given language.
tags:
- Pages
parameters:
- $ref: '#/components/parameters/language'
- name: q
in: query
required: true
description: Search query string
schema:
type: string
- $ref: '#/components/parameters/preview'
responses:
'200':
description: List of matching pages
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PageList'
'404':
description: Language not found
components:
schemas:
PageContent:
allOf:
- $ref: '#/components/schemas/PageBase'
description: Full page detail including placeholder content
properties:
placeholders:
type: array
items:
$ref: '#/components/schemas/Placeholder'
description: Ordered list of placeholders defined by the page template
Placeholder:
type: object
description: A placeholder containing structured plugin content
properties:
slot:
type: string
description: Template slot name for this placeholder
label:
type: string
description: Human-readable label for the placeholder
language:
type: string
description: Language code of the content
content:
type: array
items:
type: object
description: Nested list of serialized plugin data objects. Each object has a "plugin_type" field identifying its type, plus plugin-specific properties.
details:
type: string
format: uri
description: API URL to retrieve this placeholder directly
html:
type: string
default: ''
description: Server-rendered HTML output (only present when ?html=1 is requested)
required:
- slot
- label
- language
- details
PageMeta:
allOf:
- $ref: '#/components/schemas/PageBase'
description: Page with nested children for tree representation
properties:
children:
type: array
items:
$ref: '#/components/schemas/PageMeta'
default: []
description: Child pages in the tree
PageBase:
type: object
description: Core fields shared by all page representations
properties:
title:
type: string
maxLength: 255
description: Page title
page_title:
type: string
maxLength: 255
description: Page title used in <title> tag (falls back to title)
menu_title:
type: string
maxLength: 255
description: Title displayed in navigation menus (falls back to title)
meta_description:
type: string
description: SEO meta description
redirect:
type: string
maxLength: 2048
nullable: true
description: Redirect URL if configured
absolute_url:
type: string
format: uri
description: Absolute frontend URL for the page
path:
type: string
maxLength: 200
description: Relative URL path of the page
details:
type: string
maxLength: 2048
description: API endpoint URL for this page
is_home:
type: boolean
description: Whether this is the home/root page
login_required:
type: boolean
description: Whether the page requires authentication to view
in_navigation:
type: boolean
description: Whether the page appears in navigation menus
soft_root:
type: boolean
description: Whether the page is a soft root for navigation
template:
type: string
maxLength: 100
description: Template file used to render this page
xframe_options:
type: string
maxLength: 50
description: X-Frame-Options header value
limit_visibility_in_menu:
type: boolean
nullable: true
default: false
description: Whether menu visibility is restricted
language:
type: string
maxLength: 10
description: Language code of this page content
example: en
languages:
type: array
items:
type: string
description: All languages this page is available in
is_preview:
type: boolean
default: false
description: Whether this response is in preview/draft mode
application_namespace:
type: string
maxLength: 200
nullable: true
description: Application namespace if the page is an apphook
creation_date:
type: string
format: date-time
description: When the page was created
changed_date:
type: string
format: date-time
description: When the page was last modified
PageList:
allOf:
- $ref: '#/components/schemas/PageBase'
description: Flat page representation used in list and search results
PaginatedPageList:
type: object
description: Paginated list of pages
properties:
count:
type: integer
description: Total number of pages
next:
type: string
format: uri
nullable: true
description: URL to next page of results
previous:
type: string
format: uri
nullable: true
description: URL to previous page of results
results:
type: array
items:
$ref: '#/components/schemas/PageList'
parameters:
preview:
name: preview
in: query
description: Set to 1 or true to include draft/unpublished content (requires appropriate permissions)
schema:
type: string
enum:
- '0'
- '1'
- 'true'
- 'false'
html:
name: html
in: query
description: Set to 1 to include server-rendered HTML for placeholder content
schema:
type: string
enum:
- '0'
- '1'
language:
name: language
in: path
required: true
description: Language code (e.g. "en", "de", "fr")
schema:
type: string
example: en
externalDocs:
description: djangocms-rest Documentation
url: https://djangocms-rest.readthedocs.io/