---
title: "List templates"
canonical_url: https://docs.zvid.io/docs/endpoints/list-templates/
source: docs/endpoints/list-templates.api.mdx
content_revision: 6338386a1dd87e4a
---

# List templates

`GET /api/templates`

List the account's templates with their declared variables (`variablesSummary`). The full project JSON is not included — fetch a template by ID for that.


## Authentication

- Option 1: `x-api-key: YOUR_API_KEY` (header). API key for authentication. Create one in your dashboard.
- Option 2: `Authorization: Bearer YOUR_ACCESS_TOKEN`. Dashboard JWT in Authorization: Bearer <token>, only on operations that explicitly list this scheme. Prefer x-api-key for REST integrations. OAuth for hosted MCP is a separate connection at https://mcp.zvid.io/mcp.

Create API keys at [app.zvid.io/api-keys](https://app.zvid.io/api-keys). Keep credentials on your server.

## Parameters

| Parameter | Location | Type | Required | Description and constraints |
| --- | --- | --- | --- | --- |
| `page` | query | integer | No | Default: `1`. Minimum: `1`. |
| `limit` | query | integer | No | Default: `20`. Minimum: `1`. Maximum: `100`. |

## Request

The shell examples read credentials from `ZVID_API_KEY` (or `ZVID_ACCESS_TOKEN` for Bearer authentication). Set that variable in your environment. Replace sample project, template, job, and asset identifiers with values from your own account.

This operation does not take a request body.

### Request example

```bash
curl --request GET 'https://api.zvid.io/api/templates' \
  --header "x-api-key: $ZVID_API_KEY"
```

## Responses


### HTTP 200

Templates for the authenticated account

Content type: `application/json`.

Required properties: `templates`, `pagination`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.templates` | array of [TemplateSummary](#schema-template-summary) | Yes |  |
| `response.pagination` | [Pagination](#schema-pagination) | Yes |  |

**Nested field: `response.templates`**

**Array item: `response.templates[]`**

Schema: [TemplateSummary](#schema-template-summary).


**Example response**

```json
{
  "templates": [
    {
      "id": "tpl_rAequJHzUETcLAMfrezk",
      "userId": 5,
      "name": "Product promo",
      "description": "16:9 promo with title/brand variables",
      "type": "video",
      "variablesSummary": [
        {
          "name": "title",
          "type": "string",
          "used": true,
          "default": "Hello world"
        }
      ],
      "version": 3,
      "status": "active",
      "createdAt": "2026-07-01T09:00:00.000Z",
      "updatedAt": "2026-07-06T18:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}
```

### HTTP 401

Unauthorized

Content type: `application/json`.

Unknown properties are rejected. Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `response.error` | string | Yes | Error type |
| `response.message` | string | No | Human-readable error message |


## Schema definitions

The following definitions describe the fields referenced above. Expand a definition to inspect its complete contract.


### schema template list

**TemplateList**


Required properties: `templates`, `pagination`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `TemplateList.templates` | array of [TemplateSummary](#schema-template-summary) | Yes |  |
| `TemplateList.pagination` | [Pagination](#schema-pagination) | Yes |  |

**Nested field: `TemplateList.templates`**

**Array item: `TemplateList.templates[]`**

Schema: [TemplateSummary](#schema-template-summary).


### schema template summary

**TemplateSummary**


One template as returned by the template list endpoint (no project JSON — fetch the template by ID for that).

Required properties: `id`, `name`, `type`, `version`, `status`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `TemplateSummary.id` | string | Yes |  |
| `TemplateSummary.userId` | integer | No |  |
| `TemplateSummary.name` | string | Yes |  |
| `TemplateSummary.description` | string / null | No |  |
| `TemplateSummary.type` | `"video"` / `"image"` | Yes |  |
| `TemplateSummary.variablesSummary` | array of [TemplateVariableSummary](#schema-template-variable-summary) | No |  |
| `TemplateSummary.version` | integer | Yes |  |
| `TemplateSummary.status` | `"active"` / `"archived"` | Yes |  |
| `TemplateSummary.createdAt` | string | No | Format: `date-time`. |
| `TemplateSummary.updatedAt` | string | No | Format: `date-time`. |

**Nested field: `TemplateSummary.variablesSummary`**

**Array item: `TemplateSummary.variablesSummary[]`**

Schema: [TemplateVariableSummary](#schema-template-variable-summary).


### schema template variable summary

**TemplateVariableSummary**


One declared template variable and whether the project uses it.

Required properties: `name`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `TemplateVariableSummary.name` | string | Yes |  |
| `TemplateVariableSummary.type` | string | No |  |
| `TemplateVariableSummary.used` | boolean | No |  |
| `TemplateVariableSummary.default` | any JSON value | No | Declared default value (any JSON type) |


### schema pagination

**Pagination**


Standard pagination envelope for list endpoints.

Required properties: `page`, `limit`, `total`, `totalPages`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `Pagination.page` | integer | Yes |  |
| `Pagination.limit` | integer | Yes |  |
| `Pagination.total` | integer | Yes |  |
| `Pagination.totalPages` | integer | Yes |  |
| `Pagination.hasNext` | boolean | No | Whether there are more pages after the current one |
| `Pagination.hasPrev` | boolean | No | Whether there are pages before the current one |


### schema authentication error

**AuthenticationError**


Unknown properties are rejected. Required properties: `error`.

| Field | Type | Required | Description and constraints |
| --- | --- | --- | --- |
| `AuthenticationError.error` | string | Yes | Error type |
| `AuthenticationError.message` | string | No | Human-readable error message |


## Related resources

- [OpenAPI specification](https://docs.zvid.io/openapi.yaml)
- [Project payload schema](https://docs.zvid.io/schemas/render-payload.schema.json)
- [Quick Start](https://docs.zvid.io/docs/quick-start/)
- [Authentication guide](https://docs.zvid.io/docs/authentication/)