# Template Management {#template-management}



## Overview {#overview}


Survey templates provide reusable survey structures that can be used as starting points for new surveys. Templates include question structure, validation rules, calendar rules, and metadata.


## Template Lifecycle {#template-lifecycle}


```
Draft ──► Published ──► Deprecated
  │                        │
  └── (editable)      Archived
```

| State | Description |
|-------|-------------|
| **Draft** | In creation, only author/editors can see |
| **Published** | Available for use when creating surveys |
| **Deprecated** | Still exists but hidden from new survey creation |
| **Archived** | Removed from active use, retained for history |


## Creating Templates {#creating-templates}


```python
POST /templates
{
  "name": "Patient Follow-up Survey",
  "category_id": "cat-uuid",
  "schema": { /* full survey schema */ },
  "description": "Standard patient follow-up template",
  "is_public": true
}
```


## Creating a Survey from a Template {#creating-a-survey-from-a-template}


```python
POST /templates/{id}/create-survey
{
  "name": "Q1 2026 Patient Follow-up",
  "workspace_id": "ws-uuid"
}

# Copies schema, resets published state to draft
```


## Template Categories {#template-categories}


```python
GET /template-categories
# Returns grouped templates for the UI

POST /template-categories
{
  "name": "Healthcare",
  "icon": "heart-pulse",
  "order": 1
}
```


## Versioning {#versioning}


Templates support versioning, allowing users to update a template without breaking existing surveys created from it:

```python
# When template is updated, existing surveys keep the old version
# New surveys use the new version
```


## Permissions {#permissions}


| Role | Draft | Published | Deprecated | Archive |
|------|-------|-----------|------------|---------|
| Template Admin | Create/Edit | Publish | Deprecate | Archive |
| Editor | Create/Edit | — | — | — |
| Viewer | View | View | — | — |
| User | — | Use | — | — |


## Import/Export {#importexport}


```bash
# Export template as JSON
GET /templates/{id}/export

# Import template from JSON
POST /templates/import
Content-Type: application/json

{ "schema": { ... }, "name": "Imported Template" }
```