# Repo-Level Labels

Labels scoped to a single repository. These are the most common labels.

## Endpoints

### List repo labels

```
GET /repos/{owner}/{repo}/labels
```

**Query parameters:**
| Param | Type | Description |
|-------|------|-------------|
| `page` | integer | Page number (1-based) |
| `limit` | integer | Items per page |

**Response:** Array of Label objects.

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/labels?page=1&limit=50"
```

### Create a label

```
POST /repos/{owner}/{repo}/labels
```

**Body: CreateLabelOption**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | **yes** | Label name |
| `color` | string | **yes** | 6-char hex color, no `#` prefix (e.g., `"00aabb"`) |
| `description` | string | no | Label description |
| `exclusive` | boolean | no | Whether this label is exclusive (default: false) |
| `is_archived` | boolean | no | Whether this label is archived (default: false) |

**Color format:** Must be a 6-character hexadecimal string WITHOUT the `#` prefix. Examples: `"e11d48"`, `"00aabb"`, `"ffffff"`. Passing `"#e11d48"` will be rejected.

```bash
# Create a simple label
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "bug",
    "color": "{color}",
    "description": "{label_description}"
  }' \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/labels"

# Create an exclusive label (part of a scope group)
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Priority/High",
    "color": "{color}",
    "description": "{label_description}",
    "exclusive": true
  }' \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/labels"
```

### Get a label

```
GET /repos/{owner}/{repo}/labels/{id}
```

**Path parameters:**
| Param | Type | Description |
|-------|------|-------------|
| `id` | integer | Label ID |

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/labels/{label_id}"
```

### Edit a label

```
PATCH /repos/{owner}/{repo}/labels/{id}
```

**Body: EditLabelOption** — All fields are optional. Only include fields you want to change.

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | New name |
| `color` | string | New hex color (no `#`) |
| `description` | string | New description |
| `exclusive` | boolean | New exclusive status |
| `is_archived` | boolean | New archived status |

```bash
# Rename a label and change its color
curl -s -X PATCH \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "critical-bug",
    "color": "{color}"
  }' \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/labels/{label_id}"

# Archive a label (hides from new selections but keeps it on existing issues)
curl -s -X PATCH \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "is_archived": true
  }' \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/labels/{label_id}"
```

### Delete a label

```
DELETE /repos/{owner}/{repo}/labels/{id}
```

This removes the label definition AND removes it from all issues/PRs that had it.

```bash
curl -s -X DELETE \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/labels/{label_id}"
```

## Example: Create a Full Exclusive Label Set

```bash
# Create Priority scope with 3 exclusive labels
for entry in "Priority/Low:{color}" "Priority/Medium:{color}" "Priority/High:{color}"; do
  name="${entry%%:*}"
  color="${entry##*:}"
  curl -s -X POST \
    -H "Authorization: token ${FORGEJO_PAT}" \
    -H "Content-Type: application/json" \
    -d "{\"name\": \"${name}\", \"color\": \"${color}\", \"exclusive\": true}" \
    "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/labels"
done
```
