> ## Documentation Index
> Fetch the complete documentation index at: https://docs-slidekit.theduomi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate presentation deck (async)

> Generate a complete presentation deck with multiple slides asynchronously.

**Use this endpoint when:**
- You need to generate multiple slides in one presentation
- You're building complete decks programmatically
- Slides may use different templates

**Workflow:**
1. POST to this endpoint with your slides array
2. Receive `generation_id` immediately (HTTP 202)
3. Poll `GET /presentations/{generation_id}/status` every 2-5 seconds
4. When status is `completed` or `partial`, download from `download_url`

**Slide ordering:** Slides appear in the generated deck in the same order as your `slides` array.

**Mixed templates:** Each slide can use a different `template_slide_id`, allowing you to
combine slides from multiple templates into one deck.

**Per-slide options:** Override deck-level options for specific slides by providing
`options` within individual slide objects.

**Status values:**
- `pending` - Queued for processing
- `processing` - Generation in progress
- `completed` - All slides generated successfully
- `partial` - Some slides succeeded, some failed
- `failed` - Generation failed completely



## OpenAPI

````yaml /openapi/powerpoint-api.json post /api/v1/presentations/generate-deck
openapi: 3.1.0
info:
  title: SlideKit
  description: >-
    A comprehensive API for PowerPoint template management and presentation
    generation
  version: 1.0.0
servers: []
security: []
paths:
  /api/v1/presentations/generate-deck:
    post:
      tags:
        - presentations
      summary: Generate presentation deck (async)
      description: >-
        Generate a complete presentation deck with multiple slides
        asynchronously.


        **Use this endpoint when:**

        - You need to generate multiple slides in one presentation

        - You're building complete decks programmatically

        - Slides may use different templates


        **Workflow:**

        1. POST to this endpoint with your slides array

        2. Receive `generation_id` immediately (HTTP 202)

        3. Poll `GET /presentations/{generation_id}/status` every 2-5 seconds

        4. When status is `completed` or `partial`, download from `download_url`


        **Slide ordering:** Slides appear in the generated deck in the same
        order as your `slides` array.


        **Mixed templates:** Each slide can use a different `template_slide_id`,
        allowing you to

        combine slides from multiple templates into one deck.


        **Per-slide options:** Override deck-level options for specific slides
        by providing

        `options` within individual slide objects.


        **Status values:**

        - `pending` - Queued for processing

        - `processing` - Generation in progress

        - `completed` - All slides generated successfully

        - `partial` - Some slides succeeded, some failed

        - `failed` - Generation failed completely
      operationId: generate_deck_api_v1_presentations_generate_deck_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeckGenerateRequest'
      responses:
        '202':
          description: Generation started - poll status endpoint for progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeckGenerateResponse'
        '422':
          description: Invalid request data
        '429':
          description: Too many pending generation requests
      security:
        - ApiKeyAuth: []
components:
  schemas:
    DeckGenerateRequest:
      properties:
        org_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Org Name
          description: >-
            Organization name. If provided, must match the API key's
            organization. If omitted, the API key's organization is used.
          example: acme-corp
        slides:
          items:
            $ref: '#/components/schemas/DeckSlideInput'
          type: array
          minItems: 1
          title: Slides
          description: >-
            Ordered list of slides to generate. Minimum 1 slide required. Slides
            appear in the deck in this order.
        options:
          $ref: '#/components/schemas/GenerationOptions'
          description: >-
            Default generation options applied to all slides. Individual slides
            can override these by specifying their own `options`.
      additionalProperties: false
      type: object
      required:
        - slides
      title: DeckGenerateRequest
      description: >-
        Request schema for generating a complete presentation deck with multiple
        slides.


        This endpoint processes asynchronously due to the potentially large
        workload.

        It returns immediately with a `generation_id` that you use to poll for
        status.


        **Workflow:**

        1. POST to `/presentations/generate-deck` with this request body

        2. Receive `generation_id` and `status_url` in response

        3. Poll `GET /presentations/{generation_id}/status` until status is
        `completed` or `failed`

        4. Download the generated .pptx from the `download_url` in the status
        response


        **Slides ordering:** Slides appear in the generated deck in the same
        order as the `slides` array.


        **Mixed templates:** Each slide can use a different template slide,
        allowing you to combine

        slides from multiple templates into a single deck.
      example:
        options:
          allow_textbox_reposition: false
          auto_paginate_tables: true
        org_name: acme-corp
        slides:
          - slide_data:
              subtitle: Executive Summary
              title: Q4 2024 Business Review
            template_slide_id: slide_title001
          - slide_data:
              content:
                blocks:
                  - text:
                      bullets:
                        - Revenue grew 25% YoY to $56.6M
                        - Customer base expanded to 1,890 accounts
                        - NPS improved from 72 to 82
                    type: text
              title: Key Highlights
            template_slide_id: slide_content001
          - options:
              auto_paginate_tables: true
              table_min_font_size: 9
            slide_data:
              content:
                blocks:
                  - table:
                      table:
                        rows:
                          - cells:
                              - value: Metric
                              - value: Q3
                              - value: Q4
                              - value: Change
                            is_header: true
                          - cells:
                              - value: Revenue
                              - value: $12.8M
                              - value: $14.2M
                              - value: +11%
                          - cells:
                              - value: Customers
                              - value: 1,620
                              - value: 1,890
                              - value: +17%
                    type: table
              title: Quarterly Performance
            template_slide_id: slide_table001
    DeckGenerateResponse:
      properties:
        generation_id:
          type: string
          title: Generation Id
          description: >-
            Unique identifier for this generation job. Use this to poll status
            and download the result.
          example: gen_abc123def456
        status:
          type: string
          title: Status
          description: Initial status. Always 'pending' for new requests.
          example: pending
        message:
          type: string
          title: Message
          description: Human-readable status message.
          default: Generation started
          example: Generation started. Poll status URL for progress.
        status_url:
          type: string
          title: Status Url
          description: >-
            Full URL to poll for generation status. Convenience field - you can
            also construct this as GET /presentations/{generation_id}/status.
          example: https://api.example.com/api/v1/presentations/gen_abc123def456/status
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Timestamp when the generation request was created.
      type: object
      required:
        - generation_id
        - status
        - status_url
        - created_at
      title: DeckGenerateResponse
      description: >-
        Response schema for async generation requests.


        This response is returned immediately when you POST to
        `/presentations/generate`

        or `/presentations/generate-deck`, and when you PUT to

        `/presentations/{id}/update-charts`. The actual Aspose work happens in
        the

        background.


        **Next steps:**

        1. Save the `generation_id` from this response

        2. Poll `status_url` (or `GET /presentations/{generation_id}/status`)
        every few seconds

        3. When status becomes `completed`, `partial`, or `failed`, generation
        is done

        4. Download from `download_url` in the status response (for `completed`
        or `partial`)
    DeckSlideInput:
      properties:
        template_slide_id:
          type: string
          title: Template Slide Id
          description: >-
            Template slide ID to use for this slide. Can be from any analyzed
            template belonging to your organization.
          example: slide_abc123def456
        slide_data:
          $ref: '#/components/schemas/SlideDataInput'
          description: >-
            Content data for this slide. The structure should match what the
            template slide expects (title, content blocks, tables, etc.).
        options:
          anyOf:
            - $ref: '#/components/schemas/GenerationOptions'
            - type: 'null'
          description: >-
            Per-slide generation options. When provided, these completely
            override the deck-level options for this slide only.
      additionalProperties: false
      type: object
      required:
        - template_slide_id
        - slide_data
      title: DeckSlideInput
      description: >-
        A single slide within a deck generation request.


        Each slide specifies which template slide to use and the content data.

        Different slides can use different template slides from the same or
        different templates.


        **Options inheritance:** If `options` is not provided, the slide
        inherits options from

        the deck-level `options`. If provided, per-slide options completely
        override deck defaults.
    GenerationOptions:
      properties:
        auto_paginate_tables:
          type: boolean
          title: Auto Paginate Tables
          description: >-
            When True, table-only slides whose rows exceed the available slide
            space are automatically split across multiple slides. Each
            continuation slide includes repeated headers. Not supported for
            slides that combine tables with text content.
          default: true
          example: true
        allow_textbox_reposition:
          type: boolean
          title: Allow Textbox Reposition
          description: >-
            When True, textboxes positioned below tables can be moved down to
            give the table more vertical space. Useful for slides with both
            table and text content.
          default: false
          example: false
        table_min_font_size:
          anyOf:
            - type: integer
              maximum: 72
              minimum: 6
            - type: 'null'
          title: Table Min Font Size
          description: >-
            Minimum font size (in points) for table body cells during auto-fit
            optimization. Font will not shrink below this size. If omitted, uses
            the renderer default of 8pt.
          example: 8
        textbox_min_font_size:
          anyOf:
            - type: integer
              maximum: 72
              minimum: 6
            - type: 'null'
          title: Textbox Min Font Size
          description: >-
            Minimum font size (in points) for textbox content during auto-fit.
            Font will not shrink below this size. Default: 8pt.
          example: 8
        show_slide_numbers:
          type: boolean
          title: Show Slide Numbers
          description: >-
            When True, enables PowerPoint's native slide numbering on all
            slides. Slide numbers appear in the footer area of each slide.
          default: false
          example: true
        footer_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Footer Text
          description: >-
            Optional footer text to display on all slides. When provided, footer
            visibility is enabled automatically.
          example: Confidential
        footer_font_size:
          anyOf:
            - type: integer
              maximum: 72
              minimum: 6
            - type: 'null'
          title: Footer Font Size
          description: >-
            Font size (in points) for footer, slide number, and date/time
            placeholders. If not specified, uses the template's default footer
            font size.
          example: 10
        footer_font_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Footer Font Name
          description: >-
            Font name (e.g., 'Arial', 'Century Gothic') for footer, slide
            number, and date/time placeholders. If not specified, uses the
            template's default font.
          example: Arial
      additionalProperties: false
      type: object
      title: GenerationOptions
      description: >-
        Options controlling slide generation behavior.


        These options can be set at deck level (applies to all slides) or
        per-slide

        to override the deck defaults.
      example:
        allow_textbox_reposition: false
        auto_paginate_tables: true
        footer_font_name: Arial
        footer_font_size: 10
        footer_text: Confidential
        show_slide_numbers: true
        table_min_font_size: 8
        textbox_min_font_size: 8
    SlideDataInput:
      properties:
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: Main slide title. Populates the TITLE placeholder in the template.
          example: Q4 2024 Business Review
        subtitle:
          anyOf:
            - type: string
            - type: 'null'
          title: Subtitle
          description: >-
            Slide subtitle. Populates SUBTITLE placeholder (title slides) or
            BODY placeholder (content slides).
          example: Executive Summary
        header:
          anyOf:
            - type: string
            - type: 'null'
          title: Header
          description: Slide header area text.
          example: Confidential
        footer:
          anyOf:
            - type: string
            - type: 'null'
          title: Footer
          description: Slide footer area text.
          example: Page 1 of 10
        footnote:
          anyOf:
            - type: string
            - type: 'null'
          title: Footnote
          description: >-
            Footnote text (e.g., data source, disclaimers). Populates textbox
            containing 'footnote_placeholder' or 'footnote' marker text.
          example: 'Source: Company Research, 2024'
        content:
          anyOf:
            - $ref: '#/components/schemas/Column'
            - items:
                $ref: '#/components/schemas/Column'
              type: array
            - type: 'null'
          title: Content
          description: >-
            Main content area. Pass a single Column for standard layouts, or an
            array of Columns for multi-column layouts.
        slide_format:
          anyOf:
            - $ref: '#/components/schemas/SlideFormat'
            - type: 'null'
          description: >-
            Optional formatting overrides for title, subtitle, body, and textbox
            elements.
      additionalProperties: false
      type: object
      title: SlideDataInput
      description: >-
        Main slide data input schema.


        This is the primary schema for defining slide content. Structure your
        data to match

        your template slide type (title slide, content slide, table slide,
        etc.).


        **Simple slides:** Just provide `title` and/or `subtitle`

        **Content slides:** Add `content` with text blocks, tables, etc.

        **Multi-column:** Pass an array to `content` for side-by-side layouts
      examples:
        - subtitle: Company Performance Overview
          title: Annual Report 2024
        - content:
            blocks:
              - text:
                  bullets:
                    - Revenue grew 25% year-over-year
                    - Expanded to 3 new markets
                    - Launched 5 new products
                type: text
          title: Key Achievements
        - content:
            - blocks:
                - text:
                    bullets:
                      - Manual process
                      - 3 day turnaround
                  type: text
              header: Before
            - blocks:
                - text:
                    bullets:
                      - Automated
                      - 3 hour turnaround
                  type: text
              header: After
          title: 'Comparison: Before vs After'
        - content:
            blocks:
              - table:
                  table:
                    rows:
                      - cells:
                          - value: Region
                          - value: Q4 Revenue
                          - value: YoY Growth
                        is_header: true
                      - cells:
                          - value: North America
                          - value: $12.5M
                          - value: +18%
                      - cells:
                          - value: Europe
                          - value: $8.2M
                          - value: +22%
                      - cells:
                          - value: Asia Pacific
                          - value: $6.1M
                          - value: +35%
                type: table
          title: Revenue by Region
    Column:
      properties:
        header:
          anyOf:
            - type: string
            - type: 'null'
          title: Header
          description: >-
            Optional two-column layout header. Rendered into template textboxes
            marked LHS_header (left-hand side) or RHS_header (right-hand side)
            when those markers are present.
          example: Key Metrics
        blocks:
          items:
            $ref: '#/components/schemas/ContentBlock'
          type: array
          minItems: 1
          title: Blocks
          description: >-
            Content blocks stacked vertically in this column. At least one
            required.
      additionalProperties: false
      type: object
      required:
        - blocks
      title: Column
      description: >-
        A column containing one or more content blocks.


        Blocks are stacked vertically within the column. Use multiple columns
        for

        side-by-side layouts (comparison slides, multi-column content).


        **Single column:** Pass a single Column object to `content`

        **Multi-column:** Pass an array of Column objects to `content`
      examples:
        - blocks:
            - text:
                bullets:
                  - Point 1
                  - Point 2
              type: text
        - blocks:
            - text:
                bullets:
                  - Revenue +25%
                  - Margin +3%
                header: Q4 Results
              type: text
            - text:
                text: All targets exceeded.
              type: text
          header: Performance
    SlideFormat:
      properties:
        title:
          anyOf:
            - $ref: '#/components/schemas/TextFormat'
            - type: 'null'
          description: 'Formatting for slide title. Typical default: bold, 28pt.'
        subtitle:
          anyOf:
            - $ref: '#/components/schemas/TextFormat'
            - type: 'null'
          description: 'Formatting for slide subtitle. Typical default: 18pt.'
        body:
          anyOf:
            - $ref: '#/components/schemas/TextFormat'
            - type: 'null'
          description: 'Formatting for body text. Typical default: 14pt.'
        textbox:
          anyOf:
            - $ref: '#/components/schemas/TextBoxFormat'
            - type: 'null'
          description: >-
            Formatting for textbox content (nested header/text/bullets
            formatting).
      additionalProperties: false
      type: object
      title: SlideFormat
      description: |-
        Slide-level text formatting configuration.

        Apply consistent formatting across slide elements. All fields optional -
        unspecified values inherit from template defaults.
      example:
        subtitle:
          font_size: 20
          italic: true
        textbox:
          bullets:
            font_size: 10
          header:
            bold: true
            font_size: 12
        title:
          bold: true
          font_name: Arial
          font_size: 32
    ContentBlock:
      properties:
        type:
          $ref: '#/components/schemas/ContentType'
          description: >-
            Content type: 'text' or 'table'. Determines which content field is
            used.
          example: text
        text:
          anyOf:
            - $ref: '#/components/schemas/TextBlock'
            - type: 'null'
          description: >-
            Text content (header, paragraph, bullets). Required when
            type='text'.
        table:
          anyOf:
            - $ref: '#/components/schemas/TableContent'
            - type: 'null'
          description: Table content with rows and cells. Required when type='table'.
        chart:
          anyOf:
            - $ref: '#/components/schemas/ChartContent'
            - type: 'null'
          description: Chart content for bar and column charts.
        image:
          anyOf:
            - $ref: '#/components/schemas/ImageContent'
            - type: 'null'
          description: Image content (NOT YET IMPLEMENTED).
        agenda:
          anyOf:
            - $ref: '#/components/schemas/AgendaContent'
            - type: 'null'
          description: Agenda content with section titles and active highlighting.
      additionalProperties: false
      type: object
      required:
        - type
      title: ContentBlock
      description: >-
        A single content block within a column.


        Set `type` to indicate the content type, then provide the corresponding
        content field:

        - `type: "text"` → provide `text` field with TextBlock

        - `type: "table"` → provide `table` field with TableContent


        Only the field matching the `type` will be used; others are ignored.
      examples:
        - text:
            bullets:
              - Point 1
              - Point 2
          type: text
        - text:
            header: Summary
            text: 'Key findings:'
          type: text
        - table:
            table:
              rows:
                - cells:
                    - value: Name
                    - value: Value
                  is_header: true
                - cells:
                    - value: Item 1
                    - value: '100'
          type: table
    TextFormat:
      properties:
        font_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Font Name
        bold:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Bold
        italic:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Italic
        font_size:
          anyOf:
            - type: integer
            - type: 'null'
          title: Font Size
        color:
          anyOf:
            - type: string
            - type: 'null'
          title: Color
        alignment:
          anyOf:
            - type: string
            - type: 'null'
          title: Alignment
        line_spacing:
          anyOf:
            - type: number
            - type: 'null'
          title: Line Spacing
      additionalProperties: false
      type: object
      title: TextFormat
      description: |-
        Text formatting configuration.

        Attributes:
            font_name: Font family name (e.g., "Arial", "Calibri")
            bold: Whether text is bold
            italic: Whether text is italic
            font_size: Font size in points
            color: Text color as hex code (e.g., "#000000")
            alignment: Text alignment ("left", "center", "right")
            line_spacing: Line spacing multiplier (e.g., 1.2 for 20% spacing)
    TextBoxFormat:
      properties:
        header:
          anyOf:
            - $ref: '#/components/schemas/TextFormat'
            - type: 'null'
          description: 'Formatting for textbox headers. Default: bold, 11pt.'
        text:
          anyOf:
            - $ref: '#/components/schemas/TextFormat'
            - type: 'null'
          description: 'Formatting for textbox paragraphs. Default: 10pt.'
        bullets:
          anyOf:
            - $ref: '#/components/schemas/TextFormat'
            - type: 'null'
          description: 'Formatting for textbox bullets. Default: 10pt.'
      additionalProperties: false
      type: object
      title: TextBoxFormat
      description: >-
        Formatting options for textbox content (header, text, and bullets within
        textboxes).


        Apply consistent formatting to textbox elements across the slide.
    ContentType:
      type: string
      enum:
        - text
        - table
        - chart
        - image
        - agenda
      title: ContentType
      description: >-
        Type of content block.


        Supported types: `text`, `table`, `chart`, and `agenda`. Image is
        planned for future releases.
    TextBlock:
      properties:
        header:
          anyOf:
            - type: string
            - type: 'null'
          title: Header
          description: Section header/heading. Rendered in bold above other content.
          example: Key Findings
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
          description: Paragraph text. Rendered below header, above bullets.
          example: 'Our analysis revealed the following insights:'
        bullets:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Bullets
          description: List of bullet points. Each string becomes one bullet.
          example:
            - Revenue increased 25%
            - Customer base grew 40%
            - NPS improved to 82
        header_format:
          anyOf:
            - $ref: '#/components/schemas/TextFormat'
            - type: 'null'
          description: >-
            Custom formatting for header (font, size, color, etc.). Default:
            bold, 11pt.
        text_format:
          anyOf:
            - $ref: '#/components/schemas/TextFormat'
            - type: 'null'
          description: 'Custom formatting for text paragraph. Default: 10pt.'
        bullets_format:
          anyOf:
            - $ref: '#/components/schemas/TextFormat'
            - type: 'null'
          description: 'Custom formatting for bullet points. Default: 10pt.'
      additionalProperties: false
      type: object
      title: TextBlock
      description: |-
        Text content block - can combine header, text, and bullets.

        A text block is flexible - use any combination of fields:
        - `header` alone for a section heading
        - `bullets` alone for a bullet list
        - `header` + `bullets` for a titled list
        - `text` + `bullets` for intro text followed by list
        - All three for complete sections

        All elements render in order: header → text → bullets
      examples:
        - bullets:
            - Point 1
            - Point 2
            - Point 3
        - bullets:
            - Revenue up 15%
            - Costs down 10%
          header: Key Points
        - bullets:
            - All KPIs met
            - New product launched
          header: Summary
          header_format:
            bold: true
            font_size: 14
          text: 'This quarter exceeded expectations:'
    TableContent:
      properties:
        table:
          $ref: '#/components/schemas/TableInput'
          description: >-
            Complete table data including rows, cells, and formatting. See
            TableInput schema for structure details.
        caption:
          anyOf:
            - type: string
            - type: 'null'
          title: Caption
          description: Optional caption displayed below the table.
          example: 'Table 1: Quarterly Revenue by Region'
      additionalProperties: false
      type: object
      required:
        - table
      title: TableContent
      description: >-
        Table content wrapper.


        Contains the table data and optional caption. The `table` field holds
        the

        complete table structure including rows, cells, formatting, and column
        configs.


        See the TableInput schema for full table structure documentation.
    ChartContent:
      properties:
        chart_type:
          anyOf:
            - $ref: '#/components/schemas/ChartType'
            - type: 'null'
          description: Type of chart to create. If None, preserves the template chart type.
          example: clustered_column
        categories:
          items:
            type: string
          type: array
          minItems: 1
          title: Categories
          description: Category labels (X-axis for column charts, Y-axis for bar charts).
          example:
            - Q1
            - Q2
            - Q3
            - Q4
        series:
          items:
            $ref: '#/components/schemas/ChartSeries'
          type: array
          minItems: 1
          title: Series
          description: Data series to plot. Each series becomes one set of bars/columns.
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: Chart title displayed above the chart.
          example: Quarterly Revenue
        title_format:
          anyOf:
            - $ref: '#/components/schemas/ChartTextFormat'
            - type: 'null'
          description: Text formatting for chart title.
        legend:
          anyOf:
            - $ref: '#/components/schemas/LegendFormat'
            - type: 'null'
          description: >-
            Legend formatting options. If not specified, legend is shown on the
            right.
        value_axis:
          anyOf:
            - $ref: '#/components/schemas/AxisFormat'
            - type: 'null'
          description: >-
            Value axis formatting (Y-axis for column charts, X-axis for bar
            charts).
        value_axis_unit:
          anyOf:
            - type: string
            - type: 'null'
          title: Value Axis Unit
          description: >-
            Unit label displayed above the value axis (e.g., '$M', '000s',
            'Units'). Placed as a textbox at the top of the axis. Typically used
            for non-percentage charts.
          example: $M
        category_axis:
          anyOf:
            - $ref: '#/components/schemas/AxisFormat'
            - type: 'null'
          description: >-
            Category axis formatting (X-axis for column charts, Y-axis for bar
            charts).
        caption:
          anyOf:
            - type: string
            - type: 'null'
          title: Caption
          description: Optional caption displayed below the chart.
          example: 'Figure 1: Revenue by Quarter'
        show_bar_labels:
          type: boolean
          title: Show Bar Labels
          description: >-
            Show auto-calculated total labels at top of stacked bars/columns.
            Best for stacked and percent_stacked chart types.
          default: false
        show_data_table:
          type: boolean
          title: Show Data Table
          description: >-
            If True, indicates a data table will be added below the chart. This
            positions the legend on the right instead of bottom to avoid
            overlap.
          default: false
        data_rows:
          anyOf:
            - items:
                items:
                  type: string
                type: array
              type: array
            - type: 'null'
          title: Data Rows
          description: >-
            User-provided data rows for the table beneath the chart. Each row is
            a list of string values; values are not derived automatically from
            chart series. If data_table_header_column is True, first value in
            each row is a row label. Automatically sets show_data_table=True
            when provided.
          example:
            - - Total
              - '100'
              - '150'
              - '200'
            - - Growth
              - 10%
              - 15%
              - 20%
        data_table_header_column:
          type: boolean
          title: Data Table Header Column
          description: >-
            If True, the first value in each data_rows row is treated as a row
            header label.
          default: true
        data_table_format:
          anyOf:
            - $ref: '#/components/schemas/ChartTextFormat'
            - type: 'null'
          description: >-
            Font / size / color / bold / italic / underline applied to every
            cell in the data table beneath the chart. If not set, cells have no
            explicit Latin font and inherit from the template's theme minor font
            (typically the slide master's body font), which is often the source
            of unexpected fonts in generated output.
      additionalProperties: false
      type: object
      required:
        - categories
        - series
      title: ChartContent
      description: >-
        Chart content block for bar and column charts.


        Define chart data using categories (axis labels) and one or more data
        series.

        Supports clustered, stacked, and 100% stacked variants for both bar and
        column charts.


        - Column charts: Vertical bars with categories on X-axis
        (category_axis), values on Y-axis (value_axis)

        - Bar charts: Horizontal bars with categories on Y-axis (category_axis),
        values on X-axis (value_axis)


        Example - Simple column chart:
            {
                "chart_type": "clustered_column",
                "categories": ["Q1", "Q2", "Q3", "Q4"],
                "series": [{"name": "Revenue", "values": [100, 150, 180, 220]}],
                "title": "Quarterly Revenue"
            }

        Example - Fully customized chart:
            {
                "chart_type": "stacked_bar",
                "categories": ["Product A", "Product B", "Product C"],
                "series": [
                    {"name": "North", "values": [30, 25, 40], "color": "#4472C4"},
                    {"name": "South", "values": [20, 35, 25], "color": "#ED7D31"}
                ],
                "title": "Sales by Region",
                "title_format": {"font_size": 16, "bold": true},
                "legend": {"position": "bottom", "text_format": {"font_size": 10}},
                "value_axis": {"title": "Sales ($K)", "number_format": "#,##0"},
                "category_axis": {"label_rotation": -45}
            }
      examples:
        - categories:
            - Q1
            - Q2
            - Q3
            - Q4
          chart_type: clustered_column
          series:
            - name: Revenue
              values:
                - 100
                - 150
                - 180
                - 220
          title: Quarterly Revenue
        - categories:
            - Product A
            - Product B
            - Product C
          category_axis:
            label_rotation: -45
          chart_type: stacked_bar
          legend:
            position: bottom
            text_format:
              font_size: 10
          series:
            - color: '#4472C4'
              name: North
              values:
                - 30
                - 25
                - 40
            - color: '#ED7D31'
              name: South
              values:
                - 20
                - 35
                - 25
          title: Sales by Region
          title_format:
            bold: true
            font_size: 16
          value_axis:
            number_format: '#,##0'
            title: Sales ($K)
    ImageContent:
      properties:
        source:
          type: string
          title: Source
          description: Image URL or path - NOT YET IMPLEMENTED
        alt_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Alt Text
          description: Alt text for accessibility
        caption:
          anyOf:
            - type: string
            - type: 'null'
          title: Caption
          description: Optional caption
      additionalProperties: false
      type: object
      required:
        - source
      title: ImageContent
      description: >-
        Image content (planned for future release).


        **Note:** Image support is not yet implemented. This schema is reserved
        for future use.
    AgendaContent:
      properties:
        sections:
          items:
            type: string
          type: array
          minItems: 1
          title: Sections
          description: Section titles for the agenda (e.g. ['Market Overview', 'Strategy'])
        active_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Active Index
          description: >-
            0-based index of the active/highlighted section. None = no
            highlight.
        active_font_color:
          anyOf:
            - type: string
            - type: 'null'
          title: Active Font Color
          description: >-
            Hex color for the active section text (e.g. '#00BCD4'). Uses
            template color if None.
        active_bold:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Active Bold
          description: Whether the active section text should be bold.
          default: true
        active_underline:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Active Underline
          description: Whether the active section text should be underlined.
          default: true
      type: object
      required:
        - sections
      title: AgendaContent
      description: |-
        Content for populating an agenda slide.

        The template provides base styling (fonts, sizes). The user specifies
        section titles, which one is active, and how to highlight it.

        Example:
            >>> content = AgendaContent(
            ...     sections=["Market Overview", "Strategy", "Next Steps"],
            ...     active_index=1,
            ...     active_font_color="#00BCD4",
            ... )
    TableInput:
      properties:
        rows:
          items:
            $ref: '#/components/schemas/RowInput'
          type: array
          title: Rows
        table_format:
          anyOf:
            - $ref: '#/components/schemas/TableFormat'
            - type: 'null'
        column_configs:
          anyOf:
            - items:
                $ref: '#/components/schemas/ColumnConfig'
              type: array
            - type: 'null'
          title: Column Configs
        format_templates:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/FormatTemplate'
              type: object
            - type: 'null'
          title: Format Templates
      additionalProperties: false
      type: object
      required:
        - rows
      title: TableInput
      description: |-
        User-facing table input schema.

        This is the main schema users provide as JSON input.

        Attributes:
            rows: List of row input objects
            table_format: Optional table-level formatting for headers and defaults
            column_configs: Optional column-level configurations
            format_templates: Named format templates for reuse

        Example JSON:
            {
                "table_format": {
                    "default": {
                        "text": {
                            "font_name": "Arial",
                            "font_size": 11
                        }
                    },
                    "header_row": {
                        "text": {
                            "bold": true,
                            "font_size": 14,
                            "color": "#FFFFFF"
                        },
                        "cell": {
                            "background_color": "#4472C4"
                        }
                    }
                },
                "rows": [
                    {
                        "is_header": true,
                        "cells": [
                            {"value": "Name"},
                            {"value": "Age"}
                        ]
                    },
                    {
                        "cells": [
                            {"value": "Alice"},
                            {"value": "30"}
                        ]
                    }
                ],
                "column_configs": [
                    {
                        "column_index": 0,
                        "is_header": true
                    }
                ],
                "format_templates": {
                    "custom_style": {
                        "text": {
                            "bold": true,
                            "color": "#FF0000"
                        }
                    }
                }
            }
    ChartType:
      type: string
      enum:
        - clustered_column
        - stacked_column
        - percent_stacked_column
        - clustered_bar
        - stacked_bar
        - percent_stacked_bar
      title: ChartType
      description: Supported chart types for chart input and rendering.
    ChartSeries:
      properties:
        name:
          type: string
          title: Name
          description: Series name, displayed in legend.
          example: Revenue
        values:
          items:
            anyOf:
              - type: integer
              - type: number
          type: array
          minItems: 1
          title: Values
          description: Data values for this series. Length must match categories.
          example:
            - 100
            - 150
            - 180
            - 220
        color:
          anyOf:
            - type: string
            - type: 'null'
          title: Color
          description: >-
            Hex color for this series (e.g., '#FF5733'). If not specified, uses
            template/default colors.
          example: '#4472C4'
      additionalProperties: false
      type: object
      required:
        - name
        - values
      title: ChartSeries
      description: >-
        A single data series for a chart.


        Each series represents one set of values plotted on the chart (e.g., one
        bar color

        in a clustered bar chart, or one segment in a stacked chart).


        Example:
            {"name": "Revenue", "values": [100, 150, 180, 220], "color": "#4472C4"}
    ChartTextFormat:
      properties:
        font_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Font Name
          description: Font family name (e.g., 'Arial', 'Calibri').
          example: Arial
        font_size:
          anyOf:
            - type: number
              maximum: 100
              minimum: 1
            - type: 'null'
          title: Font Size
          description: Font size in points.
          example: 12
        bold:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Bold
          description: Whether text is bold.
        italic:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Italic
          description: Whether text is italic.
        underline:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Underline
          description: >-
            Whether text is underlined (single underline). Currently only
            applied by the data-table-beneath-chart renderer. Other
            ChartTextFormat consumers (legend, axis labels, axis titles) accept
            the field but do not yet apply it.
        color:
          anyOf:
            - type: string
            - type: 'null'
          title: Color
          description: Text color as hex code (e.g., '#000000').
          example: '#000000'
      additionalProperties: false
      type: object
      title: ChartTextFormat
      description: >-
        Text formatting options for chart elements (legend, axis labels,
        titles).
    LegendFormat:
      properties:
        show:
          type: boolean
          title: Show
          description: Whether to display the legend.
          default: true
        position:
          $ref: '#/components/schemas/LegendPosition'
          description: Legend position relative to chart.
          default: right
          example: right
        text_format:
          anyOf:
            - $ref: '#/components/schemas/ChartTextFormat'
            - type: 'null'
          description: Text formatting for legend entries.
      additionalProperties: false
      type: object
      title: LegendFormat
      description: |-
        Legend formatting options.

        Controls legend visibility, position, and text styling.
    AxisFormat:
      properties:
        visible:
          type: boolean
          title: Visible
          description: Whether the axis is visible.
          default: true
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: Axis title text.
          example: Revenue ($M)
        title_format:
          anyOf:
            - $ref: '#/components/schemas/ChartTextFormat'
            - type: 'null'
          description: Text formatting for axis title.
        label_format:
          anyOf:
            - $ref: '#/components/schemas/ChartTextFormat'
            - type: 'null'
          description: Text formatting for axis labels (tick labels).
        label_rotation:
          anyOf:
            - type: number
              maximum: 90
              minimum: -90
            - type: 'null'
          title: Label Rotation
          description: Rotation angle for axis labels in degrees (-90 to 90).
          example: 45
        number_format:
          anyOf:
            - type: string
            - type: 'null'
          title: Number Format
          description: Number format string for value axis labels (e.g., '#,##0', '0%').
          example: '#,##0'
        min_value:
          anyOf:
            - type: number
            - type: 'null'
          title: Min Value
          description: Minimum value for value axis. Auto-calculated if not specified.
        max_value:
          anyOf:
            - type: number
            - type: 'null'
          title: Max Value
          description: Maximum value for value axis. Auto-calculated if not specified.
      additionalProperties: false
      type: object
      title: AxisFormat
      description: |-
        Axis formatting options.

        Controls axis visibility, title, labels, and styling.
        Applies to either value axis (Y for column, X for bar) or category axis.
    RowInput:
      properties:
        cells:
          items:
            $ref: '#/components/schemas/CellInput'
          type: array
          title: Cells
        is_header:
          type: boolean
          title: Is Header
          default: false
      additionalProperties: false
      type: object
      required:
        - cells
      title: RowInput
      description: |-
        User input for a single table row.

        Attributes:
            cells: List of cell input objects
            is_header: Whether this is a header row. Defaults to False.
    TableFormat:
      properties:
        default:
          anyOf:
            - $ref: '#/components/schemas/FormatTemplate'
            - type: 'null'
        header_row:
          anyOf:
            - $ref: '#/components/schemas/FormatTemplate'
            - type: 'null'
        header_column:
          anyOf:
            - $ref: '#/components/schemas/FormatTemplate'
            - type: 'null'
        header_intersection:
          anyOf:
            - $ref: '#/components/schemas/FormatTemplate'
            - type: 'null'
      additionalProperties: false
      type: object
      title: TableFormat
      description: |-
        Table-level formatting configuration.

        Provides default formatting for different types of cells in the table.
        All fields are optional.

        Attributes:
            default: Default formatting for all regular cells
            header_row: Formatting for cells in header rows (when row.is_header=True)
            header_column: Formatting for cells in header columns (when column.is_header=True)
            header_intersection: Formatting for cells that are both in header row AND header column

        Priority order (highest to lowest):
            1. Cell-specific format_template
            2. header_intersection (if cell is in both header row and column)
            3. header_row (if in header row)
            4. header_column (if in header column)
            5. Column config formatting
            6. default
    ColumnConfig:
      properties:
        column_index:
          type: integer
          title: Column Index
        type:
          $ref: '#/components/schemas/ColumnType'
          default: body
        is_header:
          type: boolean
          title: Is Header
          default: false
        format_template:
          anyOf:
            - type: string
            - type: 'null'
          title: Format Template
        background_color:
          anyOf:
            - type: string
            - type: 'null'
          title: Background Color
      additionalProperties: false
      type: object
      required:
        - column_index
      title: ColumnConfig
      description: |-
        Configuration for a table column.

        Attributes:
            column_index: Zero-based column index
            type: Column type (body or highlight)
            is_header: Whether this column contains row headers. Defaults to False.
            format_template: Name of format template to apply to ALL cells in this column. Optional.
            background_color: Hex color for column background (legacy, prefer format_template). Optional.
    FormatTemplate:
      properties:
        text:
          anyOf:
            - $ref: '#/components/schemas/TextFormat'
            - type: 'null'
        cell:
          anyOf:
            - $ref: '#/components/schemas/CellFormat'
            - type: 'null'
        rules:
          anyOf:
            - items:
                $ref: '#/components/schemas/FormatRule'
              type: array
            - type: 'null'
          title: Rules
      additionalProperties: false
      type: object
      title: FormatTemplate
      description: |-
        Combined formatting template - either unconditional or conditional.

        Can be one of two types:
        1. Unconditional: Has text/cell formatting that always applies
        2. Conditional: Has rules that are evaluated based on cell values

        Attributes:
            text: Text formatting properties (font, color, bold, etc.).
                  Only for unconditional templates.
            cell: Cell formatting properties (background, borders, etc.).
                  Only for unconditional templates.
            rules: List of conditional formatting rules. When present, the first
                   matching rule's format is applied. Only for conditional templates.

        Examples:
            Unconditional template:
                {"text": {"bold": true, "font_size": 14}}

            Conditional template:
                {
                    "rules": [
                        {
                            "condition": {"field": "value", "operator": "less_than", "value": 3},
                            "cell": {"background_color": "#FF0000"}
                        },
                        {
                            "condition": {"field": "value", "operator": "less_than", "value": 8},
                            "cell": {"background_color": "#CCCCCC"}
                        },
                        {
                            "condition": {"field": "value", "operator": "greater_than_or_equal", "value": 8},
                            "cell": {"background_color": "#00FF00"}
                        }
                    ]
                }
    LegendPosition:
      type: string
      enum:
        - bottom
        - left
        - right
        - top
        - top_right
      title: LegendPosition
      description: Legend position options for chart input and rendering.
    CellInput:
      properties:
        value:
          anyOf:
            - type: string
            - items:
                $ref: '#/components/schemas/ParagraphInput'
              type: array
          title: Value
        format_template:
          anyOf:
            - type: string
            - type: 'null'
          title: Format Template
        is_logo:
          type: boolean
          title: Is Logo
          default: false
      additionalProperties: false
      type: object
      required:
        - value
      title: CellInput
      description: |-
        User input for a single table cell.

        Attributes:
            value: Cell content. Can be:
                - str: Simple text value (or domain name if is_logo=True)
                - List[ParagraphInput]: Multiple paragraphs/bullets with formatting
            format_template: Name of format template to apply. Optional.
            is_logo: If True, value is treated as a domain name for logo.dev API.
                The logo image will be fetched and displayed in the cell.
                Defaults to False.
    ColumnType:
      type: string
      enum:
        - body
        - highlight
      title: ColumnType
      description: Type of column for styling purposes.
    CellFormat:
      properties:
        background_color:
          anyOf:
            - type: string
            - type: 'null'
          title: Background Color
        border_color:
          anyOf:
            - type: string
            - type: 'null'
          title: Border Color
        border_width:
          anyOf:
            - type: number
            - type: 'null'
          title: Border Width
      additionalProperties: false
      type: object
      title: CellFormat
      description: |-
        Cell formatting configuration.

        Attributes:
            background_color: Cell background color as hex code (e.g., "#E8F4F8")
            border_color: Border color as hex code (e.g., "#000000")
            border_width: Border width in points
    FormatRule:
      properties:
        condition:
          $ref: '#/components/schemas/FormatCondition'
        text:
          anyOf:
            - $ref: '#/components/schemas/TextFormat'
            - type: 'null'
        cell:
          anyOf:
            - $ref: '#/components/schemas/CellFormat'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - condition
      title: FormatRule
      description: |-
        Conditional formatting rule with inline format definition.

        Attributes:
            condition: Condition that triggers this rule
            text: Text formatting to apply when condition is met (optional)
            cell: Cell formatting to apply when condition is met (optional)
    ParagraphInput:
      properties:
        text:
          anyOf:
            - type: string
            - items:
                type: string
              type: array
          title: Text
        is_bullet:
          type: boolean
          title: Is Bullet
          default: false
        depth:
          type: integer
          title: Depth
          default: 0
        format_template:
          anyOf:
            - type: string
            - type: 'null'
          title: Format Template
      additionalProperties: false
      type: object
      required:
        - text
      title: ParagraphInput
      description: |-
        A paragraph within a cell.

        Attributes:
            text: Paragraph text. Can be:
                - str: Single paragraph text
                - List[str]: Multiple bullet points (when is_bullet=True)
            is_bullet: Whether this is a bullet list. Defaults to False.
            depth: Indentation level for bullets (0 = top level, 1 = sub-bullet, etc.).
                Defaults to 0. Only applies when is_bullet=True.
            format_template: Name of format template to apply. Optional.
    FormatCondition:
      properties:
        field:
          type: string
          title: Field
        operator:
          $ref: '#/components/schemas/ComparisonOperator'
        value:
          title: Value
      additionalProperties: false
      type: object
      required:
        - field
        - operator
        - value
      title: FormatCondition
      description: |-
        Condition for conditional formatting.

        Attributes:
            field: Field to evaluate (e.g., "value")
            operator: Comparison operator (equals, contains, greater_than, etc.)
            value: Value to compare against
    ComparisonOperator:
      type: string
      enum:
        - equals
        - not_equals
        - contains
        - not_contains
        - greater_than
        - less_than
        - greater_than_or_equal
        - less_than_or_equal
      title: ComparisonOperator
      description: Comparison operators for conditional formatting.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Production API key. Development/test deployments may also allow
        X-Org-Name.

````