Template management

Upload your .pptx template, run analysis, and inspect what each slide accepts.

A template is the brand and structural contract for everything you generate — fonts, colours, table styles, chart presets, master layouts. The API never invents a look; it conforms to whatever your .pptx encodes. Upload it once, analyze it once, and reference it by ID on every generation request.

Step 1: Prepare your template

Build the template in PowerPoint (or any tool that exports .pptx). A few things that help analysis identify slide structure cleanly:

• Tables with the right column count and a populated header row
• Charts with realistic sample categories and series
• Distinct master layouts for distinct page types (table-heavy pages, chart pages, agenda, dividers)
• Title placeholders on slides that should accept titles

The example used throughout this page is slide 1 of a small demo template — a single six-column table with a coloured header band:

Step 2: Upload

Two-step flow: the API returns a signed upload URL; you PUT the .pptx directly to storage; you confirm the upload.

Initiate

POST /api/v1/templates
X-API-Key: your-api-key
Content-Type: application/json

{
  "filename": "ic-memo-template.pptx",
  "file_size": 1048576,
  "metadata": {
    "category": "ic-memo",
    "tags": ["pe", "fund-1"],
    "description": "IC memo template for fund 1"
  }
}

{
  "template_id": "tmpl_abc123",
  "upload_url": "https://storage.example.com/signed-url...",
  "expires_in": 3600,
  "status": "pending"
}

Upload the file

PUT the .pptx bytes to upload_url. The bytes go directly to object storage; the API never sees them.

Confirm

POST /api/v1/templates/{template_id}/upload/confirm
X-API-Key: your-api-key

The service verifies the object exists and marks the template as uploaded.

Step 3: Run analysis

POST /api/v1/templates/{template_id}/analysis
X-API-Key: your-api-key
Content-Type: application/json

{
  "options": {
    "parse_master_template_layout": true,
    "parse_slides": true,
    "include_placeholder_positions": true,
    "include_table_details": true
  }
}

Analysis runs asynchronously; the response returns immediately with an analysis_id and status: "processing".

Step 4: Inspect the analysis output

Once analysis completes, fetch the results:

GET /api/v1/templates/{template_id}/analysis
X-API-Key: your-api-key

The response wraps the parser output. The top-level structure:

{
  "slides": [
    {
      "slideId": "slide_a3f81c92",
      "slideIndex": 0,
      "slideNumber": 1,
      "title": null,
      "dimension": { "width": 1440.0, "height": 810.0 },
      "shapes": [ /* one entry per shape on the slide */ ]
    },
    {
      "slideId": "slide_7e2bd445",
      "slideIndex": 1,
      "slideNumber": 2,
      "title": null,
      "dimension": { "width": 1440.0, "height": 810.0 },
      "shapes": [ /* ... */ ]
    }
  ]
}

Each slide gets its own slideId (assigned during analysis, stable across reads). Generation requests target slides by slideId, not by template — which means a single deck can mix slides from multiple templates by referencing each one’s slideId. slideIndex (0-based) and slideNumber (1-based, matches PowerPoint’s slide number) are also available if you need ordering.

Each entry in shapes has a common set of fields, plus type-specific extras keyed off shape_type. The rest of this section walks through each shape type with a real excerpt from the parser running against slide 1 of the demo template above.

Common fields (every shape)

{
  "is_placeholder": true,
  "placeholder_type": "SLIDE_NUMBER",
  "placeholder_index": 13,
  "shape_type": "AutoShape",
  "name": "Slide Number Placeholder 1",
  "text": "1",
  "x": 1363.0147705078125,
  "y": 772.1712036132812,
  "width": 76.98519897460938,
  "height": 29.77204704284668
}

Field	Meaning
shape_type	AutoShape, Table, Chart, OleObjectFrame, etc.
name	The shape’s name as set in PowerPoint
is_placeholder	true if the shape is a master-layout placeholder
placeholder_type	TITLE, BODY, SLIDE_NUMBER, etc. (or null)
placeholder_index	Index that ties the shape to its master-layout slot (or null)
text	Current text on the shape (often "" for an unfilled template)
x, y, width, height	Position and size in points

Placeholder shapes (TITLE, BODY, SLIDE_NUMBER)

Adds text_format, describing the font the template uses for that placeholder.

{
  "is_placeholder": true,
  "placeholder_type": "TITLE",
  "placeholder_index": 0,
  "shape_type": "AutoShape",
  "name": "Title 2",
  "text": "",
  "x": 66.0,
  "y": 64.91110229492188,
  "width": 1242.0,
  "height": 48.0,
  "text_format": {
    "font_color": { "r": 44, "g": 44, "b": 44 },
    "font_size": 33.75,
    "font_name": "Arial",
    "bold": true,
    "italic": false
  }
}

The text_format block tells you what the title (or body, etc.) will look like once populated — the same font and colour the template’s master layout encodes.

Table shapes

Adds table_rows / table_columns, plus table_info (dimensions, style preset, six PowerPoint table-style flags) and table_styling (per-cell formatting for the header and body rows).

{
  "shape_type": "Table",
  "name": "Table 4",
  "x": 66.0,
  "y": 140.69583129882812,
  "width": 1298.1602783203125,
  "height": 52.39228439331055,
  "table_rows": 1,
  "table_columns": 6,
  "table_info": {
    "rows": 1,
    "columns": 6,
    "width": 1298.1602783203125,
    "height": 52.39228439331055,
    "style_preset": "TableStylePreset.MEDIUM_STYLE_2_ACCENT_1",
    "has_first_row": false,
    "has_last_row": false,
    "has_first_col": false,
    "has_last_col": false,
    "horizontal_banding": false,
    "vertical_banding": false
  },
  "table_styling": {
    "header_row_format": [
      {
        "fill_type": "FillType.SOLID",
        "fill_color": { "r": 204, "g": 0, "b": 0 },
        "transparency": 0.0,
        "borders": {
          "left":   { "width": 2.25, "color": { "r": 255, "g": 255, "b": 255 }, "style": "LineStyle.SINGLE" },
          "top":    { "width": 2.25, "color": { "r": 255, "g": 255, "b": 255 }, "style": "LineStyle.SINGLE" },
          "right":  { "width": 2.25, "color": { "r": 255, "g": 255, "b": 255 }, "style": "LineStyle.SINGLE" },
          "bottom": { "width": 2.25, "color": { "r": 255, "g": 255, "b": 255 }, "style": "LineStyle.SINGLE" },
          "diagonal_down": { "width": null, "color": null, "style": "LineStyle.NOT_DEFINED" },
          "diagonal_up":   { "width": null, "color": null, "style": "LineStyle.NOT_DEFINED" }
        }
      }
    ],
    "body_row_format": [],
    "header_text_format": [
      { "font_color": { "r": 255, "g": 255, "b": 255 }, "font_size": 14.0, "font_name": "Arial", "bold": true, "italic": false, "alignment": "center" }
    ],
    "body_text_format": []
  }
}

The example shows one entry in each per-cell array; the real response has one entry per column (six entries, mostly identical). Each border block also includes diagonal_down and diagonal_up (typically LineStyle.NOT_DEFINED for tables that don’t use diagonals).

table_styling arrays:

Array	What it contains
header_row_format	One entry per column of the header row: fill type, fill colour, transparency, and four borders + two diagonals
header_text_format	One entry per column of the header row: font name, size, colour, bold/italic, alignment
body_row_format	Same shape as header_row_format, for body rows; empty when the template has no populated body row
body_text_format	Same shape as header_text_format, for body rows

Table-style flags

The six boolean flags inside table_info mirror PowerPoint’s “Table Tools → Design → Table Style Options” checkboxes. They control whether the applied style preset (e.g. MEDIUM_STYLE_2_ACCENT_1) emphasizes certain rows or columns:

Flag	PowerPoint checkbox	Effect when true
has_first_row	Header Row	First row gets the style’s header formatting
has_last_row	Total Row	Last row gets the style’s “totals” formatting
has_first_col	First Column	First column gets emphasized formatting
has_last_col	Last Column	Last column gets emphasized formatting
horizontal_banding	Banded Rows	Alternating row colours from the style
vertical_banding	Banded Columns	Alternating column colours from the style

These flags are independent of the cell-level formatting in header_row_format / header_text_format. In the example above all six are false because the header band is styled directly on each cell, not via the style preset.

Chart shapes

Charts return only the common shape fields — position, name, shape_type: "Chart". Example from a chart slide elsewhere in the same template:

{
  "is_placeholder": false,
  "placeholder_type": null,
  "placeholder_index": null,
  "shape_type": "Chart",
  "name": "Chart 4",
  "text": "",
  "x": 66.0,
  "y": 171.47369384765625,
  "width": 1242.0,
  "height": 553.6691284179688
}

The chart’s internal structure (categories, series, preset) lives inside the .pptx itself; generation requests reference the chart by its slide’s identifier and supply the data to populate it. See the chart guides for how to fill or refresh a chart.

Text-marker shapes (AutoShape placeholders)

Templates also use a second placeholder pattern: regular AutoShape shapes whose text field holds a recognized marker string. The API identifies these by their text value and swaps in the real content from the request payload. Common markers in the demo template: LHS_header, RHS_header, Bullet_placeholder, Text_placeholder.

These have is_placeholder: false and placeholder_type: null (PowerPoint doesn’t classify them as native placeholders) but functionally they are content slots.

{
  "is_placeholder": false,
  "placeholder_type": null,
  "placeholder_index": null,
  "shape_type": "AutoShape",
  "name": "Rectangle 14",
  "text": "LHS_header",
  "x": 66.0,
  "y": 164.58921813964844,
  "width": 605.142822265625,
  "height": 48.2400016784668
}

The distinction:

Shape	Identifier the API uses
Native PowerPoint placeholder	placeholder_type (TITLE, BODY, etc.)
Text-marker AutoShape	text value (LHS_header, etc.)
Decorative AutoShape	None — has text: "" and is ignored at generation time

Authoring-tool artifacts

OleObjectFrame shapes are embedded objects from authoring tools, most commonly think-cell. They appear on every slide in templates built with such tools and don’t carry generatable content.

{
  "is_placeholder": false,
  "placeholder_type": null,
  "placeholder_index": null,
  "shape_type": "OleObjectFrame",
  "name": "think-cell data - do not delete",
  "text": "",
  "x": 0.12503936886787415,
  "y": 0.12503936886787415,
  "width": 0.09661417454481125,
  "height": 0.12503936886787415
}

The parser returns these as-is for completeness. Safe to ignore.

Step 5: Use it for generation

Generation requests reference slides by slideId. Because IDs are per-slide, a single deck can pull slides from multiple templates — useful for assembling pitch books, IC memos, or LP updates that combine standard cover/agenda slides from one template with content slides from another.

{
  "slides": [
    { "template_slide_id": "slide_a3f81c92", "slide_data": { /* ... */ } },
    { "template_slide_id": "slide_b1f9e2d7", "slide_data": { /* ... */ } },
    { "template_slide_id": "slide_c4d20af8", "slide_data": { /* ... */ } }
  ]
}

See Slide input for how to map your data onto each slide’s analysis structure, and Examples for copy-paste payloads against common slide shapes.

Maintenance

Template lifecycle

Action	Endpoint
List templates	GET /api/v1/templates
Get template details and the latest analysis summary	GET /api/v1/templates/{id}
Download the original .pptx	GET /api/v1/templates/{id}/download
Update template metadata (name, tags, description)	PATCH /api/v1/templates/{id}
Soft-delete a template	DELETE /api/v1/templates/{id}
Restore a soft-deleted template	POST /api/v1/templates/{id}/restore

Analysis

Action	Endpoint
Re-run analysis (e.g. after parser updates, or to refresh with new options)	POST /api/v1/templates/{id}/analysis
Check analysis status (lightweight, no full payload)	GET /api/v1/templates/{id}/analysis/status
Get the full analysis results	GET /api/v1/templates/{id}/analysis
Cancel a running analysis	DELETE /api/v1/templates/{id}/analysis/{analysis_id}

Slides

Action	Endpoint
Get a specific slide’s analysis (by slide_number)	GET /api/v1/templates/{id}/slides/{slide_number}
Render a slide as a PNG preview	GET /api/v1/templates/{id}/slides/{slide_number}/preview

The slide preview endpoint is useful when an agent or app wants to show the user a thumbnail of the template slide they’re about to populate.

Updating templates

There is no endpoint to overwrite a template’s .pptx bytes. If you change the underlying file, upload it as a new template (new template_id) — generations reference templates by ID and the analysis is tied to the file that was uploaded. The PATCH endpoint only updates metadata (name, tags, description), not the file itself.

Looking for the endpoint that picks the best-fit slide for a given input shape? That’s POST /api/v1/templates/match, documented under Slide input since it’s part of composing a generation request rather than maintaining a template.