Achievement Badges for Jellyfin

https://github.com/zl154/achievementbadges_for_jellyfin
Admin
Achievement Badges for Jellyfin is a progression and gamification plugin for Jellyfin that rewards...
Tokens:152,699
Snippets:946
Trust Score:7.9
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Create a custom badge to finish a series (POST /Plugins/AchievementBadges/custom-badges)

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

Use this JSON body with the POST /Plugins/AchievementBadges/custom-badges endpoint to create a custom badge that unlocks when a specific series is fully played. The criteria uses the ContainerCompletionPercent metric with a metricParameter formatted as '{guid}|{name}' and a threshold of 100. This example targets the 'One Piece: Alabasta' series with a specific GUID.

```jsonc
// POST /Plugins/AchievementBadges/custom-badges
{
  "name": "Straw Hat",
  "description": "Finish One Piece: Alabasta.",
  "rarity": "Epic",
  "media": "TV",
  "criteria": {
    "metric": "ContainerCompletionPercent",
    "metricParameter": "8f4e2a1b9c3d4e5f6a7b8c9d0e1f2a3b|One Piece: Alabasta",
    "threshold": 100
  }
}
```

--------------------------------

### GET /Plugins/AchievementBadges/admin/challenge-templates

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

GET /Plugins/AchievementBadges/admin/challenge-templates - Admin-only endpoint for one-click templates.

```APIDOC
## [GET] /Plugins/AchievementBadges/admin/challenge-templates

### Description
Admin-only endpoint for one-click templates.

### Method
GET

### Endpoint
/Plugins/AchievementBadges/admin/challenge-templates


```

--------------------------------

### GET /Plugins/AchievementBadges/custom-badges/export

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

Exports all custom badges as JSON.

```APIDOC
## GET /Plugins/AchievementBadges/custom-badges/export

### Description
Exports all custom badges as JSON.

### Method
GET

### Endpoint
`/Plugins/AchievementBadges/custom-badges/export`

### Response
#### Success Response (200)
- **badges** (array) - List of custom badges.

#### Response Example
```json
{
  "badges": []
}
```

```

--------------------------------

### GET /Plugins/AchievementBadges/custom-badges

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

Lists all custom badges.

```APIDOC
## GET /Plugins/AchievementBadges/custom-badges

### Description
List all custom badges.

### Method
GET

### Endpoint
`/Plugins/AchievementBadges/custom-badges`

### Response
#### Success Response (200)
- **badges** (array) - List of custom badges.

#### Response Example
```json
{
  "badges": []
}
```

```

--------------------------------

### GET /Plugins/AchievementBadges/admin/audit-log

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

GET /Plugins/AchievementBadges/admin/audit-log - Admin-only endpoint to get audit log entries.

```APIDOC
## [GET] /Plugins/AchievementBadges/admin/audit-log

### Description
Admin-only endpoint to get audit log entries.

### Method
GET

### Endpoint
/Plugins/AchievementBadges/admin/audit-log

### Parameters
#### Query Parameters
- **limit** - Optional - Limit the number of entries (example: 200)


```

--------------------------------

### GET /Plugins/AchievementBadges/custom-badges/targets

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

Retrieves the targeted badge cap and related information.

```APIDOC
## GET /Plugins/AchievementBadges/custom-badges/targets

### Description
Retrieves the targeted badge cap: configured value, applied cap, bounds, targets observed, and the names past it.

### Method
GET

### Endpoint
`/Plugins/AchievementBadges/custom-badges/targets`

### Response
#### Success Response (200)
- **configuredValue** (integer) - The configured cap value.
- **appliedCap** (integer) - The effective cap after clamping.
- **bounds** (object) - Minimum and maximum allowed values.
- **targetsObserved** (integer) - Number of targets observed.
- **namesPast** (array) - Names of targets past the cap.

#### Response Example
```json
{
  "configuredValue": 100,
  "appliedCap": 100,
  "bounds": { "min": 1, "max": 1000 },
  "targetsObserved": 5,
  "namesPast": []
}
```

```

--------------------------------

### OpenAPI schema collision error log

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

Example server log message when two plugins use the same schemaId for PluginConfiguration, causing the API docs page to return 500. The plugin no longer causes this from v2.4.1+.

```text
Can't use schemaId "$PluginConfiguration" for type "$Jellyfin.Plugin.A.PluginConfiguration".
The same schemaId is already used for type "$Jellyfin.Plugin.B.Configuration.PluginConfiguration"
```

--------------------------------

### GET /Plugins/AchievementBadges/users/{userId}/export

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

GET /Plugins/AchievementBadges/users/{userId}/export - Admin-only endpoint to export achievements for a user.

```APIDOC
## [GET] /Plugins/AchievementBadges/users/{userId}/export

### Description
Admin-only endpoint to export achievements for a user.

### Method
GET

### Endpoint
/Plugins/AchievementBadges/users/{userId}/export

### Parameters
#### Path Parameters
- **userId** - Required - The user identifier


```

--------------------------------

### GET /Plugins/AchievementBadges/custom-badges/{id}

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

Fetch a single custom badge by ID.

```APIDOC
## GET /Plugins/AchievementBadges/custom-badges/{id}

### Description
Fetch a single custom badge by ID.

### Method
GET

### Endpoint
`/Plugins/AchievementBadges/custom-badges/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the badge to fetch.

### Response
#### Success Response (200)
- **badge** (object) - The requested badge.

#### Response Example
```json
{
  "badge": {}
}
```

```

--------------------------------

### NixOS overlay to inject script tags at build time

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

Overrides the jellyfin-web package to inject the three script tags before </body> in dist/index.html. Rebuild your NixOS config after adding the overlay and restart Jellyfin.

```nix
nixpkgs.overlays = [
  (final: prev: {
    jellyfin-web = prev.jellyfin-web.overrideAttrs (finalAttrs: previousAttrs: {
      installPhase = ''
        runHook preInstall
        sed -i 's#</body>#<!-- achievementbadges-bootstrap --><script src="/Plugins/AchievementBadges/client-script/sidebar"></script><script src="/Plugins/AchievementBadges/client-script/standalone" defer></script><script src="/Plugins/AchievementBadges/client-script/enhance" defer></script></body>#' dist/index.html
        mkdir -p $out/share
        cp -a dist $out/share/jellyfin-web
        runHook postInstall
      '';
    });
  })
];
```

--------------------------------

### Verify release artifact with gh and cosign

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/docs/release-notes/v2.0.2.md

Verification commands for the release artifact. Run `gh attestation verify` first, then `cosign verify-blob` with the provided certificate and signature files.

```bash
gh attestation verify Jellyfin.Plugin.AchievementBadges_2.0.2.0.zip --owner ZL154
```

```bash
cosign verify-blob --certificate Jellyfin.Plugin.AchievementBadges_2.0.2.0.zip.pem \
    --signature Jellyfin.Plugin.AchievementBadges_2.0.2.0.zip.sig \
    --certificate-identity-regexp "https://github.com/ZL154/AchievementBadges_for_Jellyfin/.*" \
    --certificate-oidc-issuer https://token.actions.githubusercontent.com \
    Jellyfin.Plugin.AchievementBadges_2.0.2.0.zip
```

--------------------------------

### Verify release with gh attestation verify

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/docs/release-notes/v2.1.0.md

Use this command to verify the release zip's Cosign signature and SLSA provenance attestation. Replace the filename if needed.

```bash
gh attestation verify Jellyfin.Plugin.AchievementBadges_2.1.0.zip --repo ZL154/AchievementBadges_for_Jellyfin
```

--------------------------------

### Fix web directory permissions (Docker and systemd)

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

Grants write access to Jellyfin's web directory so the plugin can patch index.html. Run inside the container for Docker, or fix ownership on systemd. Restart Jellyfin afterward.

```bash
# Docker: run inside the container
chmod -R a+w /usr/share/jellyfin/web/

# Systemd: fix ownership
sudo chown -R jellyfin:jellyfin /usr/share/jellyfin/web/
```

--------------------------------

### POST /Plugins/AchievementBadges/custom-badges/import

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

Bulk imports custom badges.

```APIDOC
## POST /Plugins/AchievementBadges/custom-badges/import

### Description
Bulk imports custom badges. Fresh IDs are assigned.

### Method
POST

### Endpoint
`/Plugins/AchievementBadges/custom-badges/import`

### Parameters
#### Request Body
- **badges** (array) - Required - List of badges to import.

### Request Example
```jsonc
{
  "badges": [
    {
      "name": "Cinephile",
      "description": "Watch 100 films.",
      "rarity": "Rare",
      "media": "Film",
      "enabled": true,
      "criteria": { "metric": "MoviesWatched", "threshold": 100 }
    }
  ]
}
```

### Response
#### Success Response (201)
- **imported** (integer) - Number of badges imported.

#### Response Example
```json
{
  "imported": 1
}
```

```

--------------------------------

### POST /Plugins/AchievementBadges/users/{userId}/library-completion/recompute

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

POST /Plugins/AchievementBadges/users/{userId}/library-completion/recompute - Admin-only endpoint to recompute library completion for a user.

```APIDOC
## [POST] /Plugins/AchievementBadges/users/{userId}/library-completion/recompute

### Description
Admin-only endpoint to recompute library completion for a user.

### Method
POST

### Endpoint
/Plugins/AchievementBadges/users/{userId}/library-completion/recompute

### Parameters
#### Path Parameters
- **userId** - Required - The user identifier


```

--------------------------------

### POST /Plugins/AchievementBadges/backfill-all

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

POST /Plugins/AchievementBadges/backfill-all - Admin-only endpoint to trigger backfill for all users.

```APIDOC
## [POST] /Plugins/AchievementBadges/backfill-all

### Description
Admin-only endpoint to trigger backfill for all users.

### Method
POST

### Endpoint
/Plugins/AchievementBadges/backfill-all


```

--------------------------------

### GET/POST /Plugins/AchievementBadges/admin/feature-config

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

GET/POST /Plugins/AchievementBadges/admin/feature-config - Admin-only endpoint for feature kill switches + admin controls.

```APIDOC
## [GET/POST] /Plugins/AchievementBadges/admin/feature-config

### Description
Admin-only endpoint for feature kill switches + admin controls.

### Method
GET/POST

### Endpoint
/Plugins/AchievementBadges/admin/feature-config


```

--------------------------------

### Simple custom badge template (POST /custom-badges)

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

JSONC body for creating a simple badge with a single criterion. The rarity field accepts Common, Uncommon, Rare, Epic, Legendary, or Mythic; media accepts Film, TV, Music, Book, Anime, or Multi. iconUrl is optional and defaults to a blank trophy when empty.

```jsonc
// POST /Plugins/AchievementBadges/custom-badges
{
  "name": "Cinephile",
  "description": "Watch 100 films.",
  "rarity": "Rare",            // Common | Uncommon | Rare | Epic | Legendary | Mythic
  "media": "Film",             // Film | TV | Music | Book | Anime | Multi
  "iconUrl": "",               // optional external https URL; blank = default trophy
  "enabled": true,
  "criteria": { "metric": "MoviesWatched", "threshold": 100 }
}
```

--------------------------------

### POST /Plugins/AchievementBadges/users/{userId}/import

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

POST /Plugins/AchievementBadges/users/{userId}/import - Admin-only endpoint to import achievements for a user.

```APIDOC
## [POST] /Plugins/AchievementBadges/users/{userId}/import

### Description
Admin-only endpoint to import achievements for a user.

### Method
POST

### Endpoint
/Plugins/AchievementBadges/users/{userId}/import

### Parameters
#### Path Parameters
- **userId** - Required - The user identifier


```

--------------------------------

### POST /Plugins/AchievementBadges/admin/users/{userId}/test/inject-playbacks

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

POST /Plugins/AchievementBadges/admin/users/{userId}/test/inject-playbacks - Admin-only endpoint to verify integrity caps end-to-end (v1.9.8).

```APIDOC
## [POST] /Plugins/AchievementBadges/admin/users/{userId}/test/inject-playbacks

### Description
Admin-only endpoint to verify integrity caps end-to-end (v1.9.8).

### Method
POST

### Endpoint
/Plugins/AchievementBadges/admin/users/{userId}/test/inject-playbacks

### Parameters
#### Path Parameters
- **userId** - Required - The user identifier


```

--------------------------------

### POST /Plugins/AchievementBadges/admin/users/{userId}/grant-cosmetic

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

POST /Plugins/AchievementBadges/admin/users/{userId}/grant-cosmetic - Admin-only endpoint for v2.0 testing.

```APIDOC
## [POST] /Plugins/AchievementBadges/admin/users/{userId}/grant-cosmetic

### Description
Admin-only endpoint for v2.0 testing.

### Method
POST

### Endpoint
/Plugins/AchievementBadges/admin/users/{userId}/grant-cosmetic

### Parameters
#### Path Parameters
- **userId** - Required - The user identifier


```

--------------------------------

### GET/POST /Plugins/AchievementBadges/admin/ui-features

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

GET/POST /Plugins/AchievementBadges/admin/ui-features - Admin-only endpoint for UI feature toggles.

```APIDOC
## [GET/POST] /Plugins/AchievementBadges/admin/ui-features

### Description
Admin-only endpoint for UI feature toggles.

### Method
GET/POST

### Endpoint
/Plugins/AchievementBadges/admin/ui-features


```

--------------------------------

### GET/POST /Plugins/AchievementBadges/admin/badge-catalog

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

GET/POST /Plugins/AchievementBadges/admin/badge-catalog - Admin-only endpoint to enable/disable badges.

```APIDOC
## [GET/POST] /Plugins/AchievementBadges/admin/badge-catalog

### Description
Admin-only endpoint to enable/disable badges.

### Method
GET/POST

### Endpoint
/Plugins/AchievementBadges/admin/badge-catalog


```

--------------------------------

### POST /Plugins/AchievementBadges/admin/users/{userId}/grant-powerup/{type}

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

POST /Plugins/AchievementBadges/admin/users/{userId}/grant-powerup/{type} - Admin-only endpoint for v2.0 testing.

```APIDOC
## [POST] /Plugins/AchievementBadges/admin/users/{userId}/grant-powerup/{type}

### Description
Admin-only endpoint for v2.0 testing.

### Method
POST

### Endpoint
/Plugins/AchievementBadges/admin/users/{userId}/grant-powerup/{type}

### Parameters
#### Path Parameters
- **userId** - Required - The user identifier
- **type** - Required - The type of power-up


```

--------------------------------

### POST /Plugins/AchievementBadges/custom-badges/targets

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

Sets the targeted badge cap.

```APIDOC
## POST /Plugins/AchievementBadges/custom-badges/targets

### Description
Sets the cap for targeted badges. Value is clamped between 1 and 1000. Returns a fresh summary.

### Method
POST

### Endpoint
`/Plugins/AchievementBadges/custom-badges/targets`

### Parameters
#### Request Body
- **value** (integer) - Required - The cap value (1-1000). Will be clamped.

### Request Example
```jsonc
{
  "value": 100
}
```

### Response
#### Success Response (200)
- **configuredValue** (integer) - The configured cap value.
- **appliedCap** (integer) - The effective cap after clamping.
- **bounds** (object) - Minimum and maximum allowed values.
- **targetsObserved** (integer) - Number of targets observed.
- **namesPast** (array) - Names of targets past the cap.

#### Response Example
```json
{
  "configuredValue": 100,
  "appliedCap": 100,
  "bounds": { "min": 1, "max": 1000 },
  "targetsObserved": 5,
  "namesPast": []
}
```

```

--------------------------------

### Nested compound badge template (AND/OR with metricParameter)

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

JSONC body for a badge with nested criteria: an outer And combining an Or group (finish 5 horror series OR 10h audiobooks) with a single criterion (watch 25 anime items). Demonstrates metricParameter usage for genre-specific metrics.

```jsonc
{
  "name": "Eclectic",
  "description": "Genre-spanning dedication.",
  "rarity": "Legendary",
  "media": "Multi",
  "enabled": true,
  "criteria": {
    "operator": "And",
    "children": [
      {
        "operator": "Or",
        "children": [
          { "metric": "SeriesCompleted",         "threshold": 5,  "metricParameter": "Horror" },
          { "metric": "AudiobookListeningHours",  "threshold": 10 }
        ]
      },
      { "metric": "AnimeItemsWatched", "threshold": 25 }
    ]
  }
}
```

--------------------------------

### POST /Plugins/AchievementBadges/admin/users/{userId}/inject-counters

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

POST /Plugins/AchievementBadges/admin/users/{userId}/inject-counters - Admin-only endpoint to inject counters for a user.

```APIDOC
## [POST] /Plugins/AchievementBadges/admin/users/{userId}/inject-counters

### Description
Admin-only endpoint to inject counters for a user.

### Method
POST

### Endpoint
/Plugins/AchievementBadges/admin/users/{userId}/inject-counters

### Parameters
#### Path Parameters
- **userId** - Required - The user identifier


```

--------------------------------

### GET/POST /Plugins/AchievementBadges/admin/challenges

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

GET/POST /Plugins/AchievementBadges/admin/challenges - Admin-only endpoint for seasonal challenges.

```APIDOC
## [GET/POST] /Plugins/AchievementBadges/admin/challenges

### Description
Admin-only endpoint for seasonal challenges.

### Method
GET/POST

### Endpoint
/Plugins/AchievementBadges/admin/challenges


```

--------------------------------

### POST /Plugins/AchievementBadges/custom-badges

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

Creates a new custom badge. The request body contains the badge definition, including name, description, rarity, media, and a criteria tree. Compound criteria use And/Or operators with children, while leaf criteria use metric, metricParameter, and threshold.

```APIDOC
## [POST] /Plugins/AchievementBadges/custom-badges

### Description
Create a new custom badge with compound AND/OR criteria. Admin-only. All endpoints require admin elevation.

### Method
POST

### Endpoint
/Plugins/AchievementBadges/custom-badges

### Parameters
#### Request Body
- **name** (string) - Required - The badge's display name.
- **description** (string) - Optional - A description of the badge.
- **rarity** (string) - Required - The rarity level of the badge (e.g., "Epic").
- **media** (string) - Required - The media type the badge applies to (e.g., "TV").
- **criteria** (object) - Required - The criteria tree. Must be a leaf or compound node.
  - **metric** (string) - Required for leaf - The metric to evaluate (e.g., "ContainerCompletionPercent", "ItemPlayCount", "GamePlatformGames", "GameStudioGames", "GameHours").
  - **metricParameter** (string) - Optional for leaf - The parameter for the metric, e.g., "{guid}|{name}" for targeted badges or a platform tag for GamePlatformGames.
  - **threshold** (integer) - Required for leaf - The threshold value; the leaf is true when metric value ≥ threshold.
  - **operator** (string) - Required for compound - "And" or "Or".
  - **children** (array) - Required for compound - A list of child nodes (each a leaf or compound).

### Request Example
{
  "name": "Straw Hat",
  "description": "Finish One Piece: Alabasta.",
  "rarity": "Epic",
  "media": "TV",
  "criteria": {
    "metric": "ContainerCompletionPercent",
    "metricParameter": "8f4e2a1b9c3d4e5f6a7b8c9d0e1f2a3b|One Piece: Alabasta",
    "threshold": 100
  }
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created badge.

#### Response Example
{
  "id": "3f9c2b8a-1e4d-4f6a-9a7b-2c3d4e5f6a7b"
}

```

--------------------------------

### POST /Plugins/AchievementBadges/admin/backfill-milestones

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

POST /Plugins/AchievementBadges/admin/backfill-milestones - Admin-only endpoint for v2.0: retroactively unlock title milestones across all profiles.

```APIDOC
## [POST] /Plugins/AchievementBadges/admin/backfill-milestones

### Description
Admin-only endpoint for v2.0: retroactively unlock title milestones across all profiles.

### Method
POST

### Endpoint
/Plugins/AchievementBadges/admin/backfill-milestones


```

--------------------------------

### GET/POST /Plugins/AchievementBadges/admin/webhook

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

GET/POST /Plugins/AchievementBadges/admin/webhook - Admin-only endpoint for webhook config (incl. HMAC secret).

```APIDOC
## [GET/POST] /Plugins/AchievementBadges/admin/webhook

### Description
Admin-only endpoint for webhook config (incl. HMAC secret).

### Method
GET/POST

### Endpoint
/Plugins/AchievementBadges/admin/webhook


```

--------------------------------

### POST /Plugins/AchievementBadges/users/{userId}/backfill

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

POST /Plugins/AchievementBadges/users/{userId}/backfill - Admin-only endpoint to trigger backfill for a specific user (requires elevation).

```APIDOC
## [POST] /Plugins/AchievementBadges/users/{userId}/backfill

### Description
backfill operations require special admin rights.

### Method
POST

### Endpoint
/Plugins/AchievementBadges/users/{userId}/backfill

### Parameters
#### Path Parameters
- **userId** - Required - The user identifier


```

--------------------------------

### POST /Plugins/AchievementBadges/custom-badges

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

Creates a new custom badge. A fresh ID is assigned.

```APIDOC
## POST /Plugins/AchievementBadges/custom-badges

### Description
Creates a new custom badge. A fresh ID is assigned.

### Method
POST

### Endpoint
`/Plugins/AchievementBadges/custom-badges`

### Parameters
#### Request Body
- **name** (string) - Required - Name of the badge.
- **description** (string) - Optional - Description of the badge.
- **rarity** (string) - Required - Value from: Common, Uncommon, Rare, Epic, Legendary, Mythic.
- **media** (string) - Required - Value from: Film, TV, Music, Book, Anime, Multi.
- **iconUrl** (string) - Optional - External HTTPS URL for the icon; blank uses default trophy.
- **enabled** (boolean) - Required - Whether the badge is enabled.
- **criteria** (object) - Required - Criteria object with `metric` and `threshold` (or `operator` and `children`).

### Request Example
```jsonc
{
  "name": "Cinephile",
  "description": "Watch 100 films.",
  "rarity": "Rare",
  "media": "Film",
  "iconUrl": "",
  "enabled": true,
  "criteria": { "metric": "MoviesWatched", "threshold": 100 }
}
```

### Response
#### Success Response (201)
- **id** (string) - The assigned ID.

#### Response Example
```json
{
  "id": "new-id"
}
```

```

--------------------------------

### GET/POST /Plugins/AchievementBadges/admin/custom-badges

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

GET/POST /Plugins/AchievementBadges/admin/custom-badges - Admin-only endpoint for custom badge definitions.

```APIDOC
## [GET/POST] /Plugins/AchievementBadges/admin/custom-badges

### Description
Admin-only endpoint for custom badge definitions.

### Method
GET/POST

### Endpoint
/Plugins/AchievementBadges/admin/custom-badges


```

--------------------------------

### Synchronous DNS resolution in WebhookUrlValidator.cs

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/SECURITY_REVIEW.md

Synchronous DNS resolution on the request thread. Called from POST /admin/webhook and WebhookNotifier.NotifyUnlock. A slow DNS server can stall the ASP.NET request thread for the default DNS timeout. Fix: use Dns.GetHostAddressesAsync and make the validator async, or enforce a short timeout.

```csharp
addresses = Dns.GetHostAddresses(uri.Host);
```

--------------------------------

### JavaScript Injector script URLs

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

Three script URLs to paste into the JavaScript Injector plugin settings (one per entry) when the web directory isn't writable. The plugin writes these into diagnostics and the server log.

```text
/Plugins/AchievementBadges/client-script/sidebar
/Plugins/AchievementBadges/client-script/standalone
/Plugins/AchievementBadges/client-script/enhance
```

--------------------------------

### POST /Plugins/AchievementBadges/admin/users/{userId}/grant-score

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

POST /Plugins/AchievementBadges/admin/users/{userId}/grant-score - Admin-only endpoint for v2.0 testing.

```APIDOC
## [POST] /Plugins/AchievementBadges/admin/users/{userId}/grant-score

### Description
Admin-only endpoint for v2.0 testing.

### Method
POST

### Endpoint
/Plugins/AchievementBadges/admin/users/{userId}/grant-score

### Parameters
#### Path Parameters
- **userId** - Required - The user identifier


```

--------------------------------

### PUT /Plugins/AchievementBadges/custom-badges/{id}

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

Updates an existing custom badge.

```APIDOC
## PUT /Plugins/AchievementBadges/custom-badges/{id}

### Description
Updates an existing custom badge identified by ID.

### Method
PUT

### Endpoint
`/Plugins/AchievementBadges/custom-badges/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the badge to update.

#### Request Body
- **name** (string) - Required - Name of the badge.
- **description** (string) - Optional - Description of the badge.
- **rarity** (string) - Required - Value from: Common, Uncommon, Rare, Epic, Legendary, Mythic.
- **media** (string) - Required - Value from: Film, TV, Music, Book, Anime, Multi.
- **iconUrl** (string) - Optional - External HTTPS URL for the icon; blank uses default trophy.
- **enabled** (boolean) - Required - Whether the badge is enabled.
- **criteria** (object) - Required - Criteria object with `metric` and `threshold` (or `operator` and `children`).

### Request Example
```jsonc
{
  "name": "Cinephile",
  "description": "Watch 100 films.",
  "rarity": "Rare",
  "media": "Film",
  "iconUrl": "",
  "enabled": true,
  "criteria": { "metric": "MoviesWatched", "threshold": 100 }
}
```

### Response
#### Success Response (204)
No content.

```

--------------------------------

### StandalonePage endpoint URL format

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/docs/release-notes/v2.0.2.md

URL format for the anonymous standalone page endpoint. The token and user id are passed as query parameters; the token is the security gate.

```text
https://YOUR-HOST/Plugins/AchievementBadges/StandalonePage?token=<accessToken>&userId=<userGuid>
```

--------------------------------

### Compound AND/OR badge template

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

JSONC body for a badge with multiple criteria combined using an operator (And or Or) and a children array. Each child is a criterion object with metric and threshold.

```jsonc
{
  "name": "Renaissance Viewer",
  "description": "Watch 100 films AND listen to 50 music tracks.",
  "rarity": "Epic",
  "media": "Multi",
  "enabled": true,
  "criteria": {
    "operator": "And",
    "children": [
      { "metric": "MoviesWatched",   "threshold": 100 },
      { "metric": "MusicPlaysTotal", "threshold": 50 }
    ]
  }
}
```

--------------------------------

### POST /Plugins/AchievementBadges/users/{userId}/reset

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

POST /Plugins/AchievementBadges/users/{userId}/reset - Admin-only endpoint to reset a user's achievement progress.

```APIDOC
## [POST] /Plugins/AchievementBadges/users/{userId}/reset

### Description
Admin-only endpoint to reset a user's achievement progress.

### Method
POST

### Endpoint
/Plugins/AchievementBadges/users/{userId}/reset

### Parameters
#### Path Parameters
- **userId** - Required - The user identifier


```

--------------------------------

### POST /Plugins/AchievementBadges/users/{userId}/reset-badge/{badgeId}

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

POST /Plugins/AchievementBadges/users/{userId}/reset-badge/{badgeId} - Admin-only endpoint to reset a specific badge for a user.

```APIDOC
## [POST] /Plugins/AchievementBadges/users/{userId}/reset-badge/{badgeId}

### Description
Admin-only endpoint to reset a specific badge for a user.

### Method
POST

### Endpoint
/Plugins/AchievementBadges/users/{userId}/reset-badge/{badgeId}

### Parameters
#### Path Parameters
- **userId** - Required - The user identifier
- **badgeId** - Required - The badge identifier


```

--------------------------------

### Audit Log Entry Format

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/SECURITY.md

JSON structure of an audit log entry written by Api/AdminAuditLogFilter. Includes timestamp, user ID, username (or redacted), event type, and details of the admin action. Capped at 5000 entries with FIFO eviction.

```json
{
  "At": "2026-05-03T15:30:00Z",
  "UserId": "<guid>",
  "UserName": "<name or [redacted]>",
  "Type": "admin.action",
  "Details": "POST /Plugins/AchievementBadges/users/<guid>/unlock/binge_god -> 200"
}
```

--------------------------------

### DELETE /Plugins/AchievementBadges/admin/users/{userId}/reset

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

DELETE /Plugins/AchievementBadges/admin/users/{userId}/reset - Admin-only endpoint to wipe user's achievement progress.

```APIDOC
## [DELETE] /Plugins/AchievementBadges/admin/users/{userId}/reset

### Description
Admin-only endpoint to wipe user's achievement progress.

### Method
DELETE

### Endpoint
/Plugins/AchievementBadges/admin/users/{userId}/reset

### Parameters
#### Path Parameters
- **userId** - Required - The user identifier


```

--------------------------------

### DELETE /Plugins/AchievementBadges/admin/users/{userId}/badges/{badgeId}

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

DELETE /Plugins/AchievementBadges/admin/users/{userId}/badges/{badgeId} - Admin-only endpoint for manual badge revoke (v1.9.8).

```APIDOC
## [DELETE] /Plugins/AchievementBadges/admin/users/{userId}/badges/{badgeId}

### Description
Admin-only endpoint for manual badge revoke (v1.9.8).

### Method
DELETE

### Endpoint
/Plugins/AchievementBadges/admin/users/{userId}/badges/{badgeId}

### Parameters
#### Path Parameters
- **userId** - Required - The user identifier
- **badgeId** - Required - The badge identifier


```

--------------------------------

### DELETE /Plugins/AchievementBadges/custom-badges/{id}

Source: https://github.com/zl154/achievementbadges_for_jellyfin/blob/main/README.md

Deletes a custom badge by ID.

```APIDOC
## DELETE /Plugins/AchievementBadges/custom-badges/{id}

### Description
Deletes a custom badge by ID.

### Method
DELETE

### Endpoint
`/Plugins/AchievementBadges/custom-badges/{id}`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the badge to delete.

### Response
#### Success Response (204)
No content.

```
Tokens:
Raw