### Start Plex PIN Flow

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Starts the Plex PIN flow used for browser/device login.

```APIDOC
## POST /v1/api/backends/plex/generate

### Description
Starts the Plex PIN flow used for browser/device login.

### Method
POST

### Endpoint
/v1/api/backends/plex/generate

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the PIN flow.
- **code** (string) - The PIN code to be displayed to the user.
- **...** (any) - Plex PIN payload

#### Response Example
```json
{
  "id": 123456,
  "code": "ABCD",
  "...": "Plex PIN payload"
}
```

### Errors
- Returns the upstream Plex status when the PIN request fails.

### Notes
- The response also includes the WatchState Plex client headers used for the request.
```

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

### Get, Set, or Delete Backend Option (GET/POST/PATCH/DELETE)

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Manage backend options using GET for reading, POST/PATCH for setting, and DELETE for removal. Options starting with 'options.' are accessible externally.

```json
{
  "key": "options.client.timeout",
  "value": 30,
  "real_val": "30",
  "type": "float",
  "description": "HTTP timeout in seconds"
}
```

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

### Docker CLI Installation

Source: https://context7.com/arabcoders/watchstate/llms.txt

Installs WatchState using the Docker CLI. The container runs in detached mode and restarts automatically unless stopped.

```bash
mkdir -p ./data && docker run -itd --name watchstate \
  --user "${UID:-1000}:${GID:-${UID:-1000}}" \
  --restart unless-stopped \
  -p 8080:8080 \
  -v ./data:/config:rw \
  ghcr.io/arabcoders/watchstate:latest

```

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

### GET /v1/api/system/guids/custom

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves custom system GUIDs.

```APIDOC
## GET /v1/api/system/guids/custom

### Description
Retrieves custom system GUIDs.

### Method
GET

### Endpoint
/v1/api/system/guids/custom
```

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

### Docker Compose Installation

Source: https://context7.com/arabcoders/watchstate/llms.txt

Installs WatchState using Docker Compose. Ensure the 'user' directive matches the owner of the data directory. The WebUI is available at http://localhost:8080.

```yaml
# compose.yaml
services:
  watchstate:
    image: ghcr.io/arabcoders/watchstate:latest
    user: "${UID:-1000}:${UID:-1000}"
    container_name: watchstate
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./data:/config:rw

```

```bash
mkdir -p ./data && docker compose up -d
# WebUI available at http://localhost:8080
# First visit prompts for admin account creation

```

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

### GET /v1/api/system/static/{file}

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves a static file from the system.

```APIDOC
## GET /v1/api/system/static/{file}

### Description
Retrieves a static file from the system.

### Method
GET

### Endpoint
/v1/api/system/static/{file}

### Parameters
#### Path Parameters
- **file** (string) - Required - The name of the static file.
```

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

### GET /v1/api/system/processes

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves system processes.

```APIDOC
## GET /v1/api/system/processes

### Description
Retrieves system processes.

### Method
GET

### Endpoint
/v1/api/system/processes
```

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

### GET /v1/api/backends

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves a list of all configured backends.

```APIDOC
## GET /v1/api/backends

### Description
Retrieves a list of all configured backends.

### Method
GET

### Endpoint
/v1/api/backends
```

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

### GET /v1/api/system/env

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves all system environment variables.

```APIDOC
## GET /v1/api/system/env

### Description
Retrieves all system environment variables.

### Method
GET

### Endpoint
/v1/api/system/env
```

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

### GET /v1/api/system/backup

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves system backups.

```APIDOC
## GET /v1/api/system/backup

### Description
Retrieves system backups.

### Method
GET

### Endpoint
/v1/api/system/backup
```

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

### GET /v1/api/system/version

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves the current version of the system.

```APIDOC
## GET /v1/api/system/version

### Description
Retrieves the current version of the system.

### Method
GET

### Endpoint
/v1/api/system/version
```

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

### PUT /v1/api/system/guids/custom

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Updates custom system GUIDs.

```APIDOC
## PUT /v1/api/system/guids/custom

### Description
Updates custom system GUIDs.

### Method
PUT

### Endpoint
/v1/api/system/guids/custom
```

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

### GET /v1/api/system/report/ini

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Returns `ini_get_all()` for development builds.

```APIDOC
## GET /v1/api/system/report/ini

### Description
Returns `ini_get_all()` for development builds.

### Method
GET

### Endpoint
/v1/api/system/report/ini

### Response (Success)
```json
{
  "content": {
    "memory_limit": {
      "local_value": "512M",
      "global_value": "512M"
    }
  }
}
```

### Errors
- `403 Forbidden`: Outside development builds.
```

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

### GET /v1/api/system/guids

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves system GUIDs.

```APIDOC
## GET /v1/api/system/guids

### Description
Retrieves system GUIDs.

### Method
GET

### Endpoint
/v1/api/system/guids
```

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

### Example Output for Database Repair

Source: https://github.com/arabcoders/watchstate/blob/master/FAQ.md

This output shows the successful steps taken by the db:repair command, including creating a backup, repairing the database, and verifying its integrity.

```log
INFO: Attempting to repair database '{db_name}'.
INFO: Copied database '{db_name}' to '{db_name}.before.repair.db' as backup.
INFO: Attempting to repair database '{db_name}'.
INFO: Database '{db_name}' repaired successfully.
INFO: Checking database integrity...
INFO: SQLite3: ok
INFO: Database '{db_name}' is valid.
INFO: Updating database version to 1723988129.
INFO: Renaming database '{db_name}.new.db' to '{db_name}'.
INFO: Repair completed successfully. Database '{db_name}' is now valid.
```

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

### List Configured Backends

Source: https://context7.com/arabcoders/watchstate/llms.txt

Retrieves a list of all configured media server backends. Requires API key authentication. The response includes details like backend name, type, URL, and sync status.

```bash
curl -s -H "X-APIKEY: <key>" http://localhost:8080/v1/api/backends
# Response:
# [
#   {
#     "name": "plex_main",
#     "type": "plex",
#     "url": "https://plex.example.com",
#     "uuid": "abc123",
#     "user": "owner",
#     "import": { "enabled": true, "lastSync": "2026-04-01T12:00:00+00:00" },
#     "export": { "enabled": true, "lastSync": "2026-04-01T12:01:00+00:00" },
#     "urls": { "webhook": "/v1/api/webhook?apikey=..." }
#   }
# ]

```

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

### Get Custom GUID Raw Value

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves the raw nested value stored at a specific path within the custom GUID document for a given client.

```APIDOC
## GET /v1/api/system/guids/custom/{client}/{index}

### Description
Returns the raw nested value stored at `{client}.{index}` in the custom GUID document.

### Method
GET

### Endpoint
/v1/api/system/guids/custom/{client}/{index}

### Parameters
#### Path Parameters
- **client** (string) - Required - Backend type.
- **index** (integer) - Required - Numeric index within the custom GUID document.

### Errors
- `404 Not Found` if the client or requested index does not exist.

### Notes
- The current implementation looks up a nested path inside the custom GUID document, not an item from the `links` array shown by `GET /v1/api/system/guids/custom/{client}`.
- In a typical custom GUID file this means the route often returns `404 Not Found` unless the document contains a matching top-level `{client}` object with a numeric child key.
```

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

### Add Plex Backend

Source: https://context7.com/arabcoders/watchstate/llms.txt

Use this endpoint to add a new Plex backend. Ensure you have obtained a Plex token via the PIN flow first.

```bash
curl -s -X POST http://localhost:8080/v1/api/backends \
  -H "X-APIKEY: <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "plex_main",
    "type": "plex",
    "url": "https://plex.example.com",
    "token": "X-Plex-Token-Here",
    "user": "owner",
    "import": { "enabled": true },
    "export": { "enabled": false }
  }'
```

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

### GET /v1/api/system/guids/custom/{client}

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves custom system GUIDs for a specific client.

```APIDOC
## GET /v1/api/system/guids/custom/{client}

### Description
Retrieves custom system GUIDs for a specific client.

### Method
GET

### Endpoint
/v1/api/system/guids/custom/{client}

### Parameters
#### Path Parameters
- **client** (string) - Required - The client identifier.
```

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

### Serve Static Files

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Serves exported UI assets and allowlisted documentation files.

```APIDOC
## GET /v1/api/system/static/{file}

### Description
Serves exported UI assets and allowlisted documentation files.

### Method
GET

### Endpoint
/v1/api/system/static/{file}

### Parameters
#### Path Parameters
- **file** (string) - Required - Path relative to the static file root.

### Response
- File stream with `Content-Type`, `Content-Length`, and `Last-Modified` headers.

### Errors
- `400 Bad Request` if the path is invalid.
- `404 Not Found` if the file does not exist.

### Access
- Open.
```

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

### GET /v1/api/system/supported

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves information about supported features or components.

```APIDOC
## GET /v1/api/system/supported

### Description
Retrieves information about supported features or components.

### Method
GET

### Endpoint
/v1/api/system/supported
```

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

### Sign Up Admin Account

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Creates the initial WatchState admin account with a specified username and password.

```APIDOC
## POST /v1/api/system/auth/signup

### Description
Creates the initial WatchState admin account.

### Method
POST

### Endpoint
/v1/api/system/auth/signup

### Request Body
```json
{
  "username": "admin",
  "password": "secret"
}
```

### Response
#### Success Response (201)
- `201 Created` with an empty body.

#### Errors
- **400 Bad Request**: if `username` or `password` is missing.
- **403 Forbidden**: if the system account is already configured.
```

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

### GET /v1/api/system/suppressor

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Lists all configured log suppressor rules, including their types and examples.

```APIDOC
## GET /v1/api/system/suppressor

### Description
Lists log suppressor rules.

### Method
GET

### Endpoint
/v1/api/system/suppressor

### Response
#### Success Response (200)
- **items** (array) - List of suppressor rules.
  - **id** (string) - The unique ID of the suppressor rule.
  - **type** (string) - The type of rule (e.g., 'contains', 'regex').
  - **rule** (string) - The actual suppression rule pattern.
  - **example** (string) - An example log line that matches the rule.
- **types** (array) - Available types for log suppressor rules.
```

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

### Add Custom GUID Definition API

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Adds a new custom GUID definition. The `name` will be prefixed with `guid_` if it doesn't start with it. The `type` must be a supported backend client name.

```json
{
  "name": "letterboxd",
  "type": "plex",
  "description": "Letterboxd movie GUID",
  "validator": {
    "pattern": "/^[a-z0-9-]+$/",
    "example": "movie-name",
    "tests": {
      "valid": ["movie-name"],
      "invalid": ["movie name"]
    }
  }
}
```

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

### Add New Backend

Source: https://context7.com/arabcoders/watchstate/llms.txt

Adds a new media server backend configuration to WatchState. Requires API key authentication and a JSON payload with backend details. For Jellyfin, 'username:password' is used as the token for initial authentication.

```bash
# Add a Jellyfin backend (use "username:password" as token for first-time auth)
curl -s -X POST http://localhost:8080/v1/api/backends \
  -H "X-APIKEY: <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "jellyfin_main",
    "type": "jellyfin",
    "url": "https://jellyfin.example.com",
    "token": "alice:mysecret",
    "import": { "enabled": true },
    "export": { "enabled": true }
  }'
# WatchState generates an OAuth token automatically and stores it.
# Response: { "name": "jellyfin_main", "type": "jellyfin", ... }

```

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

### List Configured Backends

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves a list of all configured backends for the current user. Supports identity context via `X-User` header or `?user=` query parameter.

```APIDOC
## GET /v1/api/backends

### Description
Lists configured backends for the current user.

### Method
GET

### Endpoint
/v1/api/backends

### Parameters
#### Query Parameters
- **user** (string) - Optional - Specifies the identity context.

#### Headers
- **X-User** (string) - Optional - Specifies the identity context.

### Response
#### Success Response (200)
- **name** (string) - The name of the backend.
- **type** (string) - The type of the backend (e.g., plex, jellyfin).
- **url** (string) - The URL of the backend.
- **uuid** (string) - The unique identifier of the backend.
- **user** (string) - The user associated with the backend.
- **import** (object) - Import configuration details.
  - **enabled** (boolean) - Whether import is enabled.
  - **lastSync** (string) - The timestamp of the last sync.
- **export** (object) - Export configuration details.
  - **enabled** (boolean) - Whether export is enabled.
  - **lastSync** (string) - The timestamp of the last sync.
- **urls** (object) - URLs related to the backend.
  - **webhook** (string) - The webhook URL.

### Response Example
```json
[
  {
    "name": "plex_main",
    "type": "plex",
    "url": "https://plex.example.com",
    "uuid": "...",
    "user": "owner",
    "import": {
      "enabled": true,
      "lastSync": "2026-03-28T12:00:00+00:00"
    },
    "export": {
      "enabled": false,
      "lastSync": null
    },
    "urls": {
      "webhook": "/v1/api/webhook?apikey=..."
    }
  }
]
```

### Notes
- External responses omit the stored `options` object except for `options.IMPORT_METADATA_ONLY`.
- The generated webhook URL includes `?apikey=...` when secure API mode is enabled.
```

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

### GET /v1/api/system/guids/custom/{client}/{index}

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves a custom system GUID for a specific client and index.

```APIDOC
## GET /v1/api/system/guids/custom/{client}/{index}

### Description
Retrieves a custom system GUID for a specific client and index.

### Method
GET

### Endpoint
/v1/api/system/guids/custom/{client}/{index}

### Parameters
#### Path Parameters
- **client** (string) - Required - The client identifier.
- **index** (string) - Required - The index of the custom GUID.
```

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

### GET /v1/api/backend/{name}/unmatched[/{id}]

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Scans one library, or all supported non-ignored libraries, for items without supported GUIDs. Supports optional timeout and raw payload inclusion.

```APIDOC
## GET /v1/api/backend/{name}/unmatched[/{id}]

### Description
Scans one library, or all supported non-ignored libraries, for items without supported GUIDs.

### Method
GET

### Endpoint
/v1/api/backend/{name}/unmatched[/{id}]

### Parameters
#### Path Parameters
- **name** (string) - Required - Saved backend name.
- **id** (string) - Optional - Library ID. If omitted, WatchState scans every supported non-ignored library.

#### Query Parameters
- **timeout** (integer) - Optional - Override backend timeout.
- **raw** (boolean) - Optional - Include raw backend payloads.

### Response
#### Success Response (200)
- **title** (string) - The title of the unmatched item.
- **type** (string) - The type of the item.
- **webUrl** (string) - The web URL for the item.
- **library** (string) - The ID of the library the item belongs to.
- **path** (string) - The file path of the item.

#### Response Example
```json
[
  {
    "title": "Unknown Item",
    "type": "movie",
    "webUrl": "...",
    "library": "1",
    "path": "/media/movies/Unknown Item.mkv"
  }
]
```

### Errors
- 404 Not Found: If the user or backend does not exist.
- 500 Internal Server Error: If the scan fails.
```

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

### Create Initial Admin Account

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Use this endpoint to set up the primary WatchState administrator account. Requires username and password in the request body.

```json
{
  "username": "admin",
  "password": "secret"
}
```

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

### Scan for Unmatched Library Items (GET)

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Scan a specific library or all supported non-ignored libraries for items lacking supported GUIDs. The 'raw' parameter includes raw backend payloads.

```json
[
  {
    "title": "Unknown Item",
    "type": "movie",
    "webUrl": "...",
    "library": "1",
    "path": "/media/movies/Unknown Item.mkv"
  }
]
```

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

### POST /v1/api/system/auth/signup

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Registers a new user.

```APIDOC
## POST /v1/api/system/auth/signup

### Description
Registers a new user.

### Method
POST

### Endpoint
/v1/api/system/auth/signup
```

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

### GET /v1/api/backend/{name}

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves the configuration for a specific backend by name.

```APIDOC
## GET /v1/api/backend/{name}

### Description
Retrieves the configuration for a specific backend by name.

### Method
GET

### Endpoint
/v1/api/backend/{name}

#### Path Parameters
- **name** (string) - Required - The name of the backend.
```

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

### List GUID Types API

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Lists supported GUID types and their associated validators. The response is an array of GUID definitions.

```json
[
  {
    "guid": "imdb",
    "type": "movie",
    "validator": {
      "pattern": "..."
    }
  }
]
```

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

### Checkout Development Branch

Source: https://github.com/arabcoders/watchstate/blob/master/CONTRIBUTING.md

Before starting development, branch from the 'dev' branch and pull the latest changes.

```bash
git checkout dev
git pull origin dev
git checkout -b feature/descriptive-name
```

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

### Import Task Log Example

Source: https://github.com/arabcoders/watchstate/blob/master/guides/using-ws-as-backup-solution.md

This log message indicates the completion of the playstate import task for all users.

```log
[DD/MM HH:MM:SS]: SYSTEM: Import process completed in 'XXX's for all users.
```

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

### Read Custom GUID Configuration API

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Reads the custom GUID configuration file. This endpoint returns the current configuration for custom GUIDs.

```json
{
  "version": "0.0",
  "guids": [],
  "links": []
}
```

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

### Delete Custom GUID Definition API

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Deletes a custom GUID definition by its UUID. Associated links targeting the deleted GUID are also removed.

```json
{
  "id": "uuid",
  "name": "guid_letterboxd",
  "type": "plex"
}
```

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

### POST /v1/api/identities/provision

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Initiates identity provisioning.

```APIDOC
## POST /v1/api/identities/provision

### Description
Initiates identity provisioning.

### Method
POST

### Endpoint
/v1/api/identities/provision
```

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

### Delete Custom GUID Definition

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Deletes a custom GUID definition by its ID.

```APIDOC
## DELETE /v1/api/system/guids/custom/{id}

### Description
Deletes a custom GUID definition.

### Method
DELETE

### Endpoint
/v1/api/system/guids/custom/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Custom GUID UUID.

### Response
#### Success Response (200)
- **id** (string) - The deleted GUID's ID.
- **name** (string) - The name of the deleted GUID.
- **type** (string) - The type of the deleted GUID.

#### Response Example
```json
{
  "id": "uuid",
  "name": "guid_letterboxd",
  "type": "plex"
}
```

### Errors
- `404 Not Found` if the GUID is not found.

### Notes
- Links that target the deleted GUID are removed automatically.
```

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

### Create Admin Account

Source: https://context7.com/arabcoders/watchstate/llms.txt

Creates the initial admin account for WatchState. This endpoint only works when no user exists yet. The response is an empty body with a 201 Created status.

```bash
# Initial setup — only works when no user exists yet
curl -s -X POST http://localhost:8080/v1/api/system/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"secret"}'
# Response: 201 Created (empty body)

```

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

### List GUID Types

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Lists supported GUID types and their associated validators.

```APIDOC
## GET /v1/api/system/guids

### Description
Lists supported GUID types and validators.

### Method
GET

### Endpoint
/v1/api/system/guids

### Response
#### Success Response (200)
- An array of GUID type objects.
  - **guid** (string) - The GUID type identifier.
  - **type** (string) - The media type associated with the GUID.
  - **validator** (object) - The validation rules for the GUID.
    - **pattern** (string) - The regular expression pattern for validation.

#### Response Example
```json
[
  {
    "guid": "imdb",
    "type": "movie",
    "validator": {
      "pattern": "..."
    }
  }
]
```
```

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

### Running WatchState with Docker Compose

Source: https://github.com/arabcoders/watchstate/blob/master/README.md

This command creates the necessary data directory and starts the WatchState container using Docker Compose. Ensure your compose.yaml file is in the current directory.

```bash
mkdir -p ./data && docker compose up -d
```

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

### Add Custom GUID Definition

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Adds a new custom GUID definition to the configuration.

```APIDOC
## PUT /v1/api/system/guids/custom

### Description
Adds a custom GUID definition.

### Method
PUT

### Endpoint
/v1/api/system/guids/custom

### Parameters
#### Request Body
- **name** (string) - Required - The name of the custom GUID (e.g., 'letterboxd').
- **type** (string) - Required - The backend client type (e.g., 'plex', 'jellyfin').
- **description** (string) - Optional - A description for the GUID.
- **validator** (object) - Required - The validation rules for the GUID.
  - **pattern** (string) - Required - The regular expression pattern.
  - **example** (string) - Optional - An example of a valid GUID.
  - **tests** (object) - Optional - Test cases for validation.
    - **valid** (array) - Array of valid GUID examples.
    - **invalid** (array) - Array of invalid GUID examples.

### Request Example
```json
{
  "name": "letterboxd",
  "type": "plex",
  "description": "Letterboxd movie GUID",
  "validator": {
    "pattern": "/^[a-z0-9-]+$/",
    "example": "movie-name",
    "tests": {
      "valid": ["movie-name"],
      "invalid": ["movie name"]
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the custom GUID.
- **type** (string) - The backend client type.
- **name** (string) - The name of the custom GUID.
- **description** (string) - The description of the GUID.
- **validator** (object) - The validation rules.

#### Response Example
```json
{
  "id": "uuid",
  "type": "plex",
  "name": "guid_letterboxd",
  "description": "Letterboxd movie GUID",
  "validator": {
    "pattern": "/^[a-z0-9-]+$/",
    "example": "movie-name",
    "tests": {
      "valid": ["movie-name"],
      "invalid": ["movie name"]
    }
  }
}
```

### Errors
- `400 Bad Request` if required fields are missing, the regex is invalid, or the tests do not match the supplied pattern rules.

### Notes
- If the name does not start with `guid_`, WatchState adds the prefix automatically.
- `type` must be one of the configured supported backend/client names such as `plex`, `jellyfin`, or `emby`, not a media type like `movie`.
```

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

### Start Plex PIN Flow

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Initiate the Plex PIN flow for browser or device login. This endpoint is open access.

```json
{
  "id": 123456,
  "code": "ABCD",
  "...": "Plex pin payload"
}
```

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

### Read Custom GUID Configuration

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Reads the custom GUID configuration file, which includes definitions and links.

```APIDOC
## GET /v1/api/system/guids/custom

### Description
Reads the custom GUID configuration file.

### Method
GET

### Endpoint
/v1/api/system/guids/custom

### Response
#### Success Response (200)
- **version** (string) - The version of the configuration.
- **guids** (array) - An array of custom GUID definitions.
- **links** (array) - An array of custom GUID links.

#### Response Example
```json
{
  "version": "0.0",
  "guids": [],
  "links": []
}
```
```

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

### List All Identities

Source: https://context7.com/arabcoders/watchstate/llms.txt

Use this GET request to list all configured identities and their associated backends. Requires an API key.

```bash
curl -s -H "X-APIKEY: <key>" http://localhost:8080/v1/api/identities
# Response:
# {
#   "identities": [
#     { "identity": "main",  "backends": ["plex_main","jellyfin_main"] },
#     { "identity": "alice", "backends": ["plex_alice","jellyfin_alice"] }
#   ]
# }
```

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

### List Custom GUID Links for Client

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Lists custom GUID links for a specific backend client type.

```APIDOC
## GET /v1/api/system/guids/custom/{client}

### Description
Lists custom GUID links for one backend client type.

### Method
GET

### Endpoint
/v1/api/system/guids/custom/{client}

### Parameters
#### Path Parameters
- **client** (string) - Required - Backend type such as `plex`, `jellyfin`, or `emby`.

### Response
#### Success Response (200)
- An array of custom GUID link objects.
  - **id** (string) - The GUID's ID.
  - **type** (string) - The backend client type.
  - **map** (object) - The mapping configuration.
    - **from** (string) - The source field name.
    - **to** (string) - The target GUID name.

#### Response Example
```json
[
  {
    "id": "uuid",
    "type": "plex",
    "map": {
      "from": "GuidField",
      "to": "guid_letterboxd"
    }
  }
]
```

### Errors
- `404 Not Found` if the client type is unsupported.
```

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

### Delete Custom GUID Link

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Deletes a custom GUID link for a specific backend client, identified by its unique ID.

```APIDOC
## DELETE /v1/api/system/guids/custom/{client}/{id}

### Description
Deletes a custom GUID link for one backend client.

### Method
DELETE

### Endpoint
/v1/api/system/guids/custom/{client}/{id}

### Parameters
#### Path Parameters
- **client** (string) - Required - Backend type.
- **id** (string) - Required - Link UUID.

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier of the deleted link.
- **type** (string) - The type of the GUID link.
- **map** (object) - The mapping configuration.
  - **from** (string) - The source GUID field name.
  - **to** (string) - The target GUID field name.

#### Response Example
```json
{
  "id": "uuid",
  "type": "plex",
  "map": {
    "from": "GuidField",
    "to": "guid_letterboxd"
  }
}
```

### Errors
- `404 Not Found` if the link does not exist.
```

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

### Create Backend Definition Response

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Response format after successfully creating a backend definition, confirming saved fields.

```json
{
  "name": "plex_main",
  "type": "plex",
  "url": "https://plex.example.com",
  "uuid": "...",
  "token": "secret-token",
  "...": "saved backend fields"
}
```

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

### POST /v1/api/identities/provision/sync-backends

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Synchronizes identity provisioning with backends.

```APIDOC
## POST /v1/api/identities/provision/sync-backends

### Description
Synchronizes identity provisioning with backends.

### Method
POST

### Endpoint
/v1/api/identities/provision/sync-backends
```

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

### Force Reindex Database for GUIDs

Source: https://github.com/arabcoders/watchstate/blob/master/FAQ.md

Execute this command after modifying the guid.yaml file to update the database indexes with new or removed GUIDs.

```bash
db:index --force-reindex
```

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

### Get Users from Backend

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves users from an arbitrary backend connection without saving it first. Supports both GET and POST methods.

```APIDOC
## GET|POST /v1/api/backends/users/{type}

### Description
Returns users from an arbitrary backend connection without saving it first.

### Method
GET | POST

### Endpoint
/v1/api/backends/users/{type}

### Parameters
#### Path Parameters
- **type** (string) - Required - Backend type.

#### Query Parameters
- **url** (string) - Required - The URL of the backend.
- **token** (string) - Required - The authentication token for the backend.
- **tokens** (string) - Optional - Include backend-specific user tokens when supported.
- **target_user** (string) - Optional - Narrow the result to a specific backend user.
- **no_cache** (boolean) - Optional - Force a fresh fetch.

#### Request Body
- **url** (string) - Required - The URL of the backend.
- **token** (string) - Required - The authentication token for the backend.
- **tokens** (string) - Optional - Include backend-specific user tokens when supported.
- **target_user** (string) - Optional - Narrow the result to a specific backend user.
- **no_cache** (boolean) - Optional - Force a fresh fetch.

### Response
#### Success Response (200)
- **id** (string) - Description
- **name** (string) - Description
- **...** (any) - backend user fields

#### Response Example
```json
[
  {
    "id": "...",
    "name": "...",
    "...": "backend user fields"
  }
]
```

### Errors
- `400 Bad Request` if the backend type, URL, or token is invalid.
- `500 Internal Server Error` if the remote backend request fails.
```

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

### Get Identity Provisioning Preview

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieve the current identity provisioning preview. Use the `force` query parameter to bypass the cache and rebuild the preview.

```json
{
  "has_identities": true,
  "has_mapping": true,
  "backends": ["plex_main", "jellyfin_main"],
  "matched": [
    {
      "identity": "alice",
      "members": [
        {
          "id": "123",
          "username": "alice",
          "backend": "plex_main",
          "real_name": "Alice",
          "type": "plex",
          "protected": false,
          "options": {}
        }
      ]
    }
  ],
  "unmatched": [
    {
      "id": "789",
      "username": "bob",
      "backend": "plex_main",
      "real_name": "Bob",
      "type": "plex",
      "protected": true,
      "options": {}
    }
  ],
  "expires": "2026-03-28T12:05:00+00:00"
}
```

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

### Get Users from Backend

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieve users from an arbitrary backend connection. Supports GET and POST methods. Requires `url` and `token`.

```json
[
  {
    "id": "...",
    "name": "...",
    "...": "backend user fields"
  }
]
```

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

### Enable Hardware Acceleration in compose.yaml

Source: https://github.com/arabcoders/watchstate/blob/master/FAQ.md

Configure your compose.yaml to mount necessary devices for hardware acceleration on Debian-based systems. Ensure your group IDs for 'video' and 'render' match your system.

```yaml
services:
    watchstate:
        container_name: watchstate
        image: ghcr.io/arabcoders/watchstate:latest   # The image to use. you can use the latest or dev tag.
        user: "${UID:-1000}:${UID:-1000}"             # user and group id to run the container under. 
        group_add:
            - "44"                                    # Add video group to the container.
            - "105"                                   # Add render group to the container.
        restart: unless-stopped
        ports:
            - "8080:8080"                             # The port which the watchstate will listen on. 
        devices:
            - /dev/dri:/dev/dri                       # mount the dri devices to the container.
        volumes:
            - ./data:/config:rw                       # mount current directory to container /config directory.
            - /storage/media:/media:ro                # mount your media directory to the container.

```

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

### Add Custom GUID Link

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Adds a custom GUID link for a specific backend client type. The 'options.legacy' field is required for Plex links.

```json
{
  "type": "plex",
  "map": {
    "from": "GuidField",
    "to": "letterboxd"
  },
  "options": {
    "legacy": true
  },
  "replace": {
    "from": "old",
    "to": "new"
  }
}
```

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

### Plex PIN Login Flow

Source: https://context7.com/arabcoders/watchstate/llms.txt

Initiates the Plex PIN login flow. Step 1 generates a PIN, which the user then enters on plex.tv/link to authorize the connection.

```bash
# Step 1: generate a PIN
PIN=$(curl -s -X POST http://localhost:8080/v1/api/backends/plex/generate \
  -H "X-APIKEY: <key>")
echo $PIN
```

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

### Add Custom GUID Link

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Adds a custom GUID link for a specific backend client type. This allows for custom mapping of identifiers between different services.

```APIDOC
## PUT /v1/api/system/guids/custom/{client}

### Description
Adds a custom GUID link for one backend client type.

### Method
PUT

### Endpoint
/v1/api/system/guids/custom/{client}

### Parameters
#### Path Parameters
- **client** (string) - Required - Backend type.

#### Request Body
- **type** (string) - Required - The type of the GUID link (e.g., "plex").
- **map** (object) - Required - Defines the mapping between source and target GUID fields.
  - **from** (string) - Required - The source GUID field name.
  - **to** (string) - Required - The target GUID field name.
- **options** (object) - Optional - Additional options for the link.
  - **legacy** (boolean) - Required for Plex links - Must be truthy.
- **replace** (object) - Optional - Defines a replacement mapping.
  - **from** (string) - Required - The old GUID field name to replace.
  - **to** (string) - Required - The new GUID field name.

### Request Example
```json
{
  "type": "plex",
  "map": {
    "from": "GuidField",
    "to": "letterboxd"
  },
  "options": {
    "legacy": true
  },
  "replace": {
    "from": "old",
    "to": "new"
  }
}
```

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier for the created link.
- **type** (string) - The type of the GUID link.
- **map** (object) - The mapping configuration.
  - **from** (string) - The source GUID field name.
  - **to** (string) - The target GUID field name.
- **options** (object) - The options for the link.
  - **legacy** (boolean) - Indicates if legacy options are enabled.

#### Response Example
```json
{
  "id": "uuid",
  "type": "plex",
  "map": {
    "from": "GuidField",
    "to": "guid_letterboxd"
  },
  "options": {
    "legacy": true
  }
}
```

### Errors
- `400 Bad Request` if required fields are missing, the target GUID is unsupported, or the mapping already exists.
```

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

### API Key Authentication

Source: https://context7.com/arabcoders/watchstate/llms.txt

Demonstrates how to authenticate API requests using an API key, either via a header or a query string parameter.

```bash
# API key via header
curl -H "X-APIKEY: <api-key>" http://localhost:8080/v1/api/backends

# API key via query string
curl "http://localhost:8080/v1/api/backends?apikey=<api-key>"

```

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

### Delete Custom GUID Link

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Deletes a custom GUID link for a given backend client and link ID. Returns the deleted link's details.

```json
{
  "id": "uuid",
  "type": "plex",
  "map": {
    "from": "GuidField",
    "to": "guid_letterboxd"
  }
}
```

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

### Find Items Without GUIDs

Source: https://context7.com/arabcoders/watchstate/llms.txt

Scan all libraries for items that WatchState cannot match across backends due to missing GUIDs. This helps identify potential matching issues.

```bash
# Scan all libraries for items WatchState cannot match cross-backend
curl -s -H "X-APIKEY: <key>" \
  "http://localhost:8080/v1/api/backend/emby_main/unmatched"
```

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

### Configure Synchronous Requests for Media Backend

Source: https://github.com/arabcoders/watchstate/blob/master/FAQ.md

Modify the WS_CRON_IMPORT_ARGS environment variable to include '--sync-requests' for tasks like 'Import' to use synchronous requests, reducing load on the media backend.

```bash
-v --sync-requests
```

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

### GET|POST|PATCH|DELETE /v1/api/backend/{name}/option[/{option}]

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Gets, sets, or deletes a single backend option. Supports GET for reading, POST/PATCH for setting, and DELETE for removing options.

```APIDOC
## GET|POST|PATCH|DELETE /v1/api/backend/{name}/option[/{option}]

### Description
Gets, sets, or deletes a single backend option.

### Method
GET, POST, PATCH, or DELETE

### Endpoint
/v1/api/backend/{name}/option[/{option}]

### Parameters
#### Path Parameters
- **name** (string) - Required - Saved backend name.
- **option** (string) - Optional - Option key. Can also be sent as `key`.

#### Query Parameters
- **key** (string) - Required for GET method if option is not in path - The key of the option to retrieve.

#### Request Body
- **key** (string) - Required for POST/PATCH/DELETE - The key of the option.
- **value** (any) - Optional for POST/PATCH - The value to set for the option.

### Response
#### Success Response (200)
- **key** (string) - The option key.
- **value** (any) - The current value of the option.
- **real_val** (string) - The raw string representation of the value.
- **type** (string) - The data type of the option value.
- **description** (string) - A description of the option.

#### Response Example
```json
{
  "key": "options.client.timeout",
  "value": 30,
  "real_val": "30",
  "type": "float",
  "description": "HTTP timeout in seconds"
}
```

### Errors
- 400 Bad Request: If the key is missing, invalid, outside the allowed namespace, or if validation fails.
- 404 Not Found: If the user, backend, or option does not exist.
```

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

### System Version Information

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Retrieves build and runtime version metadata for the WatchState system.

```APIDOC
## GET /v1/api/system/version

### Description
Returns build and runtime version metadata.

### Method
GET

### Endpoint
/v1/api/system/version

### Response
#### Success Response (200)
```json
{
  "version": "dev-master",
  "build": "unknown",
  "sha": "unknown",
  "branch": "unknown",
  "container": true
}
```
```

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

### List Processes

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Returns the current OS process list.

```APIDOC
## GET /v1/api/system/processes

### Description
Returns the current OS process list.

### Method
GET

### Endpoint
/v1/api/system/processes

### Response
#### Success Response
- **processes** (array) - A list of OS processes.
  - **user** (string) - The user running the process.
  - **pid** (string) - The process ID.
  - **cpu** (string) - CPU usage percentage.
  - **mem** (string) - Memory usage percentage.
  - **command** (string) - The command that started the process.

#### Response Example
```json
{
  "processes": [
    {
      "user": "root",
      "pid": "123",
      "cpu": "0.0",
      "mem": "0.1",
      "command": "php-fpm"
    }
  ]
}
```

### Errors
- `500 Internal Server Error` if `ps aux` fails.
```

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

### List Custom GUID Links API

Source: https://github.com/arabcoders/watchstate/blob/master/API.md

Lists custom GUID links for a specific backend client type. The `client` path parameter specifies the backend type (e.g., `plex`, `jellyfin`).

```json
[
  {
    "id": "uuid",
    "type": "plex",
    "map": {
      "from": "GuidField",
      "to": "guid_letterboxd"
    }
  }
]
```