Documentation

Template System API

SmartCV template system API documentation, including template management, custom styles and other features

Updated: 12/30/2024

SmartCV template system provides rich resume templates and customization features, supporting template queries, application, custom styles and other operations.

📋 API Endpoint Overview

Endpoint	Method	Description
`/api/templates`	GET	Get template list
`/api/templates/[id]`	GET	Get template details
`/api/templates`	POST	Create new template (admin)
`/api/templates/[id]`	PUT	Update template (admin)
`/api/templates/[id]`	DELETE	Delete template (admin)

🔍 Get Template List

Endpoint: GET /api/templates

Description: Get available resume template list

Authentication: Optional (affects premium template visibility)

Query Parameters:

category (optional): Template category (MODERN, PROFESSIONAL, CREATIVE, MINIMALIST, ACADEMIC)
isPremium (optional): Whether it's a premium template (true, false)
limit (optional): Return count limit, default is 20
offset (optional): Offset, default is 0

Response:

{
  "success": true,
  "data": [
    {
      "id": "template_123",
      "name": "Modern Minimal",
      "description": "Clean modern design style, suitable for most industries",
      "category": "MODERN",
      "previewUrl": "https://storage.smartcv.cc/templates/modern-preview.jpg",
      "thumbnailUrl": "https://storage.smartcv.cc/templates/modern-thumb.jpg",
      "isPremium": false,
      "usageCount": 1500,
      "ratingAvg": 4.5,
      "ratingCount": 120,
      "createdAt": "2024-01-15T10:00:00Z"
    },
    {
      "id": "template_456",
      "name": "Professional Business",
      "description": "Formal business style, suitable for traditional industries and senior positions",
      "category": "PROFESSIONAL",
      "previewUrl": "https://storage.smartcv.cc/templates/professional-preview.jpg",
      "thumbnailUrl": "https://storage.smartcv.cc/templates/professional-thumb.jpg",
      "isPremium": true,
      "usageCount": 800,
      "ratingAvg": 4.8,
      "ratingCount": 95,
      "createdAt": "2024-01-20T10:00:00Z"
    }
  ],
  "meta": {
    "total": 25,
    "limit": 20,
    "offset": 0,
    "userSubscriptionType": "FREE"
  }
}

📄 Get Template Details

Endpoint: GET /api/templates/[id]

Description: Get detailed information of specified template, including complete HTML template and CSS styles

Authentication: Optional (affects premium template access)

Path Parameters:

id: Template ID

Response:

{
  "success": true,
  "data": {
    "id": "template_123",
    "name": "Modern Minimal",
    "description": "Clean modern design style, suitable for most industries",
    "category": "MODERN",
    "htmlTemplate": "<!DOCTYPE html><html>...</html>",
    "cssStyles": ".resume { font-family: 'Arial', sans-serif; ... }",
    "previewUrl": "https://storage.smartcv.cc/templates/modern-preview.jpg",
    "thumbnailUrl": "https://storage.smartcv.cc/templates/modern-thumb.jpg",
    "isPremium": false,
    "customizableColors": true,
    "customizableFonts": true,
    "customizableSpacing": true,
    "usageCount": 1500,
    "ratingAvg": 4.5,
    "ratingCount": 120,
    "supportedSections": [
      "personalInfo",
      "workExperience",
      "education",
      "skills",
      "projects",
      "languages",
      "certifications"
    ],
    "colorSchemes": [
      {
        "name": "Default Blue",
        "primary": "#2563eb",
        "secondary": "#64748b",
        "accent": "#0ea5e9"
      },
      {
        "name": "Professional Green",
        "primary": "#059669",
        "secondary": "#6b7280",
        "accent": "#10b981"
      }
    ],
    "fontOptions": [
      {
        "name": "Roboto",
        "family": "'Roboto', sans-serif",
        "weights": ["300", "400", "500", "700"]
      },
      {
        "name": "Open Sans",
        "family": "'Open Sans', sans-serif",
        "weights": ["400", "600", "700"]
      }
    ],
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-12-30T10:00:00Z"
  }
}

➕ Create Template (Admin)

Endpoint: POST /api/templates

Description: Create new resume template (admin only)

Authentication: Requires admin privileges

Request Body:

{
  "name": "New Template Name",
  "description": "Template description",
  "category": "MODERN",
  "htmlTemplate": "<!DOCTYPE html><html>...</html>",
  "cssStyles": ".resume { ... }",
  "previewUrl": "https://storage.smartcv.cc/templates/new-preview.jpg",
  "thumbnailUrl": "https://storage.smartcv.cc/templates/new-thumb.jpg",
  "isPremium": false,
  "customizableColors": true,
  "customizableFonts": true,
  "customizableSpacing": true,
  "supportedSections": ["personalInfo", "workExperience", "education", "skills"],
  "colorSchemes": [
    {
      "name": "Default",
      "primary": "#2563eb",
      "secondary": "#64748b",
      "accent": "#0ea5e9"
    }
  ],
  "fontOptions": [
    {
      "name": "Roboto",
      "family": "'Roboto', sans-serif",
      "weights": ["400", "700"]
    }
  ]
}

Response:

{
  "success": true,
  "data": {
    "id": "template_789"
    /* Complete template information created */
  }
}

✏️ Update Template (Admin)

Endpoint: PUT /api/templates/[id]

Description: Update existing template (admin only)

Authentication: Requires admin privileges

Path Parameters:

id: Template ID

Request Body:

{
  "name": "Updated Template Name",
  "description": "Updated description",
  "htmlTemplate": "<!DOCTYPE html><html>...</html>",
  "cssStyles": ".resume { ... }",
  "isPremium": true,
  "isActive": true
}

Response:

{
  "success": true,
  "data": {
    /* Updated template information */
  }
}

🗑️ Delete Template (Admin)

Endpoint: DELETE /api/templates/[id]

Description: Delete specified template (admin only)

Authentication: Requires admin privileges

Path Parameters:

id: Template ID

Response:

{
  "success": true,
  "message": "Template deleted successfully"
}

🎨 Template Categories

Supported Template Categories

Category	Description	Applicable Scenarios
`MODERN`	Modern Minimal	Technology, internet, innovation industries
`PROFESSIONAL`	Professional Business	Traditional industries, management positions
`CREATIVE`	Creative Design	Designers, artists, creative work
`MINIMALIST`	Minimalist Style	Content-focused positions
`ACADEMIC`	Academic Style	Academia, research positions

Template Customization Options

Color Customization: Support for primary, secondary, and accent color customization
Font Customization: Multiple font choices and weight configuration
Spacing Customization: Adjust page margins, line spacing, paragraph spacing
Layout Adjustment: Support for single-column, double-column layout switching

📝 Usage Examples

JavaScript Example

// Get all templates
async function getAllTemplates() {
  const response = await fetch('/api/templates')
  const data = await response.json()
  return data.data
}
 
// Get templates by specific category
async function getTemplatesByCategory(category) {
  const response = await fetch(`/api/templates?category=${category}`)
  const data = await response.json()
  return data.data
}
 
// Get template details
async function getTemplateDetail(templateId) {
  const response = await fetch(`/api/templates/${templateId}`)
  const data = await response.json()
 
  if (data.success) {
    return data.data
  } else {
    throw new Error(data.error)
  }
}
 
// Apply template to resume
async function applyTemplateToResume(resumeId, templateId) {
  const response = await fetch(`/api/resumes/${resumeId}`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json'
    },
    credentials: 'include',
    body: JSON.stringify({
      templateId: templateId
    })
  })
 
  return response.json()
}

React Hook Example

import { useState, useEffect } from 'react'
 
function useTemplates(category = null, isPremium = null) {
  const [templates, setTemplates] = useState([])
  const [loading, setLoading] = useState(true)
  const [error, setError] = useState(null)
 
  useEffect(() => {
    fetchTemplates()
  }, [category, isPremium])
 
  const fetchTemplates = async () => {
    try {
      setLoading(true)
 
      const params = new URLSearchParams()
      if (category) params.append('category', category)
      if (isPremium !== null) params.append('isPremium', isPremium)
 
      const response = await fetch(`/api/templates?${params}`)
      const data = await response.json()
 
      if (data.success) {
        setTemplates(data.data)
      } else {
        setError(data.error)
      }
    } catch (err) {
      setError('Failed to fetch templates')
    } finally {
      setLoading(false)
    }
  }
 
  return {
    templates,
    loading,
    error,
    refetch: fetchTemplates
  }
}
 
// Template preview component
function TemplatePreview({ template, onApply }) {
  const [previewLoading, setPreviewLoading] = useState(false)
 
  const handleApply = async () => {
    setPreviewLoading(true)
    try {
      await onApply(template.id)
    } catch (error) {
      console.error('Failed to apply template:', error)
    } finally {
      setPreviewLoading(false)
    }
  }
 
  return (
    <div className="template-card">
      <img src={template.thumbnailUrl} alt={template.name} className="template-thumbnail" />
      <div className="template-info">
        <h3>{template.name}</h3>
        <p>{template.description}</p>
        <div className="template-meta">
          <span className="category">{template.category}</span>
          {template.isPremium && <span className="premium">Premium</span>}
          <span className="rating">★ {template.ratingAvg}</span>
        </div>
        <button onClick={handleApply} disabled={previewLoading} className="apply-button">
          {previewLoading ? 'Applying...' : 'Use Template'}
        </button>
      </div>
    </div>
  )
}

Template Customization Example

// Customize template colors
async function customizeTemplateColors(resumeId, colorScheme) {
  const response = await fetch(`/api/resumes/${resumeId}`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json'
    },
    credentials: 'include',
    body: JSON.stringify({
      customStyles: {
        colors: {
          primary: colorScheme.primary,
          secondary: colorScheme.secondary,
          accent: colorScheme.accent
        }
      }
    })
  })
 
  return response.json()
}
 
// Customize template font
async function customizeTemplateFont(resumeId, fontFamily) {
  const response = await fetch(`/api/resumes/${resumeId}`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json'
    },
    credentials: 'include',
    body: JSON.stringify({
      customStyles: {
        font: {
          family: fontFamily,
          size: {
            base: '14px',
            heading: '18px',
            subheading: '16px'
          }
        }
      }
    })
  })
 
  return response.json()
}

❌ Error Handling

Common Error Codes

Error Code	HTTP Status	Description
`TEMPLATE_NOT_FOUND`	404	Template does not exist
`PREMIUM_TEMPLATE_ACCESS_DENIED`	403	Requires paid subscription to access
`TEMPLATE_CREATION_FAILED`	500	Template creation failed
`INVALID_TEMPLATE_DATA`	400	Template data format error
`TEMPLATE_IN_USE`	409	Template is in use and cannot be deleted

Error Response Example

{
  "error": "This template requires a paid subscription to use",
  "code": "PREMIUM_TEMPLATE_ACCESS_DENIED",
  "details": {
    "templateId": "template_456",
    "templateName": "Professional Business",
    "userSubscriptionType": "FREE"
  }
}

Next Steps

👤 User Management

Learn about user information and account management related APIs

View User API →

🤖 AI Services

Learn how to use AI analysis and optimization features

View AI API →

Need help?Contact us for support

Getting Started User Guide Support

Last updated: 12/30/2024 •Suggest improvements