# Linting API

Base path: `/api/v1/lint`

All endpoints require `Authorization: Bearer <jwt>`.

Related: [[03 - Metadata Linting]], [[02 - Videos API]], [[09 - Teams API]]

---

## POST /lint/videos/:id

Run lint rules against a single video synchronously. Returns the issues found immediately.

**Response:** `LintResult[]`

`resolvedAt` is always `null` on freshly created results — it is only set when a result is explicitly resolved via `PATCH /lint/results/:id/resolve`. `GET /lint/results` also always returns `null` for `resolvedAt` because it queries only unresolved rows (`WHERE resolvedAt IS NULL`).

---

## POST /lint/bulk

Enqueue lint jobs for multiple videos. Processing is asynchronous via BullMQ.

**Request body:**

```json
{ "videoIds": ["cuid", "cuid"] }
```

**Response:**

```json
{ "queued": number }
```

---

## POST /lint/channel/:channelId

Enqueue lint jobs for all videos in a given channel. Processing is asynchronous.

**Response:**

```json
{ "queued": number }
```

---

## POST /lint/team

Enqueue lint jobs for all videos in the current team. Processing is asynchronous.

**Response:**

```json
{ "queued": number }
```

---

## GET /lint/results

Get all open (unresolved) lint results for the current team.

**Query parameters:**

| Param | Type | Description |
|---|---|---|
| `severity` | `INFO\|WARNING\|ERROR` | Filter by severity level. `INFO` is valid but no current rule produces it — reserved for future informational hints. |
| `ruleCode` | string | Filter by rule code (e.g. `TITLE_WEAK`) |
| `videoId` | string | Filter by video ID |

**Response:**

```json
[
  {
    "id": "cuid",
    "videoId": "cuid",
    "ruleCode": "TITLE_WEAK",
    "severity": "WARNING",
    "targetField": "title",
    "message": "Title appears too generic",
    "fixSuggestion": "Use a more descriptive title",
    "resolvedAt": null,
    "createdAt": "ISO datetime",
    "video": {
      "id": "cuid",
      "title": "Video Title"
    }
  }
]
```

---

## PATCH /lint/results/:id/resolve

Mark a single lint result as resolved by setting `resolvedAt` to the current timestamp.

**Response:** Updated `LintResult`

---

## POST /lint/results/bulk-resolve

Mark multiple lint results as resolved in one request.

**Request body:**

```json
{ "ids": ["cuid", "cuid"] }
```

**Response:**

```json
{ "resolved": number }
```

---

## POST /lint/team/recompute-status

Recompute `lintStatus` for all videos in the current team based on their actual open `LintResult` rows. Use this to heal stale or inconsistent status values.

**Response:**

```json
{ "checked": number, "updated": number }
```

---

## Notes

- Individual lint rules can be disabled at the team level via `PATCH /teams/:teamId/settings` (`disabledLintRules` array). When a rule is disabled, its existing `LintResult` rows are deleted and affected video `lintStatus` values are recomputed automatically.
- `lintStatus` on `Video` reflects the most severe open result: `OK` → `WARNING` → `ERROR`.
- See [[03 - Metadata Linting]] for the full list of rule codes and their descriptions.
- See [[09 - Teams API]] for managing disabled lint rules at the team level.