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

# List Templates

> Discover available presentation templates using MCP

## 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

```json theme={null}
{
  "method": "tools/call",
  "params": {
    "name": "list_templates",
    "arguments": {
      "limit": 50,
      "offset": 0
    }
  }
}
```

## Response

```json theme={null}
{
  "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:

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

## Python Example

```python theme={null}
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

<Card title="Selecting Templates" icon="check-circle" href="/templates/selecting-templates">
  Learn how to choose and use templates
</Card>

<Card title="Generate Slides" icon="wand-magic" href="/mcp/generate-slides">
  Use templates in slide generation
</Card>