Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us