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

# Template Management

> List templates, get template details, and set your default template

## Overview

Templates define the visual design and layout structure of your presentations.

This API page focuses on the core template endpoints used in programmatic workflows:

* List templates
* Get template details
* Set default template

Template creation and visual editing are handled in the web app at `https://app.poesius.com`.

## List Templates

**Endpoint**: `GET /templates/`

List all templates available to your account.

**Request:**

```bash theme={null}
curl -X GET "https://poe.poesius.com/api/v1/templates/?limit=50&offset=0" \
  -H "X-API-Key: pk_your_api_key"
```

**Query Parameters:**

* `limit` (integer, optional): Maximum number of templates to return (default: 50, max: 100)
* `offset` (integer, optional): Pagination offset (default: 0)

**Response:**

```json theme={null}
{
  "templates": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Professional Blue",
      "description": "Corporate presentation template",
      "processing_status": "completed",
      "total_layouts": 15,
      "is_default": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "default_template_id": "123e4567-e89b-12d3-a456-426614174000"
}
```

## Get Template Details

**Endpoint**: `GET /templates/{template_id}`

Get detailed information about a specific template.

**Request:**

```bash theme={null}
curl -X GET "https://poe.poesius.com/api/v1/templates/123e4567-e89b-12d3-a456-426614174000" \
  -H "X-API-Key: pk_your_api_key"
```

**Response:**

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Professional Blue",
  "description": "Corporate presentation template",
  "processing_status": "completed",
  "total_masters": 2,
  "total_layouts": 15,
  "is_default": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

## Set Default Template

**Endpoint**: `POST /templates/{template_id}/set-default`

Set a template as your default. The default template will be used automatically when no `template_id` is specified in slide generation requests.

**Request:**

```bash theme={null}
curl -X POST "https://poe.poesius.com/api/v1/templates/123e4567-e89b-12d3-a456-426614174000/set-default" \
  -H "X-API-Key: pk_your_api_key"
```

**Alternative Method**: `POST /templates/default`

```bash theme={null}
curl -X POST "https://poe.poesius.com/api/v1/templates/default" \
  -H "X-API-Key: pk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "123e4567-e89b-12d3-a456-426614174000"
  }'
```

**Response:**

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Professional Blue",
  "description": "Corporate presentation template",
  "processing_status": "completed",
  "total_layouts": 15,
  "is_default": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
```

## Using Templates in Slide Generation

When generating slides, you can specify a template in two ways:

### 1. Use Default Template

If you have set a default template, simply omit the `template_id` parameter:

```bash theme={null}
curl -X POST "https://poe.poesius.com/api/v1/slides/generate-from-doc" \
  -H "X-API-Key: pk_your_api_key" \
  -F "document=@document.pdf" \
  -F "num_slides=15"
```

### 2. Specify Template ID

```bash theme={null}
curl -X POST "https://poe.poesius.com/api/v1/slides/generate-from-doc" \
  -H "X-API-Key: pk_your_api_key" \
  -F "document=@document.pdf" \
  -F "num_slides=15" \
  -F "template_id=123e4567-e89b-12d3-a456-426614174000"
```

## Best Practices

* **List first**: Call `GET /templates/` before generation to confirm available template IDs
* **Set a default**: Use `POST /templates/{id}/set-default` for a smoother generation flow
* **Fallback behavior**: If you do not send `template_id`, your default template is used when set
* **Use the web app for editing**: Uploading and visual template configuration are done in `https://app.poesius.com`

<Card title="Web Platform" icon="globe" href="https://app.poesius.com">
  Edit templates and define layout zones visually
</Card>