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

# Inspecting Templates

> Fetch template details, discover compositions and layers, download the source file, and update template properties

Once a template is uploaded, you can inspect it to discover its available compositions and layers before submitting jobs. You can also update its display name and download the original source file.

<Warning>
  The v2 inspection API (`GET /api/v2/templates/{id}` returning embedded `compositions` and `layers` arrays) is deprecated and will be removed in a future release. Use the v3 endpoints below for all new integrations.
</Warning>

## Fetch a Template (v3)

The v3 API splits introspection into three separate endpoints. The main metadata endpoint returns a lightweight object - compositions and layers are fetched separately.

### 1. Get template metadata

```bash theme={null}
curl -X GET https://api.nexrender.com/api/v3/templates/01JTGM9GCR71JV7EJYDF45QAFD \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "id": "01JTGM9GCR71JV7EJYDF45QAFD",
  "type": "zip",
  "displayName": "Product Promo",
  "status": "uploaded",
  "createdAt": "2025-05-05T16:25:59.961Z",
  "updatedAt": "2025-05-05T16:30:12.000Z"
}
```

### 2. List compositions

`GET /v3/templates/{id}/compositions` returns paginated compositions with full AE metadata.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.nexrender.com/api/v3/templates/01JTGM9GCR71JV7EJYDF45QAFD/compositions" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```json Response theme={null}
  [
    {
      "aeid": "1",
      "name": "main",
      "width": 1920,
      "height": 1080,
      "duration": 15.0,
      "frame_rate": 30,
      "data": {}
    },
    {
      "aeid": "2",
      "name": "intro",
      "width": 1920,
      "height": 1080,
      "duration": 3.0,
      "frame_rate": 30,
      "data": {}
    }
  ]
  ```
</CodeGroup>

The `name` field is the value to use as `template.composition` when submitting a render job.

| Field              | Description                                                   |
| ------------------ | ------------------------------------------------------------- |
| `aeid`             | After Effects internal composition ID                         |
| `name`             | Composition name - use this as `template.composition` in jobs |
| `width` / `height` | Composition dimensions in pixels                              |
| `duration`         | Duration in seconds                                           |
| `frame_rate`       | Frames per second                                             |
| `data`             | Additional parser metadata                                    |

### 3. List layers

`GET /v3/templates/{id}/layers` returns paginated layers with full structural metadata.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.nexrender.com/api/v3/templates/01JTGM9GCR71JV7EJYDF45QAFD/layers" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```json Response theme={null}
  [
    {
      "composition_id": 1,
      "aeid": 1,
      "name": "title",
      "top": 200,
      "left": 100,
      "width": 1720,
      "height": 120,
      "start_time": 0,
      "in_point": 0,
      "out_point": 15.0,
      "layer_type": "TextLayer",
      "source_type": null,
      "source_comp_id": null,
      "parent_id": null,
      "data": {}
    },
    {
      "composition_id": 1,
      "aeid": 2,
      "name": "logo",
      "top": 880,
      "left": 80,
      "width": 200,
      "height": 80,
      "start_time": 0,
      "in_point": 0,
      "out_point": 15.0,
      "layer_type": "AVLayer",
      "source_type": "image",
      "source_comp_id": null,
      "parent_id": null,
      "data": {}
    }
  ]
  ```
</CodeGroup>

| Field                               | Description                                                              |
| ----------------------------------- | ------------------------------------------------------------------------ |
| `composition_id`                    | `aeid` of the composition this layer belongs to                          |
| `aeid`                              | After Effects internal layer ID                                          |
| `name`                              | Layer name - use this as `layerName` in job assets and functions         |
| `top` / `left` / `width` / `height` | Layer bounds at time 0, in pixels                                        |
| `start_time`                        | Layer start time in seconds                                              |
| `in_point` / `out_point`            | Layer in/out points in seconds                                           |
| `layer_type`                        | AE layer type: `TextLayer`, `AVLayer`, `ShapeLayer`, `CameraLayer`, etc. |
| `source_type`                       | Source type for AV layers: `image`, `video`, `audio` (null for non-AV)   |
| `source_comp_id`                    | AE composition ID of the source precomp, when this layer is a precomp    |
| `parent_id`                         | AE ID of the parent layer when parented                                  |

### Pagination

Both `/compositions` and `/layers` support `limit` and `offset` query parameters (default `limit` is 300, max 1000). Use these for templates with large numbers of layers:

```bash theme={null}
curl "https://api.nexrender.com/api/v3/templates/01JTGM9GCR71JV7EJYDF45QAFD/layers?limit=100&offset=200" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Template Status Values

| Status            | Meaning                                                    |
| ----------------- | ---------------------------------------------------------- |
| `awaiting_upload` | Template created but file not yet uploaded                 |
| `downloading`     | Template file is being fetched (clean room / remote `src`) |
| `processing`      | File received, introspection in progress                   |
| `uploaded`        | Introspection complete - ready for rendering               |
| `error`           | Processing failed - see the `error` field for details      |

## List All Templates

```bash theme={null}
curl -X GET https://api.nexrender.com/api/v3/templates \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Update Display Name

Use `PATCH /templates/{id}` to rename a template. Only `displayName` can be updated.

<CodeGroup>
  ```bash Request theme={null}
  curl -X PATCH https://api.nexrender.com/api/v2/templates/01JTGM9GCR71JV7EJYDF45QAFD \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "displayName": "Product Promo v2"
    }'
  ```

  ```json Response theme={null}
  {
    "id": "01JTGM9GCR71JV7EJYDF45QAFD",
    "type": "zip",
    "displayName": "Product Promo v2",
    "status": "uploaded"
  }
  ```
</CodeGroup>

## Download the Source File

`GET /templates/{id}/download` returns a presigned URL for downloading the original template file from storage.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET https://api.nexrender.com/api/v2/templates/01JTGM9GCR71JV7EJYDF45QAFD/download \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```json Response theme={null}
  {
    "url": "https://nx1-assets-eu.cloudflarestorage.com/...?X-Amz-Expires=3600&..."
  }
  ```
</CodeGroup>

The URL is temporary - use it promptly. If you need to re-download, request a fresh URL via the same endpoint.

## Template Storage and Retention

Templates are persisted indefinitely unless deleted manually. Regularly delete old or unused templates to keep your account tidy - use `DELETE /templates/{id}` or see the [Deleting Templates](/docs/cloud/templates/deleting) page.

For clean room setups, templates can be stored in secure customer-owned storage rather than on Nexrender's side. In this case, template introspection (compositions, layers) and caching are not available - your job payloads must reference composition and layer names directly.

## API Reference


## OpenAPI

````yaml GET /v3/templates/{id}
openapi: 3.0.4
info:
  title: Nexrender API
  version: '2.0'
  description: >
    REST API for the Nexrender cloud rendering platform, enabling programmatic
    control over After Effects template processing, job management, and asset
    handling.


    Features include:


    - Template upload and management (AEP, MOGRT, ZIP files)

    - Job creation and status monitoring with real-time progress

    - Job nesting for multi-composition renders (parent/child jobs)

    - Job stitching to combine multiple videos into one

    - Batch job creation for submitting up to 1000 jobs at once

    - Font library management for typography consistency

    - Secret management for secure API key storage

    - Webhook notifications for job lifecycle events

    - Asset injection for dynamic content replacement


    Authentication is required for all endpoints using Bearer token
    authorization.
servers:
  - url: https://api.nexrender.com/api/v2
    description: Production API server
security:
  - apiToken: []
paths:
  /v3/templates/{id}:
    servers:
      - url: https://api.nexrender.com/api
        description: Production API server
    get:
      tags:
        - Template Management
      summary: Get template metadata (v3)
      description: >-
        Retrieve lightweight metadata for one template. Use the compositions and
        layers subresources to inspect template structure.
      operationId: getTemplateV3
      parameters:
        - in: path
          name: id
          required: true
          description: Unique template identifier in ULID format
          schema:
            type: string
            pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
      responses:
        '200':
          description: Successfully retrieved template metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateV3'
        '400':
          description: Invalid template id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            Template not found - the specified template ID does not exist or is
            not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    TemplateV3:
      type: object
      description: >-
        Lightweight template metadata returned by the v3 template API.
        Composition and layer structure is exposed through separate paginated
        endpoints.
      properties:
        id:
          type: string
          pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
          description: >-
            Unique template identifier used for referencing in jobs and API
            operations
        type:
          type: string
          enum:
            - aep
            - zip
            - mogrt
          description: Template file format
        displayName:
          type: string
          description: Human-readable template name
        status:
          type: string
          enum:
            - awaiting_upload
            - downloading
            - processing
            - uploaded
            - error
          description: Current template processing status
        createdAt:
          type: string
          format: date-time
          description: ISO timestamp when the template was created
        updatedAt:
          type: string
          format: date-time
          description: ISO timestamp when the template was last updated
      required:
        - id
        - type
        - displayName
        - status
        - createdAt
        - updatedAt
    ErrorResponse:
      type: object
      description: Standard error response format
      properties:
        error:
          type: string
          description: Human-readable error message explaining what went wrong
      required:
        - error
  securitySchemes:
    apiToken:
      type: http
      scheme: bearer
      description: >
        Bearer token authentication using API tokens for team-based access
        control.


        You can generate your own API token at:
        https://app.nexrender.com/settings/api-tokens

````