Templates

A Template is a versioned video bundle uploaded to a project. It contains the animation assets, binding manifest, and optional video files used by the Percus Player to render personalized videos.

Template kinds

Kind	Description
LottieStandalone	Pure Lottie/Bodymovin JSON animation with optional static assets
Raster	MP4 video base combined with a Lottie overlay for text and image personalization

Status lifecycle

Testing ──► Production ──► Previous
   │                           │
   └──────────────────────────►└──► Archived

Status	Meaning
Testing	Uploaded and available for internal testing. Not yet live.
Production	The active template served on the PROD channel. Only one template per project can be Production at a time.
Previous	Was previously Production. Kept for reference and rollback awareness.
Archived	Retired. Cannot be deleted if it was ever Production.

When a new template is deployed to Production, the current Production template automatically moves to Previous.

Uploading a template

Templates are uploaded as a multipart form to:

POST /api/Projects/{projectId}/templates/upload

Supported fields:

Field	Type	Required	Notes
name	string	✅	Template display name
version	string	—	Defaults to "1.0". Format: "major.minor"
kind	enum	✅	LottieStandalone or Raster
templateJson	file	—	Lottie JSON (inline, Phase 1)
manifestJson	file	—	Binding manifest JSON
overlayJson	file	—	Overlay config (Raster only)
videoFile	file	Raster only	MP4 background video
posterFile	file	—	Preview image
assetFiles	file[]	—	Additional static assets

Maximum upload size: 250 MB.

The Idempotency-Key header can be set to prevent duplicate uploads on retry.

Example (curl)

curl -X POST https://api.example.com/api/Projects/{projectId}/templates/upload \
  -H "Authorization: Bearer {token}" \
  -H "Idempotency-Key: unique-upload-id" \
  -F "name=Q2 Credit Card v1" \
  -F "kind=LottieStandalone" \
  -F "version=1.0" \
  -F "templateJson=@template.json" \
  -F "manifestJson=@manifest.json"

Deploying to Production

Deploying publishes a Testing template to the PROD distribution channel and marks it Production:

POST /api/Projects/{projectId}/templates/{templateId}/deploy

Requires ProjectManager or OrganizationAdmin role.

Alternatively, publish directly to a specific channel using the Distribution Channels API.

Archiving a template

POST /api/Projects/{projectId}/templates/{templateId}/archive

A template in Production status cannot be archived. Move it to Previous first by deploying a newer version.

Preview

Generate a preview render of a template with test data:

POST /api/Projects/{projectId}/templates/{templateId}/preview
{ "data": { "clientName": "Jane Doe", "balance": "$ 15,432" } }

Returns a signed URL to the rendered preview asset.

Versioning rules

• Versions are immutable. You cannot edit an uploaded template — upload a new version instead.
• The version field is a display label ("1.0", "2.0", etc.) set by the uploader.
• Only one template per project can be Production at any given time.