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/