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

# The Flag objects

> Two independent flag systems: people flags tag a person; skill flags tag a person at one of four career scopes

<Info>
  **Quick Summary:** There are TWO flag systems sharing no tables: **people flags** (`/api/v1/people-flags`) tag a person; **skill flags** (`/api/v1/skill-flags`) tag a person at a career, section, skill-group or skill scope. A *flag* is the company-configured type; a *flag assignment* is a person carrying one.
</Info>

## Attributes (both systems)

| Field                            | Type           | Description                                                                                                                     |
| -------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `id`                             | string         | Opaque flag id                                                                                                                  |
| `name` / `description` / `color` | —              | Display fields                                                                                                                  |
| `isEnabled`                      | boolean        | See the disable warning below                                                                                                   |
| `isSystemDefault`                | boolean        | System defaults cannot be deleted, only disabled                                                                                |
| `position`                       | number \| null | Order within the list                                                                                                           |
| `designatesTrainer`              | boolean        | **Skill flags only** — turns assignment into a competency signal driving trainer counts, metrics and the training approver pool |

<Warning>
  **Disabling hides existing assignments — it does not merely block new ones.** Every assignment of a disabled flag disappears from the assignment reads, and for skill flags also from trainer counts, metrics and the training approver pool: someone carrying a trainer-designating flag stops counting as a trainer the moment it is disabled. **No rows are deleted** — re-enabling restores everything. An integrator reconciling assignments will otherwise see rows vanish with no corresponding delete.
</Warning>

## People flags

CRUD plus `POST /{id}/enable`, `POST /{id}/disable`, `POST /reorder`, `GET /{id}/dependencies`, and a guarded `DELETE /{id}` (409 with the holder count; `?confirm=true` proceeds). Assignments: `GET /people-flags/{id}/people`, and per person `GET|POST|DELETE /people/{id}/people-flags` — each assignment carries who assigned it and when.

**Visibility** exists **only for people flags**: one company-wide setting per audience at `GET|PATCH /people-flags/visibility` (administrators always see them — not configurable), and `GET /people-flags/visibility/me` resolves the answer for the acting identity.

## Skill flags

The same lifecycle surface plus `PATCH /{id}/trainer-designation`. Dependencies and the guarded delete report counts **per scope**. Assignments live at `/api/v1/skill-flag-assignments/{scope}` where scope is `careers`, `sections`, `skill-groups` or `skills` — query with filters, `POST` applies in bulk, `DELETE` removes in bulk.

<Note>
  **The skill scope is not career-relative.** Career, section and skill-group assignments carry the career; a skill-scope assignment keys off the skill alone and returns `careerId: null`. The four scopes are deliberately not squeezed into one shape.
</Note>

Trainer tracking: `GET /api/v1/skill-groups/{id}/trainer-count` counts people carrying an enabled trainer-designating flag for the group.

## Not published

`FlagType` — every assignment row internally duplicates the flag's display name as a string, and it drifts when the flag is renamed. The API publishes the flag reference only.