openapi: 3.0.3
info:
  title: djangocms-rest Breadcrumbs 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: Breadcrumbs
  description: Page breadcrumb trails
paths:
  /{language}/breadcrumbs/:
    get:
      operationId: breadcrumbs_retrieve
      summary: Breadcrumbs (root)
      description: Returns the breadcrumb trail from the root for the given language.
      tags:
      - Breadcrumbs
      parameters:
      - $ref: '#/components/parameters/language'
      - $ref: '#/components/parameters/preview'
      responses:
        '200':
          description: Breadcrumb navigation nodes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NavigationNode'
  /{language}/breadcrumbs/{path}/:
    get:
      operationId: breadcrumbs_path_retrieve
      summary: Breadcrumbs by path
      description: Returns the breadcrumb trail to the specified page path.
      tags:
      - Breadcrumbs
      parameters:
      - $ref: '#/components/parameters/language'
      - name: path
        in: path
        required: true
        description: URL path of the target page
        schema:
          type: string
      - $ref: '#/components/parameters/preview'
      responses:
        '200':
          description: Breadcrumb navigation nodes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NavigationNode'
  /{language}/breadcrumbs/{start_level}/:
    get:
      operationId: breadcrumbs_level_retrieve
      summary: Breadcrumbs from level
      description: Returns the breadcrumb trail starting from the given level.
      tags:
      - Breadcrumbs
      parameters:
      - $ref: '#/components/parameters/language'
      - $ref: '#/components/parameters/start_level'
      - $ref: '#/components/parameters/preview'
      responses:
        '200':
          description: Breadcrumb navigation nodes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NavigationNode'
  /{language}/breadcrumbs/{start_level}/{path}/:
    get:
      operationId: breadcrumbs_level_path_retrieve
      summary: Breadcrumbs from level by path
      description: Returns the breadcrumb trail from the given level for the specified page path.
      tags:
      - Breadcrumbs
      parameters:
      - $ref: '#/components/parameters/language'
      - $ref: '#/components/parameters/start_level'
      - name: path
        in: path
        required: true
        description: URL path of the target page
        schema:
          type: string
      - $ref: '#/components/parameters/preview'
      responses:
        '200':
          description: Breadcrumb navigation nodes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NavigationNode'
components:
  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'
    start_level:
      name: start_level
      in: path
      required: true
      description: Starting breadcrumb level
      schema:
        type: integer
        default: 0
    language:
      name: language
      in: path
      required: true
      description: Language code (e.g. "en", "de", "fr")
      schema:
        type: string
        example: en
  schemas:
    NavigationNode:
      type: object
      description: A navigation menu node, optionally with nested children
      properties:
        namespace:
          type: string
          nullable: true
          description: Menu namespace (for apphook menus)
        title:
          type: string
          description: Display title for the menu item
        url:
          type: string
          format: uri
          nullable: true
          description: Absolute frontend URL for the menu item
        api_endpoint:
          type: string
          format: uri
          nullable: true
          description: API URL to fetch full page detail for this menu item
        visible:
          type: boolean
          description: Whether this node is visible in the menu
        selected:
          type: boolean
          description: Whether this node represents the current page
        attr:
          type: object
          nullable: true
          description: Additional attributes from the menu template tag (e.g. is_home, auth_required)
          additionalProperties: true
        level:
          type: integer
          nullable: true
          description: Nesting level of this menu node (0 = root)
        children:
          type: array
          items:
            $ref: '#/components/schemas/NavigationNode'
          description: Child navigation nodes
      required:
      - title
      - visible
      - selected
externalDocs:
  description: djangocms-rest Documentation
  url: https://djangocms-rest.readthedocs.io/