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

# List Templates

> Retrieve a list of all video templates associated with your account

## Overview

Retrieve a list of all video templates created and associated with your account. Templates are reusable video project configurations that can be used to quickly create new videos with consistent branding, structure, and variable placeholders.

<Note>
  You need a valid API key to use this endpoint. Get your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</Note>

***

## API Endpoint

```http theme={null}
GET https://api.pictory.ai/pictoryapis/v1/templates
```

***

## Request Parameters

### Headers

<ParamField header="Authorization" type="string" required>
  API key for authentication (starts with `pictai_`)

  ```
  Authorization: YOUR_API_KEY
  ```
</ParamField>

***

## Response

<ResponseField name="items" type="array of objects">
  Array of template objects

  <Expandable title="template item">
    <ResponseField name="templateId" type="string">
      Unique identifier for the template
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the template
    </ResponseField>

    <ResponseField name="language" type="string">
      Language code of the template (e.g., `en` for English)
    </ResponseField>

    <ResponseField name="published" type="boolean" default="true">
      Indicates whether the template is published and available for use
    </ResponseField>

    <ResponseField name="deprecated" type="boolean" default="false">
      Indicates whether the template has been deprecated and should no longer be used
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "items": [
      {
        "templateId": "202507141030549677ylq8k8gu44vy1y",
        "name": "Corporate Presentation Template",
        "language": "en",
        "published": true,
        "deprecated": false
      },
      {
        "templateId": "202508151145238899abc123def456gh",
        "name": "Social Media Promo",
        "language": "en",
        "published": true,
        "deprecated": false
      }
    ]
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```

  ```json 400 - Bad Request theme={null}
  {
    "code": "INVALID_REQUEST",
    "message": "Bad request"
  }
  ```
</ResponseExample>

***

## Code Examples

<Tip>
  Replace `YOUR_API_KEY` with your actual API key that starts with `pictai_`
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.pictory.ai/pictoryapis/v1/templates \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'accept: application/json' | python -m json.tool
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.pictory.ai/pictoryapis/v1/templates"
  headers = {
      "Authorization": "YOUR_API_KEY",
      "accept": "application/json"
  }

  response = requests.get(url, headers=headers)
  templates = response.json()

  # Print template information
  for template in templates.get('items', []):
      print(f"Template: {template['name']}")
      print(f"  ID: {template['templateId']}")
      print(f"  Language: {template['language']}")
      print(f"  Published: {template['published']}")
      print(f"  Deprecated: {template.get('deprecated', False)}")
      print()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/templates',
    {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'accept': 'application/json'
      }
    }
  );

  const data = await response.json();

  // Print template information
  data.items.forEach(template => {
    console.log(`Template: ${template.name}`);
    console.log(`  ID: ${template.templateId}`);
    console.log(`  Language: ${template.language}`);
    console.log(`  Published: ${template.published}`);
    console.log(`  Deprecated: ${template.deprecated || false}`);
    console.log('');
  });
  ```
</CodeGroup>

***

## Usage Notes

<Tip>
  Templates are returned in the order they were created. Use the `templateId` to reference specific templates when creating new projects.
</Tip>

<Note>
  **Published Status**: Only templates with `published: true` are available for creating new videos. Draft or unpublished templates will have `published: false`.
</Note>

<Note>
  **Deprecated Templates**: Templates marked with `deprecated: true` should not be used for new projects, though they may still be accessible for backward compatibility.
</Note>

***

## Common Use Cases

### 1. List All Available Templates

Retrieve and display all templates:

```python theme={null}
import requests

def get_all_templates(api_key):
    """
    Retrieve all templates associated with the account
    """
    url = "https://api.pictory.ai/pictoryapis/v1/templates"
    headers = {"Authorization": api_key}

    response = requests.get(url, headers=headers)

    if response.status_code == 200:
        data = response.json()
        templates = data.get('items', [])

        print(f"Found {len(templates)} templates:")
        for template in templates:
            status = "Published" if template['published'] else "Draft"
            deprecated = " (Deprecated)" if template.get('deprecated') else ""
            print(f"  - {template['name']} ({status}){deprecated}")
            print(f"    ID: {template['templateId']}")

        return templates
    else:
        print(f"Error: {response.status_code}")
        return []

# Example usage
templates = get_all_templates("YOUR_API_KEY")
```

### 2. Filter Published Templates

Get only published, non-deprecated templates:

```javascript theme={null}
async function getPublishedTemplates(apiKey) {
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/templates',
    {
      headers: { 'Authorization': `${apiKey}` }
    }
  );

  const data = await response.json();

  // Filter for published, non-deprecated templates
  const publishedTemplates = data.items.filter(
    template => template.published && !template.deprecated
  );

  console.log(`Found ${publishedTemplates.length} published templates:`);
  publishedTemplates.forEach(template => {
    console.log(`  - ${template.name} (${template.templateId})`);
  });

  return publishedTemplates;
}

// Example usage
const templates = await getPublishedTemplates('YOUR_API_KEY');
```

### 3. Group Templates by Language

Organize templates by language:

```python theme={null}
from collections import defaultdict
import requests

def group_templates_by_language(api_key):
    """
    Group templates by language code
    """
    url = "https://api.pictory.ai/pictoryapis/v1/templates"
    headers = {"Authorization": api_key}

    response = requests.get(url, headers=headers)
    data = response.json()
    templates = data.get('items', [])

    # Group by language
    by_language = defaultdict(list)
    for template in templates:
        language = template.get('language', 'unknown')
        by_language[language].append(template)

    # Print grouped results
    for language, template_list in by_language.items():
        print(f"\n{language.upper()} Templates ({len(template_list)}):")
        for template in template_list:
            print(f"  - {template['name']}")

    return by_language

# Example usage
grouped = group_templates_by_language("YOUR_API_KEY")
```

### 4. Find Template by Name

Search for a specific template by name:

```javascript theme={null}
async function findTemplateByName(apiKey, searchName) {
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v1/templates',
    {
      headers: { 'Authorization': `${apiKey}` }
    }
  );

  const data = await response.json();

  // Case-insensitive search
  const found = data.items.filter(
    template => template.name.toLowerCase().includes(searchName.toLowerCase())
  );

  if (found.length > 0) {
    console.log(`Found ${found.length} matching template(s):`);
    found.forEach(template => {
      console.log(`  - ${template.name} (ID: ${template.templateId})`);
    });
    return found;
  } else {
    console.log(`No templates found matching: ${searchName}`);
    return [];
  }
}

// Example usage
const results = await findTemplateByName('YOUR_API_KEY', 'Corporate');
```

### 5. Export Template List

Export template list to a file:

```python theme={null}
import requests
import json
from datetime import datetime

def export_template_list(api_key, output_file="templates.json"):
    """
    Export all templates to a JSON file
    """
    url = "https://api.pictory.ai/pictoryapis/v1/templates"
    headers = {"Authorization": api_key}

    response = requests.get(url, headers=headers)

    if response.status_code == 200:
        data = response.json()

        # Create export data with metadata
        export_data = {
            "exportDate": datetime.now().isoformat(),
            "totalTemplates": len(data.get('items', [])),
            "templates": data.get('items', [])
        }

        # Write to file
        with open(output_file, 'w') as f:
            json.dump(export_data, f, indent=2)

        print(f"Exported {export_data['totalTemplates']} templates to {output_file}")
        return export_data
    else:
        print(f"Error: {response.status_code}")
        return None

# Example usage
export_template_list("YOUR_API_KEY", "my_templates.json")
```

### 6. Template Status Summary

Generate a summary report of template statuses:

```python theme={null}
import requests

def get_template_summary(api_key):
    """
    Generate a summary of template statuses
    """
    url = "https://api.pictory.ai/pictoryapis/v1/templates"
    headers = {"Authorization": api_key}

    response = requests.get(url, headers=headers)
    data = response.json()
    templates = data.get('items', [])

    # Calculate statistics
    total = len(templates)
    published = sum(1 for t in templates if t.get('published'))
    deprecated = sum(1 for t in templates if t.get('deprecated'))
    active = sum(1 for t in templates if t.get('published') and not t.get('deprecated'))

    # Print summary
    print("Template Summary:")
    print(f"  Total Templates: {total}")
    print(f"  Published: {published}")
    print(f"  Deprecated: {deprecated}")
    print(f"  Active (Published & Not Deprecated): {active}")
    print(f"  Draft: {total - published}")

    # Languages breakdown
    languages = {}
    for template in templates:
        lang = template.get('language', 'unknown')
        languages[lang] = languages.get(lang, 0) + 1

    print("\nTemplates by Language:")
    for lang, count in sorted(languages.items()):
        print(f"  {lang}: {count}")

    return {
        'total': total,
        'published': published,
        'deprecated': deprecated,
        'active': active,
        'languages': languages
    }

# Example usage
summary = get_template_summary("YOUR_API_KEY")
```

***

## Best Practices

### Template Selection

1. **Filter Active Templates**: Always filter for `published: true` and `deprecated: false` when presenting templates to users
2. **Cache Template Lists**: Cache the template list to reduce API calls, refreshing periodically or when needed
3. **Handle Language**: Filter templates by language when building multilingual applications
4. **Sort by Name**: Sort templates alphabetically for better user experience

### Performance Tips

* Cache template list responses for 5-10 minutes to reduce API calls
* Only fetch template list when needed (e.g., on page load or user action)
* Use client-side filtering and sorting after fetching the list once
* Monitor for deprecated templates and notify users to update their workflows