Template Management API

Last modified: May 16, 2025

This set of endpoints allows you to manage your template library with full CRUD (Create, Read, Update, Delete) operations. All operations are scoped to your account and require authentication.

Base URL

https://api.bulkdesign.app

Authentication

All template management endpoints require authentication using Bearer token with your API key:

Authorization: Bearer <YOUR_API_KEY>

List All Templates

Retrieve a paginated list of your templates with optional filtering and search capabilities.

GET Endpoint

GET /listAllTemplates

Query Parameters

• page (optional) - Page number for pagination (default: 1)
• limit (optional) - Number of templates per page (default: 10, max: 100)
• category (optional) - Filter by template category
• search (optional) - Search in template names and descriptions
• width (optional) - Filter by template width
• height (optional) - Filter by template height

Sample Request

curl --request GET \
     --url 'https://api.bulkdesign.app/listAllTemplates?page=1&limit=20&category=business&search=logo' \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

Successful Response

{
  "data": [
    {
      "id": "template-123456",
      "name": "Business Logo Template",
      "description": "Professional logo template for businesses",
      "category": "business",
      "imageUrl": "https://example.com/preview.jpg",
      "width": 800,
      "height": 600,
      "isPro": false,
      "content": {
        "canvas": {
          "width": 800,
          "height": 600
        },
        "items": [...]
      },
      "createdAt": "2025-05-16T10:00:00Z",
      "updatedAt": "2025-05-16T10:00:00Z"
    }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

Get Template by ID

Retrieve a specific template by its unique identifier.

GET Endpoint

GET /getTemplateById/:id

Path Parameters

• id (required) - The unique identifier of the template

Sample Request

curl --request GET \
     --url https://api.bulkdesign.app/getTemplateById/template-123456 \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

Successful Response

{
  "id": "template-123456",
  "name": "Business Logo Template",
  "description": "Professional logo template for businesses",
  "category": "business",
  "imageUrl": "https://example.com/preview.jpg",
  "width": 800,
  "height": 600,
  "isPro": false,
  "content": {
    "canvas": {
      "width": 800,
      "height": 600
    },
    "items": [
      {
        "id": "headline",
        "type": "text",
        "content": "Your Company Name",
        "replaceable": true,
        "x": 100,
        "y": 200,
        "fontSize": 32,
        "color": "#333333"
      }
    ]
  },
  "createdAt": "2025-05-16T10:00:00Z",
  "updatedAt": "2025-05-16T10:00:00Z"
}

Create Template

Create a new template in your library.

POST Endpoint

POST /createTemplate

Request Body

• name (optional) - Template name
• description (optional) - Template description
• category (required) - Template category
• imageUrl (optional) - Preview image URL
• content (required) - Template content structure
• isPro (optional) - Whether template is premium (default: false)
• width (optional) - Template width (auto-detected from content if not provided)
• height (optional) - Template height (auto-detected from content if not provided)

Sample Request

curl --request POST \
     --url https://api.bulkdesign.app/createTemplate \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '{
       "name": "My Custom Template",
       "description": "A custom template for marketing materials",
       "category": "marketing",
       "imageUrl": "https://example.com/preview.jpg",
       "content": {
         "canvas": {
           "width": 1200,
           "height": 800,
           "backgroundColor": "#ffffff"
         },
         "items": [
           {
             "id": "headline",
             "type": "text",
             "content": "Your Headline Here",
             "replaceable": true,
             "x": 100,
             "y": 100,
             "fontSize": 48,
             "color": "#333333",
             "fontFamily": "Arial, sans-serif"
           },
           {
             "id": "logo",
             "type": "image",
             "src": "https://example.com/logo.png",
             "replaceable": true,
             "x": 50,
             "y": 50,
             "width": 200,
             "height": 100
           }
         ]
       },
       "isPro": false
     }'

Successful Response

{
  "id": "template-789012",
  "name": "My Custom Template",
  "description": "A custom template for marketing materials",
  "category": "marketing",
  "imageUrl": "https://example.com/preview.jpg",
  "width": 1200,
  "height": 800,
  "isPro": false,
  "content": {
    "canvas": {
      "width": 1200,
      "height": 800,
      "backgroundColor": "#ffffff"
    },
    "items": [...]
  },
  "createdAt": "2025-05-16T10:30:00Z",
  "updatedAt": "2025-05-16T10:30:00Z"
}

Update Template

Update an existing template. Only provided fields will be updated.

PUT Endpoint

PUT /updateTemplate/:id

Path Parameters

• id (required) - The unique identifier of the template to update

Request Body

All fields are optional. Only provided fields will be updated:

• name - Template name
• description - Template description
• category - Template category
• imageUrl - Preview image URL
• content - Template content structure
• isPro - Whether template is premium
• width - Template width
• height - Template height

Sample Request

curl --request PUT \
     --url https://api.bulkdesign.app/updateTemplate/template-123456 \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '{
       "name": "Updated Template Name",
       "description": "Updated description",
       "category": "business"
     }'

Successful Response

{
  "id": "template-123456",
  "name": "Updated Template Name",
  "description": "Updated description",
  "category": "business",
  "imageUrl": "https://example.com/preview.jpg",
  "width": 800,
  "height": 600,
  "isPro": false,
  "content": {
    "canvas": {
      "width": 800,
      "height": 600
    },
    "items": [...]
  },
  "createdAt": "2025-05-16T10:00:00Z",
  "updatedAt": "2025-05-16T11:00:00Z"
}

Delete Template

Permanently delete a template from your library.

DELETE Endpoint

DELETE /deleteTemplate/:id

Path Parameters

• id (required) - The unique identifier of the template to delete

Sample Request

curl --request DELETE \
     --url https://api.bulkdesign.app/deleteTemplate/template-123456 \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

Successful Response

{
  "message": "Template deleted successfully"
}

Get Template Categories

Retrieve statistics about your template categories, including count of templates in each category.

GET Endpoint

GET /getTemplateCategories

Sample Request

curl --request GET \
     --url https://api.bulkdesign.app/getTemplateCategories \
     --header 'Authorization: Bearer <YOUR_API_KEY>'

Successful Response

[
  {
    "value": "",
    "label": "All Templates",
    "count": 45
  },
  {
    "value": "business",
    "label": "business",
    "count": 15
  },
  {
    "value": "marketing",
    "label": "marketing",
    "count": 12
  },
  {
    "value": "social",
    "label": "social",
    "count": 8
  },
  {
    "value": "education",
    "label": "education",
    "count": 5
  },
  {
    "value": "personal",
    "label": "personal",
    "count": 5
  }
]

Error Responses

All endpoints return appropriate HTTP status codes and error messages:

Common Error Codes

• 400 - Bad Request
• 401 - Unauthorized (invalid or missing API key)
• 404 - Template not found or access denied
• 500 - Internal server error

Error Response Format

{
  "error": "Error message describing what went wrong"
}

Example Error Responses

Missing API Key (401):

{
  "error": "Unauthorized"
}

Template Not Found (404):

{
  "error": "Template not found or access denied"
}

Missing Required Fields (400):

{
  "error": "Missing required fields: category and content"
}

Template Content Structure

Templates use a structured JSON format to define the canvas and elements:

Basic Structure

{
  "canvas": {
    "width": 1200,
    "height": 800,
    "backgroundColor": "#ffffff"
  },
  "items": [
    {
      "id": "unique-element-id",
      "type": "text|image|shape",
      "replaceable": true,
      // Element-specific properties...
    }
  ]
}

Canvas Properties

• width - Canvas width in pixels
• height - Canvas height in pixels
• backgroundColor - Background color (hex, rgb, or named color)

Element Types

Text Elements

{
  "id": "headline",
  "type": "text",
  "content": "Your text here",
  "replaceable": true,
  "x": 100,
  "y": 100,
  "fontSize": 32,
  "color": "#333333",
  "fontFamily": "Arial, sans-serif",
  "textAlign": "center",
  "bold": false,
  "italic": false
}

Image Elements

{
  "id": "logo",
  "type": "image",
  "src": "https://example.com/image.jpg",
  "replaceable": true,
  "x": 50,
  "y": 50,
  "width": 200,
  "height": 100,
  "cornerRadius": 8
}

Shape Elements

{
  "id": "background-shape",
  "type": "rectangle",
  "replaceable": false,
  "x": 0,
  "y": 0,
  "width": 400,
  "height": 200,
  "fillColor": "#f0f0f0",
  "strokeColor": "#cccccc",
  "strokeWidth": 1
}

Replaceable Elements

Elements marked with "replaceable": true can be dynamically updated when rendering templates using the Render Template API.

Usage Considerations

Template Organization

• Use descriptive names and categories for easy organization
• Include preview images (imageUrl) for better template management
• Use consistent naming conventions for element IDs

Content Structure Best Practices

• Mark elements as replaceable: true if they should be customizable during rendering
• Use semantic IDs for elements (e.g., "headline", "logo", "profile-image")
• Include fallback content for all replaceable elements

Performance Tips

• Keep template content structure reasonable in size
• Use appropriate image dimensions for your use case
• Consider template complexity when designing for bulk rendering

Data Privacy

• All templates are private to your account
• Templates cannot be accessed by other users
• Deleted templates are permanently removed and cannot be recovered

Integration Examples

Creating a Template Library

// Create multiple templates for different use cases
const templates = [
  {
    name: "Social Media Post",
    category: "social",
    content: {
      canvas: { width: 1080, height: 1080 },
      items: [
        {
          id: "main-text",
          type: "text",
          content: "Your message here",
          replaceable: true,
          x: 100,
          y: 400,
          fontSize: 48
        }
      ]
    }
  },
  {
    name: "Business Card",
    category: "business",
    content: {
      canvas: { width: 1050, height: 600 },
      items: [
        {
          id: "company-name",
          type: "text",
          content: "Company Name",
          replaceable: true,
          x: 50,
          y: 100,
          fontSize: 32
        }
      ]
    }
  }
];

// Create templates
for (const template of templates) {
  const response = await fetch('https://api.bulkdesign.app/createTemplate', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(template)
  });
  
  const result = await response.json();
  console.log('Created template:', result.id);
}

Template Management Workflow

// 1. List existing templates
const listResponse = await fetch('https://api.bulkdesign.app/listAllTemplates?category=business', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const { data: templates } = await listResponse.json();

// 2. Update a template
const templateId = templates[0].id;
await fetch(`https://api.bulkdesign.app/updateTemplate/${templateId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Updated Business Template",
    description: "Enhanced version with new features"
  })
});

// 3. Use template for rendering
await fetch('https://api.bulkdesign.app/render/template', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    templateId: templateId,
    format: 'jpg',
    jsonData: {
      "company-name": {
        "content": "Acme Corporation"
      }
    }
  })
});