> ## Documentation Index
> Fetch the complete documentation index at: https://lopiv2-invenicum-25.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```http theme={null}
GET /templates/market
```

Retrieves all public templates available in the marketplace.

**Authentication**: Required

**Response**

```json theme={null}
[
  {
    "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

```http theme={null}
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**

```http theme={null}
GET /templates/detail/template-123
```

**Response**

```json theme={null}
{
  "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

```http theme={null}
GET /templates/my-library
```

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

**Authentication**: Required

**Response**

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

### Publish Template

```http theme={null}
POST /templates/publish
```

Publishes a new template to the marketplace.

**Authentication**: Required

**Request Body**

```json theme={null}
{
  "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**

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

### Track Download

```http theme={null}
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**

```http theme={null}
POST /templates/template-123/download
```

**Response**

```json theme={null}
{
  "success": true,
  "downloadCount": 3543
}
```

> [!NOTE]
>
> 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

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

### Number Field

```json theme={null}
{
  "name": "Price",
  "type": "number",
  "required": true,
  "defaultValue": 0,
  "validation": {
    "min": 0,
    "max": 999999.99
  }
}
```

### Boolean Field

```json theme={null}
{
  "name": "Is Published",
  "type": "boolean",
  "defaultValue": false
}
```

### Select Field

```json theme={null}
{
  "name": "Status",
  "type": "select",
  "required": true,
  "options": ["Draft", "Review", "Published", "Archived"],
  "defaultValue": "Draft"
}
```

### Date Field

```json theme={null}
{
  "name": "Release Date",
  "type": "date",
  "required": false,
  "defaultValue": "2026-03-07"
}
```

### Multi-select Field

```json theme={null}
{
  "name": "Platforms",
  "type": "multiselect",
  "options": ["Web", "iOS", "Android", "Desktop"],
  "defaultValue": ["Web"]
}
```

## SDK Usage

### Get Market Templates

```dart theme={null}
final templates = await templateService.getMarketTemplates();

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

### Publish a Template

```dart theme={null}
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

```dart theme={null}
await templateService.trackDownload('template-123');
```

## Authentication

All template endpoints require a valid Bearer token:

```http theme={null}
Authorization: Bearer <your-token>
```

## Error Responses

```json theme={null}
{
  "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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.