List Templates - Poesius API Documentation

Tool: `list_templates`

List all available templates with their layouts.

Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Maximum templates to return (default: 50)
`offset`	integer	No	Pagination offset (default: 0)

Example Request

{
  "method": "tools/call",
  "params": {
    "name": "list_templates",
    "arguments": {
      "limit": 50,
      "offset": 0
    }
  }
}

Response

{
  "templates": [
    {
      "template_id": "uuid",
      "template_name": "Professional Blue",
      "layouts": [
        {
          "layout_id": "layout-1",
          "layout_name": "Title Slide",
          "master_name": "Master 1",
          "master_index": 0,
          "layout_index": 0,
          "thumbnail_url": "https://..."
        },
        {
          "layout_id": "layout-2",
          "layout_name": "Content Slide",
          "master_name": "Master 1",
          "master_index": 0,
          "layout_index": 1,
          "thumbnail_url": "https://..."
        }
      ]
    }
  ],
  "total": 5,
  "default_template_id": "uuid"
}

Response Structure

Template Object

template_id (string): Unique identifier for the template
template_name (string): Human-readable template name
layouts (array): Available layouts within this template

Layout Object

layout_id (string): Unique identifier for the layout
layout_name (string): Human-readable layout name (e.g., “Title Slide”, “Content Slide”)
master_name (string): Master slide name
master_index (integer): Index of the master slide
layout_index (integer): Index of the layout within the master
thumbnail_url (string): URL to preview thumbnail

Using Templates

Once you have the template list, you can use a template_id in your generation requests:

{
  "method": "tools/call",
  "params": {
    "name": "generate_slides",
    "arguments": {
      "topic": "My Presentation",
      "instructions": "Create slides",
      "template_id": "uuid-from-list-templates"
    }
  }
}

Python Example

import requests

API_KEY = "pk_your_api_key_here"
BASE_URL = "https://poe.poesius.com/api/v1/mcp"

def list_templates(limit=50, offset=0):
    response = requests.post(
        f"{BASE_URL}/messages",
        headers={
            "X-API-Key": API_KEY,
            "Content-Type": "application/json"
        },
        json={
            "method": "tools/call",
            "params": {
                "name": "list_templates",
                "arguments": {
                    "limit": limit,
                    "offset": offset
                }
            }
        }
    )
    return response.json()

# Get templates
result = list_templates()
templates = result["result"]["templates"]

for template in templates:
    print(f"{template['template_name']} ({template['template_id']})")
    for layout in template["layouts"]:
        print(f"  - {layout['layout_name']}")

Best Practices

Cache Templates: Template lists don’t change frequently, so cache the results
Use Default: If default_template_id is provided, you can omit template_id in requests
Inspect Layouts: Check available layouts to understand what’s available for each template

Selecting Templates

Learn how to choose and use templates

Generate Slides

Use templates in slide generation

​Tool: list_templates

​Parameters

​Example Request

​Response

​Response Structure

​Template Object

​Layout Object

​Using Templates

​Python Example

​Best Practices