# Repository Flags API Reference

Repository flags are admin-only markers that can be applied to repositories. This is a **Forgejo-specific feature** and may not be available on Gitea instances or Forgejo instances where the feature is disabled.

---

## Endpoints

### List All Flags on a Repository

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

Returns an array of flag strings currently set on the repository.

**Response:** `200` with `["flag1", "flag2"]` or `[]` if no flags.

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

### Check if a Repository Has a Specific Flag

```
GET /repos/{owner}/{repo}/flags/{flag}
```

**Response Codes:**

| Code | Meaning                          |
|------|----------------------------------|
| 204  | Flag is present on the repo      |
| 404  | Flag is not present on the repo  |

```bash
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/flags/{flag}" \
  -H "Authorization: token ${FORGEJO_PAT}")

if [ "$HTTP_CODE" = "204" ]; then
  echo "Repo has '${FLAG}' flag."
else
  echo "Repo does NOT have '${FLAG}' flag."
fi
```

### Add a Flag to a Repository

```
PUT /repos/{owner}/{repo}/flags/{flag}
```

**Response Codes:**

| Code | Meaning                              |
|------|--------------------------------------|
| 204  | Flag added successfully              |
| 403  | Permission denied (not admin)        |
| 404  | Feature disabled or repo not found   |

```bash
curl -s -o /dev/null -w "%{http_code}" -X PUT \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/flags/{flag}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Remove a Specific Flag

```
DELETE /repos/{owner}/{repo}/flags/{flag}
```

**Response Codes:**

| Code | Meaning                              |
|------|--------------------------------------|
| 204  | Flag removed successfully            |
| 403  | Permission denied (not admin)        |
| 404  | Flag not found or feature disabled   |

```bash
curl -s -o /dev/null -w "%{http_code}" -X DELETE \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/flags/{flag}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

### Replace All Flags

```
PUT /repos/{owner}/{repo}/flags
```

Replaces the entire set of flags on the repository. Any existing flags not in the new array are removed.

**JSON Body:**

| Field | Type          | Description                       |
|-------|---------------|-----------------------------------|
| flags | array[string] | Complete set of flags to apply    |

**Response Codes:**

| Code | Meaning                              |
|------|--------------------------------------|
| 204  | Flags replaced successfully          |
| 403  | Permission denied (not admin)        |
| 404  | Feature disabled or repo not found   |

```bash
# Replace all flags with a new set
curl -s -o /dev/null -w "%{http_code}" -X PUT \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/flags" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"flags": ["{flag1}", "{flag2}", "{flag3}"]}'
```

**Note:** The body format is `{"flags": ["flag1", "flag2"]}` — an object with a `flags` key containing an array, not a bare array.

### Remove All Flags

```
DELETE /repos/{owner}/{repo}/flags
```

Removes all flags from the repository.

**Response Codes:**

| Code | Meaning                              |
|------|--------------------------------------|
| 204  | All flags removed                    |
| 403  | Permission denied (not admin)        |
| 404  | Feature disabled or repo not found   |

```bash
curl -s -o /dev/null -w "%{http_code}" -X DELETE \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/flags" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

## Use Cases for Flags

Flags are free-form strings with no predefined values — admins define whatever flags make sense for their instance. Common use cases include:

| Use Case              | Example Flags                          | Description                                                  |
|-----------------------|----------------------------------------|--------------------------------------------------------------|
| **Moderation**        | `moderated`, `nsfw`, `under-review`    | Mark repos that need review or contain restricted content    |
| **Featured repos**    | `featured`, `staff-pick`               | Highlight repos on the instance explore page or custom UIs   |
| **Compliance**        | `verified`, `official`, `audited`      | Mark repos that meet organizational compliance standards     |
| **Lifecycle**         | `deprecated`, `archived-pending`       | Track repo lifecycle states beyond Forgejo's built-in archive |
| **CI/CD integration** | `auto-deploy`, `staging`               | Flags that external tooling checks before performing actions |

---

## Common Patterns

### Toggle a Flag

```bash
FLAG="{flag}"

# Check current state
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
  "${FORGEJO_URL}/api/v1/repos/${OWNER}/${REPO}/flags/${FLAG}" \
  -H "Authorization: token ${FORGEJO_PAT}")

if [ "$HTTP_CODE" = "204" ]; then
  # Flag exists, remove it
  curl -s -X DELETE "${FORGEJO_URL}/api/v1/repos/${OWNER}/${REPO}/flags/${FLAG}" \
    -H "Authorization: token ${FORGEJO_PAT}"
  echo "Removed '${FLAG}' flag."
else
  # Flag doesn't exist, add it
  curl -s -X PUT "${FORGEJO_URL}/api/v1/repos/${OWNER}/${REPO}/flags/${FLAG}" \
    -H "Authorization: token ${FORGEJO_PAT}"
  echo "Added '${FLAG}' flag."
fi
```

### Audit Flags Across Repos

```bash
# Check multiple repos for a specific flag
for REPO in {repo1} {repo2} {repo3}; do
  HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
    "${FORGEJO_URL}/api/v1/repos/${OWNER}/${REPO}/flags/{flag}" \
    -H "Authorization: token ${FORGEJO_PAT}")
  
  if [ "$HTTP_CODE" = "204" ]; then
    echo "${REPO}: verified"
  else
    echo "${REPO}: NOT verified"
  fi
done
```

---

## Notes

- **Admin only:** All flag endpoints require site admin privileges. Non-admin users will receive `403 Forbidden`.
- **Forgejo-specific:** This feature is specific to Forgejo and is not available on standard Gitea instances. On Forgejo instances where the feature is disabled, all endpoints return `404`.
- **Free-form strings:** Flag values are arbitrary strings. There is no predefined list — use whatever naming convention suits your instance.
- **No built-in UI filtering:** Flags are primarily an API feature. To build user-facing experiences (e.g., a "featured repos" page), you need custom tooling that queries the flag endpoints.
