> ## Documentation Index
> Fetch the complete documentation index at: https://docs.docyard.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Template

> Create a new artifact type template

# Create Template

Create a new artifact type template. Templates start in `draft` status and must be approved before use.

## Endpoint

```
POST /templates
```

## Request

### Headers

| Header         | Required | Description                |
| -------------- | -------- | -------------------------- |
| `X-API-Key`    | Yes      | Your API key               |
| `X-API-Secret` | Yes      | Your API secret            |
| `Content-Type` | Yes      | Must be `application/json` |

### Body Parameters

| Parameter     | Type   | Required | Description                               |
| ------------- | ------ | -------- | ----------------------------------------- |
| `name`        | string | Yes      | Template name (max 100 characters)        |
| `description` | string | No       | Template description (max 500 characters) |
| `locks`       | array  | Yes      | Array of lock definitions                 |

### Lock Definition Object

| Parameter     | Type    | Required | Description                                      |
| ------------- | ------- | -------- | ------------------------------------------------ |
| `name`        | string  | Yes      | Lock name (snake\_case, alphanumeric)            |
| `data_type`   | string  | Yes      | Data type: `string`, `number`, `date`, `boolean` |
| `description` | string  | No       | Human-readable description                       |
| `validation`  | object  | No       | Validation rules                                 |
| `weight`      | integer | Yes      | Weight score (1-100)                             |
| `required`    | boolean | Yes      | Whether lock is required                         |

### Validation Object (Optional)

| Parameter    | Type    | Description               |
| ------------ | ------- | ------------------------- |
| `pattern`    | string  | Regex pattern for strings |
| `min_length` | integer | Minimum string length     |
| `max_length` | integer | Maximum string length     |
| `min`        | number  | Minimum value for numbers |
| `max`        | number  | Maximum value for numbers |

## Example Request

```bash theme={null}
curl -X POST https://api.docyard.io/v1/templates \
  -H "X-API-Key: dk_live_dist_aaaaaaaa" \
  -H "X-API-Secret: dk_secret_dist_bbbbbbbb" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Insurance Declaration Page",
    "description": "Standard insurance policy declaration document",
    "locks": [
      {
        "name": "policy_number",
        "data_type": "string",
        "description": "Unique insurance policy identifier",
        "validation": {
          "pattern": "^POL-[0-9]{8}$",
          "min_length": 12,
          "max_length": 12
        },
        "weight": 20,
        "required": true
      },
      {
        "name": "effective_date",
        "data_type": "date",
        "description": "Date the policy coverage begins",
        "weight": 10,
        "required": true
      },
      {
        "name": "mortgagee_name",
        "data_type": "string",
        "description": "Name of the mortgagee/lender",
        "weight": 5,
        "required": false
      },
      {
        "name": "property_address",
        "data_type": "string",
        "description": "Insured property address",
        "weight": 5,
        "required": false
      }
    ]
  }'
```

## Response

### Success (201 Created)

```json theme={null}
{
  "template_id": "tmpl-ins-dec-001",
  "name": "Insurance Declaration Page",
  "description": "Standard insurance policy declaration document",
  "status": "draft",
  "locks": [
    {
      "name": "policy_number",
      "data_type": "string",
      "description": "Unique insurance policy identifier",
      "validation": {
        "pattern": "^POL-[0-9]{8}$",
        "min_length": 12,
        "max_length": 12
      },
      "weight": 20,
      "required": true
    },
    {
      "name": "effective_date",
      "data_type": "date",
      "description": "Date the policy coverage begins",
      "weight": 10,
      "required": true
    },
    {
      "name": "mortgagee_name",
      "data_type": "string",
      "description": "Name of the mortgagee/lender",
      "weight": 5,
      "required": false
    },
    {
      "name": "property_address",
      "data_type": "string",
      "description": "Insured property address",
      "weight": 5,
      "required": false
    }
  ],
  "created_at": "2026-03-15T10:00:00Z",
  "message": "Template created as draft. Submit for review when ready."
}
```

## Error Responses

### Validation Error (422)

```json theme={null}
{
  "error": "validation_error",
  "message": "Template validation failed",
  "details": [
    {
      "field": "locks[0].name",
      "issue": "required"
    },
    {
      "field": "locks[0].weight",
      "issue": "must be between 1 and 100"
    }
  ],
  "request_id": "req-abc123xyz"
}
```

### Too Many Templates (429)

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Too many templates created. Please wait before creating more.",
  "retry_after": 60,
  "request_id": "req-abc123xyz"
}
```

## Code Examples

### Node.js

```javascript theme={null}
const template = await client.templates.create({
  name: 'Insurance Declaration Page',
  description: 'Standard insurance policy declaration document',
  locks: [
    {
      name: 'policy_number',
      data_type: 'string',
      validation: { pattern: '^POL-[0-9]{8}$' },
      weight: 20,
      required: true
    },
    {
      name: 'effective_date',
      data_type: 'date',
      weight: 10,
      required: true
    }
  ]
});
```

### Python

```python theme={null}
template = client.templates.create(
    name='Insurance Declaration Page',
    description='Standard insurance policy declaration document',
    locks=[
        {
            'name': 'policy_number',
            'data_type': 'string',
            'validation': {'pattern': '^POL-[0-9]{8}$'},
            'weight': 20,
            'required': True
        },
        {
            'name': 'effective_date',
            'data_type': 'date',
            'weight': 10,
            'required': True
        }
    ]
)
```

***

## Next Steps

* [Submit Template for Review](/api-reference/artifact-types/submit) - Submit for admin approval
* [List Templates](/api-reference/artifact-types/list) - View all templates