Shotstack templates provide a way to save an [edit](https://shotstack.io/docs/api/#tocs_edit) that you want to re-use at
a later date. A template can also be saved with placeholders using double curly braces (handlebars), like
`{{ FIRST_NAME }}`. These placeholders can be replaced with real values when the video is rendered.

A template can be rendered using it's ID and an array of [merge fields](merging-data.md) that replace the placeholders
at render time.

### Render a template with merge fields

Once you have saved a template, you can render it at any time in the future. While it is possible to render the template
by id only, it is more likely you will want to replace placeholders using merge fields.

To render a template call the following endpoint:

```bash
POST https://api.shotstack.io/{{ENV}}/templates/render
```

The following cURL request will replace the templates placeholders with the provided merge fields and render a video:

```bash
curl -X POST \
     -H "Content-Type: application/json" \
     -H "x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf" \
     -d '
{
    "id": "ca84c7c5-5fe4-66d3-839e-ee0f1d4c2641",
    "merge": [
        {
            "find": "URL",
            "replace": "https://shotstack-assets.s3-ap-southeast-2.amazonaws.com/footage/city-timelapse.mp4"
        },
        {
            "find": "TRIM",
            "replace": 3
        },
        {
            "find": "DURATION",
            "replace": 10
        }
    ]
}'
```

The following response will be returned including the render task id; `response.id`:

```json
{
    "success": true,
    "message": "Created",
    "response": {
        "message": "Render Successfully Queued",
        "id": "b3a3034f-8827-9e33-a6a8-ba745d36fc1"
    }
}
```

The video is now queued for rendering and can be polled like any other render request using the
[GET render endpoint](../getting-started/hello-world-using-curl.md#poll-the-api-to-check-the-render-status) or using
[webhooks](../architecting-an-application/webhooks.md).

### Create a template

To create a template you POST an edit to the **templates** endpoint:

```bash
POST https://api.shotstack.io/{{ENV}}/templates/
```

Where `{{ENV}}` is the environment you are working with, for example `stage` or `v1`.

The following cURL request will create a template in the **stage** environment. The video `src` and `length` use
placeholder values `{{ URL }}` and `{{ DURATION }}`. The place holders can be replaced when rendering using merge
fields.

```bash
curl -X POST \
     -H "Content-Type: application/json" \
     -H "x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf" \
     -d '
{
    "name": "Basic test template",
    "template": {
        "timeline": {
            "tracks": [
                {
                    "clips": [
                        {
                            "asset": {
                                "type": "video",
                                "src": "{{ URL }}"
                            },
                            "start": 0,
                            "length": "{{ DURATION }}"
                        }
                    ]
                }
            ]
        },
        "output": {
            "format": "mp4",
            "resolution": "sd"
        }
    }
}' \
     https://api.shotstack.io/stage/templates/
```

The POST request should return a JSON payload that includes the the template ID; `response.id`:

```json
{
    "success": true,
    "message": "Created",
    "response": {
        "message": "Template Successfully Created",
        "id":"ca84c7c5-5fe4-66d3-839e-ee0f1d4c2641"
    }
}
```

### Retrieve a template

You can retrieve a template using the following endpoint:

```bash
GET https://api.shotstack.io/{{ENV}}/templates/{{ID}}
```

The following cURL request retrieves the template we just created:

```bash
curl -X GET \
     -H "Content-Type: application/json" \
     -H "x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf" \
     https://api.shotstack.io/stage/templates/ca84c7c5-5fe4-66d3-839e-ee0f1d4c2641
```

The response should look like:

```json
{
    "success": true,
    "message": "OK",
    "response": {
        "id": "ca84c7c5-5fe4-66d3-839e-ee0f1d4c2641",
        "name": "Basic test template",
        "owner": "5ca6hu7s9k",
        "template": {
            "timeline": {
                "tracks": [
                    {
                        "clips": [
                            {
                                "asset": {
                                    "type": "video",
                                    "src": "{{ URL }}"
                                },
                                "start": 0,
                                "length": "{{ DURATION }}"
                            }
                        ]
                    }
                ]
            },
            "output": {
                "format": "mp4",
                "resolution": "sd"
            }
        }
    }
}
```

### Retrieve a list of all templates

You can retrieve a list of template using the following endpoint:

```bash
GET https://api.shotstack.io/{{ENV}}/templates/
```

The following cURL request returns all templates created in the **stage** environment:

```bash
curl -X GET \
     -H "Content-Type: application/json" \
     -H "x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf" \
     https://api.shotstack.io/stage/templates
```

The response should include a list of all templates:

```json
{
    "success": true,
    "message": "OK",
    "response": {
        "owner": "5ca6hu7s9k",
        "templates": [
            {
                "id": "ca84c7c5-5fe4-66d3-839e-ee0f1d4c2641",
                "name": "Basic test template",
                "created": "2022-12-20T12:24:44.650Z",
                "updated": "2022-12-20T12:24:44.451Z"
            },
            {
                "id": "17eff444b-b0f4-8a91-8fcc-7423ef711060",
                "name": "Another template",
                "created": "2022-12-19T22:37:39.287Z",
                "updated": "2022-12-20T03:57:59.827Z"
            },
            {
                "id": "e63874c58-3a62-3c98-8942-2bb70cad3ba9",
                "name": "Hello world template",
                "created": "2022-10-03T07:10:46.125Z",
                "updated": "2022-12-20T03:57:25.865Z"
            }
        ]
    }
}
```

### Update an existing template

To update and overwrite an existing template use the following endpoint:

```bash
PUT https://api.shotstack.io/{{ENV}}/templates/{{ID}}
```

The following cURL request updates the template we created earlier and adds a `{{ TRIM }}` placeholder and changes the
resolution to `hd`:

```bash
curl -X PUT \
     -H "Content-Type: application/json" \
     -H "x-api-key: ptmpOiyKgGYMnnONwvXH7FHzDGOazrIjaEDUS7Cf" \
     -d '
{
    "name": "Basic test template",
    "template": {
        "timeline": {
            "tracks": [
                {
                    "clips": [
                        {
                            "asset": {
                                "type": "video",
                                "src": "{{ URL }}",
                                "trim": "{{ TRIM }}"
                            },
                            "start": 0,
                            "length": "{{ DURATION }}"
                        }
                    ]
                }
            ]
        },
        "output": {
            "format": "mp4",
            "resolution": "hd"
        }
    }
}' \
     https://api.shotstack.io/stage/templates/ca84c7c5-5fe4-66d3-839e-ee0f1d4c2641
```

The response should indicate the template was updated and return the template id:

```json
{
    "success": true,
    "message": "OK",
    "response": {
        "id": "ca84c7c5-5fe4-66d3-839e-ee0f1d4c2641",
        "message": "Template Successfully Updated"
    }
}
```