# Label Templates

Forgejo ships with predefined sets of labels (templates) that can be applied when creating a repository. These endpoints let you discover what templates are available and inspect their contents.

## Endpoints

### List available label template sets

```
GET /label/templates
```

Returns an array of template name strings.

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/label/templates"
```

**Example response:**
```json
[
  "Advanced",
  "Gitea/Default"
]
```

### Get labels from a template

```
GET /label/templates/{name}
```

**Path parameters:**
| Param | Type | Description |
|-------|------|-------------|
| `name` | string | Template name from the list endpoint |

Returns an array of Label objects defined in the template.

```bash
# Get all labels from the "Advanced" template
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/label/templates/Advanced"
```

**Example response:**
```json
[
  {
    "id": 0,
    "name": "Kind/Bug",
    "exclusive": true,
    "color": "ee0701",
    "description": "Something is not working as expected"
  },
  {
    "id": 0,
    "name": "Kind/Feature",
    "exclusive": true,
    "color": "0e8a16",
    "description": "Request for a new feature or enhancement"
  },
  {
    "id": 0,
    "name": "Priority/Critical",
    "exclusive": true,
    "color": "b60205",
    "description": "This issue must be resolved immediately"
  }
]
```

Note: The `id` field in template responses is `0` because these are template definitions, not actual labels. Labels get real IDs when they are created in a repository.

## How Templates Are Used

Label templates are primarily used at **repository creation time**. When creating a repo, you can specify an `issue_labels` option to pre-populate the repo with a template's labels:

```bash
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "{repo}",
    "auto_init": true,
    "issue_labels": "Advanced"
  }' \
  "${FORGEJO_URL}/api/v1/user/repos"
```

## Manually Applying a Template to an Existing Repo

There is no single API call to apply a template to an existing repo. You must fetch the template and create each label individually:

```bash
OWNER="{owner}"
REPO="{repo}"
TEMPLATE="Advanced"

# Fetch template labels and create each one in the repo
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/label/templates/${TEMPLATE}" | \
  jq -c '.[]' | while read -r label; do
    name=$(echo "$label" | jq -r '.name')
    color=$(echo "$label" | jq -r '.color')
    desc=$(echo "$label" | jq -r '.description')
    exclusive=$(echo "$label" | jq -r '.exclusive')

    curl -s -X POST \
      -H "Authorization: token ${FORGEJO_PAT}" \
      -H "Content-Type: application/json" \
      -d "{\"name\": \"${name}\", \"color\": \"${color}\", \"description\": \"${desc}\", \"exclusive\": ${exclusive}}" \
      "${FORGEJO_URL}/api/v1/repos/${OWNER}/${REPO}/labels"
done
```
