How do I render a Handlebars template via API?

To render a template, POST to /api/v1/templates/{name}/render with JSON variables in the body and X-API-Key header. The API returns rendered HTML directly.

How do I authenticate API requests to Template Tiger?

All API requests require an X-API-Key header. Create API keys at /api-keys in the web interface.

What are the rate limits for Template Tiger API?

Rate limit is 60 requests per minute per API key. Monitor X-RateLimit-Remaining header. Wait 60 seconds if you receive a 429 error.

What does TEMPLATE_NOT_FOUND error mean?

TEMPLATE_NOT_FOUND (404) means the template doesn't exist in your account. Verify the template name is spelled correctly and your API key belongs to the correct account.

Template Tiger

Integration Approaches

TemplateTiger offers two powerful integration patterns to fit your architecture and use case:

Server-Side Rendering

Recommended

Pattern: Send template variables to TemplateTiger and receive fully-rendered HTML.

POST /api/v1/templates/{name}/render

Best For:

Email generation and delivery systems
Server-side rendering workflows
Build-time static site generation
Systems where template content should remain server-controlled
Scenarios requiring consistent rendering across different client environments

Benefits:

Centralized template management and version control
Consistent rendering logic across all integrations
Reduced client-side dependencies
Template content remains secure on the server
Automatic updates when templates are modified

Example Use Case: Your application needs to send personalized welcome emails. You call the render endpoint with user data, and TemplateTiger returns ready-to-send HTML.

Client-Side Rendering

Advanced

Pattern: Retrieve raw template content and render it in your own application using Handlebars.js or similar templating engines.

GET /api/v1/templates/{name}

Best For:

High-performance applications requiring local rendering
Offline-capable applications
Systems with existing client-side templating infrastructure
Use-cases that can accept eventually-consistent template changes

Benefits:

Lower server load for repeated renders
Faster rendering after initial template fetch
Offline rendering capability
Full control over rendering pipeline
Reduced API calls for multiple renders of the same template

Example Use Case: Your document generation service creates PDFs from templates for hundreds of users. You fetch the template once and render it locally for each user's data, enabling efficient batch PDF generation while reducing server load and improving performance.

API Endpoint Reference

Send template variables and receive rendered HTML.

Request

POST /api/v1/templates/{templateName}/render HTTP/1.1
Host: app.templatetiger.dev
Content-Type: application/json
X-API-Key: your-api-key-here

{
  "variables": {
    "user": { "firstName": "Amina" },
    "company": "Acme Corp"
  }
}

Success Response (200)

HTTP/1.1 200 OK
Content-Type: text/html

<h1>Hello John Doe!</h1>
<p>Welcome to Acme Corp</p>
<p>Your email: [email protected]</p>
<p>Join date: 2024-01-15</p>

Error Responses

For error response codes (400, 401, 404, 500, 503) and detailed error handling guidance, see the Error Handling section.

Code Examples

curl -X POST \
  https://app.templatetiger.dev/api/v1/templates/welcome-email/render \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "company": "Acme Corp",
    "joinDate": "2024-01-15"
  }'

const response = await fetch('/api/v1/templates/welcome-email/render', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY_HERE'
  },
  body: JSON.stringify({
    name: 'John Doe',
    email: '[email protected]',
    company: 'Acme Corp',
    joinDate: '2024-01-15'
  })
});

if (response.ok) {
  const html = await response.text();
  console.log(html);
} else {
  const error = await response.json();
  console.error('Error:', error.message);
}

import requests

try:
    response = requests.post(
        'https://app.templatetiger.dev/api/v1/templates/welcome-email/render',
        json={
            'name': 'John Doe',
            'email': '[email protected]',
            'company': 'Acme Corp',
            'joinDate': '2024-01-15'
        }
    )
    response.raise_for_status()
    print(response.text)
except requests.exceptions.RequestException as e:
    print(f'Error: {e}')

import java.net.http.*;
import java.net.URI;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;

public class TemplateRenderer {
    private final HttpClient client;
    private final ObjectMapper mapper;

    public TemplateRenderer() {
        this.client = HttpClient.newHttpClient();
        this.mapper = new ObjectMapper();
    }

    public String renderTemplate(String templateName, Map<String, Object> data) throws Exception {
        Map<String, Object> requestData = Map.of(
            "name", data.get("name"),
            "email", data.get("email"),
            "company", data.get("company"),
            "joinDate", data.get("joinDate")
        );

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.templatetiger.dev/api/v1/templates/" + templateName + "/render"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(requestData)))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() == 200) {
            return response.body();
        } else {
            throw new RuntimeException("Template rendering failed: " + response.statusCode());
        }
    }

    public static void main(String[] args) throws Exception {
        TemplateRenderer renderer = new TemplateRenderer();

        Map<String, Object> data = Map.of(
            "name", "John Doe",
            "email", "[email protected]",
            "company", "Acme Corp",
            "joinDate", "2024-01-15"
        );

        String html = renderer.renderTemplate("welcome-email", data);
        System.out.println(html);
    }
}

Retrieve raw template content for client-side rendering.

Request

GET /api/v1/templates/{templateName} HTTP/1.1
Host: app.templatetiger.dev
X-API-Key: your-api-key-here

Success Response (200)

HTTP/1.1 200 OK
Content-Type: text/plain

<h1>Hello {{name}}!</h1>
<p>Welcome to {{company}}</p>
<p>Your email: {{email}}</p>
<p>Join date: {{joinDate}}</p>

Error Responses

For error response codes (400, 401, 404, 500, 503) and detailed error handling guidance, see the Error Handling section.

Code Examples

curl -X GET \
  https://app.templatetiger.dev/api/v1/templates/welcome-email

const response = await fetch('/api/v1/templates/welcome-email', {
  method: 'GET'
});

if (response.ok) {
  const templateContent = await response.text();
  console.log(templateContent);
} else {
  const error = await response.json();
  console.error('Error:', error.message);
}

import requests

try:
    response = requests.get(
        'https://app.templatetiger.dev/api/v1/templates/welcome-email'
    )
    response.raise_for_status()
    template_content = response.text
    print(template_content)
except requests.exceptions.RequestException as e:
    print(f'Error: {e}')

import java.net.http.*;
import java.net.URI;

public class TemplateFetcher {
    private final HttpClient client;

    public TemplateFetcher() {
        this.client = HttpClient.newHttpClient();
    }

    public String getTemplate(String templateName) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://app.templatetiger.dev/api/v1/templates/" + templateName))
            .GET()
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() == 200) {
            return response.body();
        } else {
            throw new RuntimeException("Template fetch failed: " + response.statusCode());
        }
    }

    public static void main(String[] args) throws Exception {
        TemplateFetcher fetcher = new TemplateFetcher();
        String templateContent = fetcher.getTemplate("welcome-email");
        System.out.println(templateContent);
    }
}

Authentication

Secure API Access with API Keys

All API requests require authentication using API keys. Create and manage your keys from your account settings.

How API Keys Work

Create API Key: Generate a secure API key from your account settings
Include in Requests: Add X-API-Key header to all API calls
Account Context: Keys automatically scope access to your account's templates

Getting Started

Log in to your TemplateTiger account
Navigate to the API Keys page (/api-keys)
Click "Create API Key"
Give your key a descriptive name
Copy the key immediately (shown only once)
Use the key in your API requests

Security Note: Store your API keys securely. They provide access to all templates in your account.

Handlebars Templating

TemplateTiger uses the Handlebars templating engine for powerful template rendering. Create dynamic content with variables, conditionals, and loops.

Need More Handlebars Help?

For comprehensive Handlebars documentation, syntax reference, and advanced features, visit the official guide.

Official Handlebars Guide

<h1>Hello {{name}}!</h1>
<p>Welcome to {{company}}</p>
<p>Your email: {{email}}</p>

{{#if isNewUser}}
<p>Welcome to our platform!</p>
{{else}}
<p>Welcome back!</p>
{{/if}}

{{#each features}}
<li>{{this.name}}: {{this.description}}</li>
{{/each}}

{{#with user}}
<p>Name: {{profile.firstName}} {{profile.lastName}}</p>
<p>Role: {{role.name}}</p>
{{/with}}

Error Handling

The API returns structured error responses to help you handle different scenarios effectively.

Error Codes

Rate Limit Details

Limit: 60 requests per minute per API key

The rate limit is tracked per API key using a fixed window algorithm. The window resets every 60 seconds.

Need higher limits? Contact [email protected] to discuss increased rate limits for your use case.

Rate Limit Headers

All API responses include headers that help you monitor your rate limit usage:

X-RateLimit-Limit: Maximum number of requests allowed per minute (60)
X-RateLimit-Remaining: Number of requests remaining in the current window

Fixed Window Algorithm

The API uses a fixed window algorithm to track rate limits:

Each API key has a counter that tracks requests within a 60-second window
The window automatically resets 60 seconds after the first request
Requests are counted atomically to ensure accuracy under concurrent load
When the limit is exceeded, the API returns a 429 error (see Error Handling)

Note: This is a fixed window algorithm. The window resets completely every 60 seconds, which means up to 120 requests could theoretically be made in a 2-minute span if timed at window boundaries (60 at the end of one window, 60 at the start of the next).

Best Practices

Monitor Headers: Check X-RateLimit-Remaining in responses to track your usage
Implement Exponential Backoff: When you receive a 429 error, wait before retrying with increasing delays
Batch Operations: If possible, batch multiple operations to reduce the number of API calls
Cache Results: Cache template content when using client-side rendering to minimize API requests
Handle 429 Gracefully: Implement proper error handling for rate limit errors in your application

Example: Monitoring Rate Limits

Check the rate limit headers in your API responses:

const response = await fetch('https://app.templatetiger.dev/api/v1/templates/welcome-email/render', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY_HERE'
  },
  body: JSON.stringify({ name: 'John' })
});

// Check rate limit headers
const limit = response.headers.get('X-RateLimit-Limit');
const remaining = response.headers.get('X-RateLimit-Remaining');

console.log(`Rate limit: ${remaining}/${limit} requests remaining`);

if (remaining < 10) {
  console.warn('Approaching rate limit, consider throttling requests');
}

Best Practices

Template Design

Use descriptive variable names
Provide fallback content with conditionals
Keep templates focused and reusable
Test with various data scenarios
Document expected data structure

API Integration

4xx Errors: Do not retry client errors - fix the request instead
500 Errors: Implement retry logic with exponential backoff and jitter (start with 1-2 second delays) for transient failures
503 Errors: Check the retryAfter field for suggested retry timing
Retry Limits: Limit retries to 3-5 attempts to avoid infinite loops
Monitoring: Monitor API calls and log all errors.
Caching: Cache rendered content when appropriate

TemplateTiger API Integration Guide

Integration Approaches

Server-Side Rendering

Best For:

Benefits:

Client-Side Rendering

Best For:

Benefits:

API Endpoint Reference

Server-Side Rendering Endpoint

Request

Success Response (200)

Error Responses

Code Examples

Client-Side Rendering Endpoint

Request

Success Response (200)

Error Responses

Code Examples

Authentication

Secure API Access with API Keys

How API Keys Work

Getting Started

Handlebars Templating

Need More Handlebars Help?

Error Handling

Error Codes

400 - RENDER_FAILED

Response Example

401 - AUTHENTICATION_FAILED

Response Example

404 - TEMPLATE_NOT_FOUND

Response Example

500 - INTERNAL_ERROR

Response Example

503 - SERVICE_UNAVAILABLE

Response Example

Rate Limiting

Rate Limit Details

Rate Limit Headers

Fixed Window Algorithm

Best Practices

Example: Monitoring Rate Limits

Best Practices

Template Design

API Integration