Template API

Access and manage asset templates from the marketplace

Overview

The Template API provides access to Invenicum’s template marketplace, allowing you to browse, publish, and install asset templates. Templates define reusable metadata structures for different types of assets.

Template Model

{
  "id": "string",
  "name": "string",
  "description": "string",
  "category": "string",
  "tags": ["string"],
  "author": "string",
  "authorAvatarUrl": "string",
  "downloadUrl": "string",
  "fields": [],
  "isOfficial": false,
  "isPublic": false,
  "downloadCount": 0,
  "createdAt": "2026-03-07T10:00:00Z",
  "updatedAt": "2026-03-07T10:00:00Z"
}

Fields

• id: Unique identifier for the template
• name: Display name of the template
• description: Detailed description of the template’s purpose
• category: Template category (e.g., “3D Models”, “Documents”, “Images”)
• tags: Array of searchable tags
• author: GitHub username or display name of the template creator
• authorAvatarUrl: URL to the author’s profile picture
• downloadUrl: Direct download URL for the template file
• fields: Array of custom field definitions (see below)
• isOfficial: Whether this is an official Invenicum template
• isPublic: Whether the template is published to the marketplace
• downloadCount: Number of times the template has been downloaded
• createdAt: Timestamp when the template was created
• updatedAt: Timestamp when the template was last modified

Custom Field Definition

{
  "id": "field-001",
  "name": "Material Type",
  "type": "text",
  "required": true,
  "defaultValue": "Plastic",
  "options": ["Metal", "Plastic", "Wood", "Composite"],
  "validation": {
    "pattern": "^[A-Z][a-z]+$",
    "minLength": 3,
    "maxLength": 50
  }
}

Endpoints

Get Market Templates

GET /templates/market

Retrieves all public templates available in the marketplace.

Authentication: Required

Response

[
  {
    "id": "template-123",
    "name": "3D Model Asset",
    "description": "Standard template for 3D model assets with material and geometry metadata",
    "category": "3D Models",
    "tags": ["3d", "modeling", "cad"],
    "author": "invenicum",
    "authorAvatarUrl": "https://avatars.githubusercontent.com/u/...",
    "downloadCount": 3542,
    "isOfficial": true,
    "fields": [
      {
        "name": "Polygon Count",
        "type": "number",
        "required": true
      },
      {
        "name": "Material Type",
        "type": "select",
        "options": ["PBR", "Unlit", "Toon"]
      }
    ]
  }
]

Get Template by ID

GET /templates/detail/:id

Retrieves the complete details of a specific template, including all field definitions.

Authentication: Required

Path Parameters

• id: The template ID

Example Request

GET /templates/detail/template-123

Response

{
  "id": "template-123",
  "name": "3D Model Asset",
  "description": "Standard template for 3D model assets",
  "category": "3D Models",
  "tags": ["3d", "modeling", "cad"],
  "author": "invenicum",
  "authorAvatarUrl": "https://avatars.githubusercontent.com/u/...",
  "downloadUrl": "https://...",
  "isOfficial": true,
  "isPublic": true,
  "downloadCount": 3542,
  "fields": [
    {
      "id": "field-001",
      "name": "Polygon Count",
      "type": "number",
      "required": true,
      "defaultValue": 10000
    },
    {
      "id": "field-002",
      "name": "Material Type",
      "type": "select",
      "required": true,
      "options": ["PBR", "Unlit", "Toon"],
      "defaultValue": "PBR"
    },
    {
      "id": "field-003",
      "name": "UV Mapped",
      "type": "boolean",
      "defaultValue": true
    }
  ],
  "createdAt": "2025-01-15T08:00:00Z",
  "updatedAt": "2026-02-10T14:30:00Z"
}

Get User Library

GET /templates/my-library

Returns all templates in the authenticated user’s personal library.

Authentication: Required

Response

[
  {
    "id": "template-456",
    "name": "Product Photography",
    "category": "Images",
    "isOfficial": false,
    "fields": [...]
  }
]

Publish Template

POST /templates/publish

Publishes a new template to the marketplace.

Authentication: Required

Request Body

{
  "name": "Product Photography",
  "description": "Template for product photo assets with lighting and camera metadata",
  "category": "Images",
  "tags": ["photography", "product", "studio"],
  "author": "octocat",
  "fields": [
    {
      "name": "Camera Model",
      "type": "text",
      "required": false
    },
    {
      "name": "Lighting Setup",
      "type": "select",
      "options": ["Natural", "Studio", "Mixed"],
      "required": true
    },
    {
      "name": "ISO",
      "type": "number",
      "required": false,
      "validation": {
        "min": 100,
        "max": 6400
      }
    }
  ],
  "isPublic": true
}

Response

{
  "success": true,
  "data": {
    "id": "template-789",
    "name": "Product Photography",
    "author": "octocat",
    "isPublic": true,
    "downloadCount": 0,
    "createdAt": "2026-03-07T10:30:00Z"
  }
}

Track Download

POST /templates/:templateId/download

Increments the download counter for a template. This is typically called automatically when a user installs a template to their library.

Authentication: Required

Path Parameters

• templateId: The template ID to track

Example Request

POST /templates/template-123/download

Response

{
  "success": true,
  "downloadCount": 3543
}

This endpoint is non-critical and will not throw errors if tracking fails. It’s designed for analytics purposes.

Field Types

Templates support the following custom field types:

Text Field

{
  "name": "Description",
  "type": "text",
  "required": true,
  "defaultValue": "Enter description",
  "validation": {
    "minLength": 10,
    "maxLength": 500,
    "pattern": "^[a-zA-Z0-9\\s]+$"
  }
}

Number Field

{
  "name": "Price",
  "type": "number",
  "required": true,
  "defaultValue": 0,
  "validation": {
    "min": 0,
    "max": 999999.99
  }
}

Boolean Field

{
  "name": "Is Published",
  "type": "boolean",
  "defaultValue": false
}

Select Field

{
  "name": "Status",
  "type": "select",
  "required": true,
  "options": ["Draft", "Review", "Published", "Archived"],
  "defaultValue": "Draft"
}

Date Field

{
  "name": "Release Date",
  "type": "date",
  "required": false,
  "defaultValue": "2026-03-07"
}

Multi-select Field

{
  "name": "Platforms",
  "type": "multiselect",
  "options": ["Web", "iOS", "Android", "Desktop"],
  "defaultValue": ["Web"]
}

SDK Usage

Get Market Templates

final templates = await templateService.getMarketTemplates();

for (final template in templates) {
  print('${template.name} by ${template.author}');
  print('Downloads: ${template.downloadCount}');
}

Publish a Template

final newTemplate = AssetTemplate(
  id: '', // Auto-generated
  name: 'Custom Product Template',
  description: 'Template for tracking product inventory',
  category: 'Inventory',
  tags: ['product', 'inventory', 'stock'],
  author: 'my-username',
  fields: [
    CustomFieldDefinition(
      name: 'SKU',
      type: 'text',
      required: true,
    ),
    CustomFieldDefinition(
      name: 'Stock Count',
      type: 'number',
      required: true,
      defaultValue: 0,
    ),
  ],
  isPublic: true,
);

final published = await templateService.publishTemplate(newTemplate);
print('Published with ID: ${published.id}');

Track a Download

await templateService.trackDownload('template-123');

Authentication

All template endpoints require a valid Bearer token:

Authorization: Bearer <your-token>

Error Responses

{
  "success": false,
  "message": "Template not found",
  "error": "TEMPLATE_NOT_FOUND"
}

Common Error Codes

• TEMPLATE_NOT_FOUND: The requested template does not exist
• INVALID_FIELDS: One or more field definitions are invalid
• DUPLICATE_NAME: A template with this name already exists
• PERMISSION_DENIED: User does not have permission to publish or modify this template
• VALIDATION_ERROR: Field validation rules are malformed