# Settings

Daemon settings and user preferences.

Back to the [web API reference](/docs/server/api/index.md).

## `GET /api/settings`

Returns file-backed and runtime-effective Settings plus per-plugin groups.

**Access:** The operator (token or session) only.

**Credentials:** `operatorToken` or `operatorSession`

### Responses

- `200` — The settings. Body: [`SettingsResponse`](/docs/server/api/schemas/index.md#settingsresponse) (`application/json`)
  - `settings` *map of string to string*, **required** — Values as written in config.toml (and env overlays), plus `output.*` from the `core.output` database document.
  - `effective` *map of string to string*, **required** — Runtime-effective values after the last successful reload (auth, plugins).
  - `plugins` *array of [`PluginSettingsGroup`](/docs/server/api/schemas/index.md#pluginsettingsgroup)*, **required** — Per-plugin setting groups rendered by the Settings UI.
  - `host_cpu_cores_max` *number (double)*, **required** — Host max jail CPU in cores (2 d.p.; equals logical CPU count).
  - `jail_cpu_cores` *number (double) or null* — Optional global per-jail CPU ceiling in cores (from `[plugins.jail]`).
  - `output_revision` *integer (int64) or null* — Revision of the `core.output` document the `output.*` values in `settings` were read from; send it back as `expected_output_revision`. `effective["output.revision"]` is the revision this host has applied, which lags the document until the host's next wakeup.
- `401` — The caller is not signed in, or the credential is wrong. Body: [`ApiError`](/docs/server/api/schemas/index.md#apierror) (`application/json`)
  - `error` *string*, **required** — Stable machine slug.
  - `message` *string* — Explanation for people.
  - `status` *integer* — The HTTP status, repeated.
- `403` — The caller's role does not allow this route. Body: [`ApiError`](/docs/server/api/schemas/index.md#apierror) (`application/json`)
  - `error` *string*, **required** — Stable machine slug.
  - `message` *string* — Explanation for people.
  - `status` *integer* — The HTTP status, repeated.
- `500` — The settings could not be read. Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `504` — The request ran past the API's time budget. Body: string (`text/plain`)

### Example request

```console
$ curl 'http://127.0.0.1:8787/api/settings' \
    -H 'Authorization: Bearer <operatorToken>'
```

```powershell
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/settings' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
```

```python
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/settings",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
```

```javascript
const response = await fetch("http://127.0.0.1:8787/api/settings", {
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
```

```rust
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/settings")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);
```

### Example response

Status `200`: The settings.

```json
{
  "settings": {
    "daemon.auth.enabled": "true",
    "daemon.listen": "127.0.0.1:8787,[::1]:8787",
    "library.auto_acquire": "false"
  },
  "effective": {
    "daemon.auth.enabled": "true",
    "daemon.listen": "127.0.0.1:8787,[::1]:8787",
    "library.auto_acquire": "false"
  },
  "plugins": [
    {
      "id": "libro",
      "family": "source",
      "plugin_key": "platform:bookclerk/bookclerk-plugin-source-libro#libro",
      "provenance": "platform_bundled",
      "logo": "/api/images/aHR0cHM6Ly93d3cuZ29vZ2xlLmNvbS9zMi9mYXZpY29ucz9kb21haW49bGlicm8uZm0mc3o9MTI4.N14rqh66Bok9-eCqJKBNoQ",
      "settings": [
        {
          "key": "container",
          "label": "Container",
          "value": "m4b",
          "value_type": "string"
        }
      ],
      "plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
      "display_name": "Libro.fm (household)",
      "is_default": true,
      "config_revision": 4,
      "deployment": {
        "deployment_id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
        "node_id": "node-7f3a9c",
        "desired": "present",
        "revision": 3,
        "status": "healthy",
        "detail": "",
        "applied_config_revision": 5,
        "observed_at": "2026-10-28T19:07:00Z"
      },
      "placement": {
        "replicas": 0,
        "constraints": [
          "target=linux-x64-gnu",
          "!drain"
        ],
        "revision": 2,
        "placed": 1,
        "detail": "",
        "scheduled_at": "2026-10-28T19:07:00Z",
        "updated_at": "2026-10-28T19:05:00Z"
      },
      "storage_sync": {
        "feed_state": "off",
        "feed_error": "the notification queue refused the request: access denied",
        "feed_checked_at": "2026-11-20T21:00:00Z",
        "listed_at": "2026-11-20T18:00:00Z",
        "next_listing_at": "2026-11-21T00:00:00Z",
        "listing_in_progress": false,
        "listing_error": "the listing missed 412 of 1832 known files; removals were not applied",
        "objects": 1832
      },
      "present_on": [
        "6d1f2e3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a"
      ]
    }
  ],
  "host_cpu_cores_max": 8.0,
  "jail_cpu_cores": 2.0,
  "output_revision": 7
}
```

Schema:

```json
{
  "type": "object",
  "description": "Settings page payload: file values, effective runtime, and plugin groups.",
  "required": [
    "settings",
    "effective",
    "plugins",
    "host_cpu_cores_max"
  ],
  "properties": {
    "settings": {
      "type": "object",
      "description": "Values as written in config.toml (and env overlays), plus `output.*`\nfrom the `core.output` database document.",
      "additionalProperties": {
        "type": "string"
      },
      "propertyNames": {
        "type": "string"
      },
      "example": {
        "daemon.auth.enabled": "true",
        "daemon.listen": "127.0.0.1:8787,[::1]:8787",
        "library.auto_acquire": "false"
      }
    },
    "effective": {
      "type": "object",
      "description": "Runtime-effective values after the last successful reload (auth, plugins).",
      "additionalProperties": {
        "type": "string"
      },
      "propertyNames": {
        "type": "string"
      },
      "example": {
        "daemon.auth.enabled": "true",
        "daemon.listen": "127.0.0.1:8787,[::1]:8787",
        "library.auto_acquire": "false"
      }
    },
    "plugins": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Settings UI group for one discovered or loaded plugin.",
        "required": [
          "id",
          "family",
          "settings"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Plugin id (`audible`, `sqlite`, and similar).",
            "example": "libro"
          },
          "family": {
            "type": "string",
            "description": "Handler family wire label (`source`, `integration`, `output`, `database`).",
            "example": "source"
          },
          "plugin_key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Provenance-qualified PluginKey when this row came from a discovered install.",
            "example": "platform:bookclerk/bookclerk-plugin-source-libro#libro"
          },
          "provenance": {
            "type": [
              "string",
              "null"
            ],
            "description": "Host-evaluated provenance (`platform_bundled`, `verified_staged`, `installed`, …).",
            "example": "platform_bundled"
          },
          "logo": {
            "type": [
              "string",
              "null"
            ],
            "description": "Same-origin logo for Settings list rows: the plugin's embedded logo,\nor a 128 px copy of the remote logo its manifest names.",
            "example": "/api/images/aHR0cHM6Ly93d3cuZ29vZ2xlLmNvbS9zMi9mYXZpY29ucz9kb21haW49bGlicm8uZm0mc3o9MTI4.N14rqh66Bok9-eCqJKBNoQ"
          },
          "settings": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "One editable setting shown in the Settings UI.",
              "required": [
                "key",
                "label",
                "value",
                "value_type"
              ],
              "properties": {
                "key": {
                  "type": "string",
                  "description": "Dotted `config.toml` key for this option.",
                  "example": "container"
                },
                "label": {
                  "type": "string",
                  "description": "Operator-facing field caption.",
                  "example": "Container"
                },
                "value": {
                  "type": "string",
                  "description": "Current string form of the setting.",
                  "example": "m4b"
                },
                "value_type": {
                  "type": "string",
                  "description": "UI widget hint (`boolean`, `string`, `number`, `secret`, or\n`table`).",
                  "example": "string"
                },
                "choices": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "One selectable value for a Settings dropdown.",
                    "required": [
                      "value",
                      "label"
                    ],
                    "properties": {
                      "value": {
                        "type": "string",
                        "description": "Stored config value; empty string means use the plugin default.",
                        "example": "m4b"
                      },
                      "label": {
                        "type": "string",
                        "description": "Operator-facing choice caption.",
                        "example": "M4B"
                      }
                    }
                  },
                  "description": "Optional dropdown values; omitted for free-form fields."
                },
                "secret": {
                  "type": "boolean",
                  "description": "True for a `secret` setting: `value` is never the stored value.",
                  "example": false
                },
                "secret_set": {
                  "type": [
                    "boolean",
                    "null"
                  ],
                  "description": "For a secret setting, whether the instance document names a sealed value.",
                  "example": true
                },
                "columns": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "One column of a `table` setting in the Settings UI.",
                    "required": [
                      "key",
                      "label",
                      "value_type"
                    ],
                    "properties": {
                      "key": {
                        "type": "string",
                        "description": "Record field the column fills in each row.",
                        "example": "prefix"
                      },
                      "label": {
                        "type": "string",
                        "description": "Column heading.",
                        "example": "Storage key prefix"
                      },
                      "value_type": {
                        "type": "string",
                        "description": "UI widget hint (`boolean`, `string`, or `number`).",
                        "example": "string"
                      },
                      "choices": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "object",
                          "description": "One selectable value for a Settings dropdown.",
                          "required": [
                            "value",
                            "label"
                          ],
                          "properties": {
                            "value": {
                              "type": "string",
                              "description": "Stored config value; empty string means use the plugin default.",
                              "example": "m4b"
                            },
                            "label": {
                              "type": "string",
                              "description": "Operator-facing choice caption.",
                              "example": "M4B"
                            }
                          }
                        },
                        "description": "Dropdown values of an `enum` column; omitted otherwise."
                      },
                      "default": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "String form of the value a new row starts with; omitted when there\nis no default.",
                        "example": ""
                      },
                      "required": {
                        "type": "boolean",
                        "description": "True when every row must have a value in this column.",
                        "example": true
                      }
                    }
                  },
                  "description": "Columns of a `table` setting, in display order; omitted for other\nkinds. `value` is then the rows as JSON text."
                }
              }
            },
            "description": "Editable options for this plugin, including `.enabled`."
          },
          "plugin_instance_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Plugin instance this group edits; absent for a bootstrap database adapter.",
            "example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Operator-facing instance name, when the operator set one.",
            "example": "Libro.fm (household)"
          },
          "is_default": {
            "type": "boolean",
            "description": "True when a bare plugin key or alias routes to this instance.",
            "example": true
          },
          "config_revision": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Instance document revision for compare-and-swap writes.",
            "example": 4
          },
          "deployment": {
            "oneOf": [
              {
                "type": "object",
                "description": "This node's deployment of the instance, when one exists.",
                "required": [
                  "deployment_id",
                  "node_id",
                  "desired",
                  "revision"
                ],
                "properties": {
                  "deployment_id": {
                    "type": "string",
                    "description": "Deployment row id.",
                    "example": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
                  },
                  "node_id": {
                    "type": "string",
                    "description": "Node the row targets.",
                    "example": "node-7f3a9c"
                  },
                  "desired": {
                    "type": "string",
                    "description": "What the row asks the node to do: `present` / `absent` from an\noperator, `placed` / `unplaced` from the scheduler.",
                    "enum": [
                      "present",
                      "absent",
                      "placed",
                      "unplaced"
                    ]
                  },
                  "revision": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Compare-and-swap revision of the desired row.",
                    "example": 3
                  },
                  "status": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Latest observation status from that node, when it reported one.",
                    "example": "healthy"
                  },
                  "detail": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Observation detail (error text, redacted).",
                    "example": ""
                  },
                  "applied_config_revision": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "format": "int64",
                    "description": "Document revision the running guest applied.",
                    "example": 5
                  },
                  "observed_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "RFC 3339 time of the observation.",
                    "example": "2026-10-28T19:07:00Z"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "placement": {
            "oneOf": [
              {
                "type": "object",
                "description": "Scheduler placement; absent when the instance is hand-managed (the\nEnabled switch applies only then).",
                "required": [
                  "replicas",
                  "constraints",
                  "revision",
                  "placed",
                  "detail",
                  "scheduled_at",
                  "updated_at"
                ],
                "properties": {
                  "replicas": {
                    "oneOf": [
                      {
                        "type": "integer",
                        "minimum": 0
                      },
                      {
                        "type": "string",
                        "enum": [
                          "all"
                        ]
                      }
                    ],
                    "description": "A replica count (0 stops every replica) or `\"all\"`."
                  },
                  "constraints": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Label constraints every chosen node must satisfy.",
                    "example": [
                      "target=linux-x64-gnu",
                      "!drain"
                    ]
                  },
                  "revision": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Compare-and-swap revision of the intent.",
                    "example": 2
                  },
                  "placed": {
                    "type": "integer",
                    "format": "int32",
                    "description": "Replicas the last scheduler pass placed.",
                    "example": 1,
                    "minimum": 0
                  },
                  "detail": {
                    "type": "string",
                    "description": "Why fewer than requested are placed; empty when satisfied.",
                    "example": ""
                  },
                  "scheduled_at": {
                    "type": "string",
                    "description": "RFC 3339 time the scheduler last changed the status.",
                    "example": "2026-10-28T19:07:00Z"
                  },
                  "updated_at": {
                    "type": "string",
                    "description": "RFC 3339 time of the last intent write.",
                    "example": "2026-10-28T19:05:00Z"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "storage_sync": {
            "oneOf": [
              {
                "type": "object",
                "description": "How outside changes at this destination are followed; absent for\nother plugins and before a destination's first sync pass.",
                "required": [
                  "feed_state",
                  "listing_in_progress",
                  "objects"
                ],
                "properties": {
                  "feed_state": {
                    "type": "string",
                    "description": "The change feed's state: `off` (no feed; listings alone), `healthy`,\n`gap` (the feed may have missed changes; a listing runs at once) or\n`failing` (reading the feed failed; listings cover it).",
                    "enum": [
                      "off",
                      "healthy",
                      "gap",
                      "failing"
                    ]
                  },
                  "feed_error": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The last feed failure.",
                    "example": "the notification queue refused the request: access denied"
                  },
                  "feed_checked_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "RFC 3339 time the feed was last read.",
                    "example": "2026-11-20T21:00:00Z"
                  },
                  "listed_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "RFC 3339 time the last listing finished.",
                    "example": "2026-11-20T18:00:00Z"
                  },
                  "next_listing_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "RFC 3339 time the next scheduled listing is due.",
                    "example": "2026-11-21T00:00:00Z"
                  },
                  "listing_in_progress": {
                    "type": "boolean",
                    "description": "True while a listing is in progress (it continues on the next\npass).",
                    "example": false
                  },
                  "listing_error": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Why the last listing failed or its removals were held back.",
                    "example": "the listing missed 412 of 1832 known files; removals were not applied"
                  },
                  "objects": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Files the destination held after the last listing or feed page.",
                    "example": 1832,
                    "minimum": 0
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "present_on": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Nodes whose deployment of the instance is `present`.",
            "example": [
              "6d1f2e3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a"
            ]
          }
        }
      },
      "description": "Per-plugin setting groups rendered by the Settings UI."
    },
    "host_cpu_cores_max": {
      "type": "number",
      "format": "double",
      "description": "Host max jail CPU in cores (2 d.p.; equals logical CPU count).",
      "example": 8.0
    },
    "jail_cpu_cores": {
      "type": [
        "number",
        "null"
      ],
      "format": "double",
      "description": "Optional global per-jail CPU ceiling in cores (from `[plugins.jail]`).",
      "example": 2.0
    },
    "output_revision": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "Revision of the `core.output` document the `output.*` values in\n`settings` were read from; send it back as `expected_output_revision`.\n`effective[\"output.revision\"]` is the revision this host has applied,\nwhich lags the document until the host's next wakeup.",
      "example": 7
    }
  }
}
```

Status `401`: The caller is not signed in, or the credential is wrong.

```json
{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}
```

Schema:

```json
{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}
```

Status `403`: The caller's role does not allow this route.

```json
{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}
```

Schema:

```json
{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}
```

Status `500`: The settings could not be read.

```json
{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `504`: The request ran past the API's time budget.

```text
request timed out
```

Schema:

A `text/plain` body: a string.

## `PATCH /api/settings`

Validates, writes, and reloads allowlisted Settings keys under `reload_lock`.

**Access:** The operator (token or session) only.

**Credentials:** `operatorToken` or `operatorSession`

### Request body

`application/json`: [`PatchSettingsRequest`](/docs/server/api/schemas/index.md#patchsettingsrequest)

- `settings` *array of [`SettingsUpdate`](/docs/server/api/schemas/index.md#settingsupdate)*, **required** — Key/value pairs to validate, persist, and reload.
- `expected_output_revision` *integer (int64) or null* — `core.output` document revision the client read (`output_revision` in `GET /api/settings`). When set and stale, an `output.*` update is rejected with 409.

### Responses

- `200` — The settings after the change. Body: [`SettingsResponse`](/docs/server/api/schemas/index.md#settingsresponse) (`application/json`)
  - `settings` *map of string to string*, **required** — Values as written in config.toml (and env overlays), plus `output.*` from the `core.output` database document.
  - `effective` *map of string to string*, **required** — Runtime-effective values after the last successful reload (auth, plugins).
  - `plugins` *array of [`PluginSettingsGroup`](/docs/server/api/schemas/index.md#pluginsettingsgroup)*, **required** — Per-plugin setting groups rendered by the Settings UI.
  - `host_cpu_cores_max` *number (double)*, **required** — Host max jail CPU in cores (2 d.p.; equals logical CPU count).
  - `jail_cpu_cores` *number (double) or null* — Optional global per-jail CPU ceiling in cores (from `[plugins.jail]`).
  - `output_revision` *integer (int64) or null* — Revision of the `core.output` document the `output.*` values in `settings` were read from; send it back as `expected_output_revision`. `effective["output.revision"]` is the revision this host has applied, which lags the document until the host's next wakeup.
- `400` — A key is unknown or a value is invalid. As `text/plain`, when the body is not syntactically valid JSON. Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`); string (`text/plain`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `401` — The caller is not signed in, or the credential is wrong. Body: [`ApiError`](/docs/server/api/schemas/index.md#apierror) (`application/json`)
  - `error` *string*, **required** — Stable machine slug.
  - `message` *string* — Explanation for people.
  - `status` *integer* — The HTTP status, repeated.
- `403` — The caller's role does not allow this route. A write sent with a session cookie but without a matching `Origin` or `Referer` is refused. Body: [`ApiError`](/docs/server/api/schemas/index.md#apierror) (`application/json`)
  - `error` *string*, **required** — Stable machine slug.
  - `message` *string* — Explanation for people.
  - `status` *integer* — The HTTP status, repeated.
- `409` — `output.*` keys were sent with a stale `expected_output_revision`, or another write won; the body's `current_revision` is the revision to retry against (`revision_conflict`). Body: [`ApiError`](/docs/server/api/schemas/index.md#apierror) (`application/json`)
  - `error` *string*, **required** — Stable machine slug.
  - `message` *string* — Explanation for people.
  - `status` *integer* — The HTTP status, repeated.
- `415` — The request did not declare a JSON body. Body: string (`text/plain`)
- `422` — The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (`text/plain`)
- `500` — The settings could not be written. Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `504` — The request ran past the API's time budget. Body: string (`text/plain`)

### Example request

```console
$ curl 'http://127.0.0.1:8787/api/settings' \
    -X PATCH \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{"settings": [{"key": "library.auto_acquire", "value": "false"}]}'
```

```powershell
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/settings' `
    -Method Patch `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{"settings": [{"key": "library.auto_acquire", "value": "false"}]}'
```

```python
import requests

response = requests.patch(
    "http://127.0.0.1:8787/api/settings",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={"settings": [{"key": "library.auto_acquire", "value": "false"}]},
)
print(response.status_code, response.text)
```

```javascript
const response = await fetch("http://127.0.0.1:8787/api/settings", {
  method: "PATCH",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"settings": [{"key": "library.auto_acquire", "value": "false"}]}),
});
console.log(response.status, await response.text());
```

```rust
let client = reqwest::Client::new();
let response = client
    .patch("http://127.0.0.1:8787/api/settings")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({"settings": [{"key": "library.auto_acquire", "value": "false"}]}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);
```

### Example response

Status `200`: The settings after the change.

```json
{
  "settings": {
    "daemon.auth.enabled": "true",
    "daemon.listen": "127.0.0.1:8787,[::1]:8787",
    "library.auto_acquire": "false"
  },
  "effective": {
    "daemon.auth.enabled": "true",
    "daemon.listen": "127.0.0.1:8787,[::1]:8787",
    "library.auto_acquire": "false"
  },
  "plugins": [
    {
      "id": "libro",
      "family": "source",
      "plugin_key": "platform:bookclerk/bookclerk-plugin-source-libro#libro",
      "provenance": "platform_bundled",
      "logo": "/api/images/aHR0cHM6Ly93d3cuZ29vZ2xlLmNvbS9zMi9mYXZpY29ucz9kb21haW49bGlicm8uZm0mc3o9MTI4.N14rqh66Bok9-eCqJKBNoQ",
      "settings": [
        {
          "key": "container",
          "label": "Container",
          "value": "m4b",
          "value_type": "string"
        }
      ],
      "plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
      "display_name": "Libro.fm (household)",
      "is_default": true,
      "config_revision": 4,
      "deployment": {
        "deployment_id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
        "node_id": "node-7f3a9c",
        "desired": "present",
        "revision": 3,
        "status": "healthy",
        "detail": "",
        "applied_config_revision": 5,
        "observed_at": "2026-10-28T19:07:00Z"
      },
      "placement": {
        "replicas": 0,
        "constraints": [
          "target=linux-x64-gnu",
          "!drain"
        ],
        "revision": 2,
        "placed": 1,
        "detail": "",
        "scheduled_at": "2026-10-28T19:07:00Z",
        "updated_at": "2026-10-28T19:05:00Z"
      },
      "storage_sync": {
        "feed_state": "off",
        "feed_error": "the notification queue refused the request: access denied",
        "feed_checked_at": "2026-11-20T21:00:00Z",
        "listed_at": "2026-11-20T18:00:00Z",
        "next_listing_at": "2026-11-21T00:00:00Z",
        "listing_in_progress": false,
        "listing_error": "the listing missed 412 of 1832 known files; removals were not applied",
        "objects": 1832
      },
      "present_on": [
        "6d1f2e3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a"
      ]
    }
  ],
  "host_cpu_cores_max": 8.0,
  "jail_cpu_cores": 2.0,
  "output_revision": 7
}
```

Schema:

```json
{
  "type": "object",
  "description": "Settings page payload: file values, effective runtime, and plugin groups.",
  "required": [
    "settings",
    "effective",
    "plugins",
    "host_cpu_cores_max"
  ],
  "properties": {
    "settings": {
      "type": "object",
      "description": "Values as written in config.toml (and env overlays), plus `output.*`\nfrom the `core.output` database document.",
      "additionalProperties": {
        "type": "string"
      },
      "propertyNames": {
        "type": "string"
      },
      "example": {
        "daemon.auth.enabled": "true",
        "daemon.listen": "127.0.0.1:8787,[::1]:8787",
        "library.auto_acquire": "false"
      }
    },
    "effective": {
      "type": "object",
      "description": "Runtime-effective values after the last successful reload (auth, plugins).",
      "additionalProperties": {
        "type": "string"
      },
      "propertyNames": {
        "type": "string"
      },
      "example": {
        "daemon.auth.enabled": "true",
        "daemon.listen": "127.0.0.1:8787,[::1]:8787",
        "library.auto_acquire": "false"
      }
    },
    "plugins": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "Settings UI group for one discovered or loaded plugin.",
        "required": [
          "id",
          "family",
          "settings"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Plugin id (`audible`, `sqlite`, and similar).",
            "example": "libro"
          },
          "family": {
            "type": "string",
            "description": "Handler family wire label (`source`, `integration`, `output`, `database`).",
            "example": "source"
          },
          "plugin_key": {
            "type": [
              "string",
              "null"
            ],
            "description": "Provenance-qualified PluginKey when this row came from a discovered install.",
            "example": "platform:bookclerk/bookclerk-plugin-source-libro#libro"
          },
          "provenance": {
            "type": [
              "string",
              "null"
            ],
            "description": "Host-evaluated provenance (`platform_bundled`, `verified_staged`, `installed`, …).",
            "example": "platform_bundled"
          },
          "logo": {
            "type": [
              "string",
              "null"
            ],
            "description": "Same-origin logo for Settings list rows: the plugin's embedded logo,\nor a 128 px copy of the remote logo its manifest names.",
            "example": "/api/images/aHR0cHM6Ly93d3cuZ29vZ2xlLmNvbS9zMi9mYXZpY29ucz9kb21haW49bGlicm8uZm0mc3o9MTI4.N14rqh66Bok9-eCqJKBNoQ"
          },
          "settings": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "One editable setting shown in the Settings UI.",
              "required": [
                "key",
                "label",
                "value",
                "value_type"
              ],
              "properties": {
                "key": {
                  "type": "string",
                  "description": "Dotted `config.toml` key for this option.",
                  "example": "container"
                },
                "label": {
                  "type": "string",
                  "description": "Operator-facing field caption.",
                  "example": "Container"
                },
                "value": {
                  "type": "string",
                  "description": "Current string form of the setting.",
                  "example": "m4b"
                },
                "value_type": {
                  "type": "string",
                  "description": "UI widget hint (`boolean`, `string`, `number`, `secret`, or\n`table`).",
                  "example": "string"
                },
                "choices": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "One selectable value for a Settings dropdown.",
                    "required": [
                      "value",
                      "label"
                    ],
                    "properties": {
                      "value": {
                        "type": "string",
                        "description": "Stored config value; empty string means use the plugin default.",
                        "example": "m4b"
                      },
                      "label": {
                        "type": "string",
                        "description": "Operator-facing choice caption.",
                        "example": "M4B"
                      }
                    }
                  },
                  "description": "Optional dropdown values; omitted for free-form fields."
                },
                "secret": {
                  "type": "boolean",
                  "description": "True for a `secret` setting: `value` is never the stored value.",
                  "example": false
                },
                "secret_set": {
                  "type": [
                    "boolean",
                    "null"
                  ],
                  "description": "For a secret setting, whether the instance document names a sealed value.",
                  "example": true
                },
                "columns": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "One column of a `table` setting in the Settings UI.",
                    "required": [
                      "key",
                      "label",
                      "value_type"
                    ],
                    "properties": {
                      "key": {
                        "type": "string",
                        "description": "Record field the column fills in each row.",
                        "example": "prefix"
                      },
                      "label": {
                        "type": "string",
                        "description": "Column heading.",
                        "example": "Storage key prefix"
                      },
                      "value_type": {
                        "type": "string",
                        "description": "UI widget hint (`boolean`, `string`, or `number`).",
                        "example": "string"
                      },
                      "choices": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "object",
                          "description": "One selectable value for a Settings dropdown.",
                          "required": [
                            "value",
                            "label"
                          ],
                          "properties": {
                            "value": {
                              "type": "string",
                              "description": "Stored config value; empty string means use the plugin default.",
                              "example": "m4b"
                            },
                            "label": {
                              "type": "string",
                              "description": "Operator-facing choice caption.",
                              "example": "M4B"
                            }
                          }
                        },
                        "description": "Dropdown values of an `enum` column; omitted otherwise."
                      },
                      "default": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "String form of the value a new row starts with; omitted when there\nis no default.",
                        "example": ""
                      },
                      "required": {
                        "type": "boolean",
                        "description": "True when every row must have a value in this column.",
                        "example": true
                      }
                    }
                  },
                  "description": "Columns of a `table` setting, in display order; omitted for other\nkinds. `value` is then the rows as JSON text."
                }
              }
            },
            "description": "Editable options for this plugin, including `.enabled`."
          },
          "plugin_instance_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Plugin instance this group edits; absent for a bootstrap database adapter.",
            "example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Operator-facing instance name, when the operator set one.",
            "example": "Libro.fm (household)"
          },
          "is_default": {
            "type": "boolean",
            "description": "True when a bare plugin key or alias routes to this instance.",
            "example": true
          },
          "config_revision": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Instance document revision for compare-and-swap writes.",
            "example": 4
          },
          "deployment": {
            "oneOf": [
              {
                "type": "object",
                "description": "This node's deployment of the instance, when one exists.",
                "required": [
                  "deployment_id",
                  "node_id",
                  "desired",
                  "revision"
                ],
                "properties": {
                  "deployment_id": {
                    "type": "string",
                    "description": "Deployment row id.",
                    "example": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
                  },
                  "node_id": {
                    "type": "string",
                    "description": "Node the row targets.",
                    "example": "node-7f3a9c"
                  },
                  "desired": {
                    "type": "string",
                    "description": "What the row asks the node to do: `present` / `absent` from an\noperator, `placed` / `unplaced` from the scheduler.",
                    "enum": [
                      "present",
                      "absent",
                      "placed",
                      "unplaced"
                    ]
                  },
                  "revision": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Compare-and-swap revision of the desired row.",
                    "example": 3
                  },
                  "status": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Latest observation status from that node, when it reported one.",
                    "example": "healthy"
                  },
                  "detail": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Observation detail (error text, redacted).",
                    "example": ""
                  },
                  "applied_config_revision": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "format": "int64",
                    "description": "Document revision the running guest applied.",
                    "example": 5
                  },
                  "observed_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "RFC 3339 time of the observation.",
                    "example": "2026-10-28T19:07:00Z"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "placement": {
            "oneOf": [
              {
                "type": "object",
                "description": "Scheduler placement; absent when the instance is hand-managed (the\nEnabled switch applies only then).",
                "required": [
                  "replicas",
                  "constraints",
                  "revision",
                  "placed",
                  "detail",
                  "scheduled_at",
                  "updated_at"
                ],
                "properties": {
                  "replicas": {
                    "oneOf": [
                      {
                        "type": "integer",
                        "minimum": 0
                      },
                      {
                        "type": "string",
                        "enum": [
                          "all"
                        ]
                      }
                    ],
                    "description": "A replica count (0 stops every replica) or `\"all\"`."
                  },
                  "constraints": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Label constraints every chosen node must satisfy.",
                    "example": [
                      "target=linux-x64-gnu",
                      "!drain"
                    ]
                  },
                  "revision": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Compare-and-swap revision of the intent.",
                    "example": 2
                  },
                  "placed": {
                    "type": "integer",
                    "format": "int32",
                    "description": "Replicas the last scheduler pass placed.",
                    "example": 1,
                    "minimum": 0
                  },
                  "detail": {
                    "type": "string",
                    "description": "Why fewer than requested are placed; empty when satisfied.",
                    "example": ""
                  },
                  "scheduled_at": {
                    "type": "string",
                    "description": "RFC 3339 time the scheduler last changed the status.",
                    "example": "2026-10-28T19:07:00Z"
                  },
                  "updated_at": {
                    "type": "string",
                    "description": "RFC 3339 time of the last intent write.",
                    "example": "2026-10-28T19:05:00Z"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "storage_sync": {
            "oneOf": [
              {
                "type": "object",
                "description": "How outside changes at this destination are followed; absent for\nother plugins and before a destination's first sync pass.",
                "required": [
                  "feed_state",
                  "listing_in_progress",
                  "objects"
                ],
                "properties": {
                  "feed_state": {
                    "type": "string",
                    "description": "The change feed's state: `off` (no feed; listings alone), `healthy`,\n`gap` (the feed may have missed changes; a listing runs at once) or\n`failing` (reading the feed failed; listings cover it).",
                    "enum": [
                      "off",
                      "healthy",
                      "gap",
                      "failing"
                    ]
                  },
                  "feed_error": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The last feed failure.",
                    "example": "the notification queue refused the request: access denied"
                  },
                  "feed_checked_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "RFC 3339 time the feed was last read.",
                    "example": "2026-11-20T21:00:00Z"
                  },
                  "listed_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "RFC 3339 time the last listing finished.",
                    "example": "2026-11-20T18:00:00Z"
                  },
                  "next_listing_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "RFC 3339 time the next scheduled listing is due.",
                    "example": "2026-11-21T00:00:00Z"
                  },
                  "listing_in_progress": {
                    "type": "boolean",
                    "description": "True while a listing is in progress (it continues on the next\npass).",
                    "example": false
                  },
                  "listing_error": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Why the last listing failed or its removals were held back.",
                    "example": "the listing missed 412 of 1832 known files; removals were not applied"
                  },
                  "objects": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Files the destination held after the last listing or feed page.",
                    "example": 1832,
                    "minimum": 0
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "present_on": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Nodes whose deployment of the instance is `present`.",
            "example": [
              "6d1f2e3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a"
            ]
          }
        }
      },
      "description": "Per-plugin setting groups rendered by the Settings UI."
    },
    "host_cpu_cores_max": {
      "type": "number",
      "format": "double",
      "description": "Host max jail CPU in cores (2 d.p.; equals logical CPU count).",
      "example": 8.0
    },
    "jail_cpu_cores": {
      "type": [
        "number",
        "null"
      ],
      "format": "double",
      "description": "Optional global per-jail CPU ceiling in cores (from `[plugins.jail]`).",
      "example": 2.0
    },
    "output_revision": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "Revision of the `core.output` document the `output.*` values in\n`settings` were read from; send it back as `expected_output_revision`.\n`effective[\"output.revision\"]` is the revision this host has applied,\nwhich lags the document until the host's next wakeup.",
      "example": 7
    }
  }
}
```

Status `400`: A key is unknown or a value is invalid. As `text/plain`, when the body is not syntactically valid JSON.

```json
{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `401`: The caller is not signed in, or the credential is wrong.

```json
{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}
```

Schema:

```json
{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}
```

Status `403`: The caller's role does not allow this route. A write sent with a session cookie but without a matching `Origin` or `Referer` is refused.

```json
{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}
```

Schema:

```json
{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}
```

Status `409`: `output.*` keys were sent with a stale `expected_output_revision`, or another write won; the body's `current_revision` is the revision to retry against (`revision_conflict`).

```json
{
  "error": "conflict",
  "message": "Conflict",
  "status": 409
}
```

Schema:

```json
{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}
```

Status `415`: The request did not declare a JSON body.

```text
Expected request with `Content-Type: application/json`
```

Schema:

A `text/plain` body: a string.

Status `422`: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

```text
Failed to deserialize the JSON body into the target type: missing field `settings` at line 1 column 2
```

Schema:

A `text/plain` body: a string.

Status `500`: The settings could not be written.

```json
{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `504`: The request ran past the API's time budget.

```text
request timed out
```

Schema:

A `text/plain` body: a string.

## `GET /api/diagnostics/reports`

Lists the diagnostics reports this install sent, newest first, with
the IDs the collector gave them.

**Access:** The operator (token or session) only.

**Credentials:** `operatorToken` or `operatorSession`

### Responses

- `200` — The install's sent reports, newest first. Body: [`DiagnosticsReportsResponse`](/docs/server/api/schemas/index.md#diagnosticsreportsresponse) (`application/json`)
  - `reports` *array of [`DiagnosticsReportView`](/docs/server/api/schemas/index.md#diagnosticsreportview)*, **required** — Sent reports, newest first (the last 200 are kept).
- `401` — The caller is not signed in, or the credential is wrong. Body: [`ApiError`](/docs/server/api/schemas/index.md#apierror) (`application/json`)
  - `error` *string*, **required** — Stable machine slug.
  - `message` *string* — Explanation for people.
  - `status` *integer* — The HTTP status, repeated.
- `403` — The caller's role does not allow this route. Body: [`ApiError`](/docs/server/api/schemas/index.md#apierror) (`application/json`)
  - `error` *string*, **required** — Stable machine slug.
  - `message` *string* — Explanation for people.
  - `status` *integer* — The HTTP status, repeated.
- `504` — The request ran past the API's time budget. Body: string (`text/plain`)

### Example request

```console
$ curl 'http://127.0.0.1:8787/api/diagnostics/reports' \
    -H 'Authorization: Bearer <operatorToken>'
```

```powershell
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/diagnostics/reports' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
```

```python
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/diagnostics/reports",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
```

```javascript
const response = await fetch("http://127.0.0.1:8787/api/diagnostics/reports", {
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
```

```rust
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/diagnostics/reports")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);
```

### Example response

Status `200`: The install's sent reports, newest first.

```json
{
  "reports": [
    {
      "report_id": "0e9ced79-df3c-4dae-872b-2e5772b06e69",
      "trigger": "error_burst",
      "version": "0.4.0",
      "sent_at_unix_ms": 1763520000000,
      "access_code": "K7QM-3XRD-PW9T-H2CF",
      "deleted_at_unix_ms": null
    }
  ]
}
```

Schema:

```json
{
  "type": "object",
  "description": "Body of `GET /api/diagnostics/reports`.",
  "required": [
    "reports"
  ],
  "properties": {
    "reports": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One diagnostics report this install sent.",
        "required": [
          "report_id",
          "trigger",
          "version",
          "sent_at_unix_ms"
        ],
        "properties": {
          "report_id": {
            "type": "string",
            "description": "The collector's ID for the report (a UUID). The GitHub issue filed\nfor it mentions this ID; search the issues for it or give it to a\nmaintainer.",
            "example": "0e9ced79-df3c-4dae-872b-2e5772b06e69"
          },
          "trigger": {
            "type": "string",
            "description": "Why it was sent: `crash`, `error_burst`, `slow_burst`, `job_failed`,\n`cli_error`, `cli_manual`, ….",
            "example": "error_burst"
          },
          "version": {
            "type": "string",
            "description": "The Bookclerk version that sent it.",
            "example": "0.4.0"
          },
          "sent_at_unix_ms": {
            "type": "integer",
            "format": "int64",
            "description": "When the collector accepted it, Unix milliseconds.",
            "example": 1763520000000,
            "minimum": 0
          },
          "access_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "The code that reads the report back or deletes it, in groups of\nfour, or null when the collector issued none. With the ID it also\nopens the collector's public lookup page.",
            "example": "K7QM-3XRD-PW9T-H2CF"
          },
          "deleted_at_unix_ms": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "When this install deleted the collector's stored copy, Unix\nmilliseconds, or null while it is stored.",
            "example": null,
            "minimum": 0
          }
        }
      },
      "description": "Sent reports, newest first (the last 200 are kept)."
    }
  }
}
```

Status `401`: The caller is not signed in, or the credential is wrong.

```json
{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}
```

Schema:

```json
{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}
```

Status `403`: The caller's role does not allow this route.

```json
{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}
```

Schema:

```json
{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}
```

Status `504`: The request ran past the API's time budget.

```text
request timed out
```

Schema:

A `text/plain` body: a string.

## `GET /api/diagnostics/reports/{id}`

Reads a sent report back from the collector with its access code: the
stored report (redacted, as sent), the GitHub issues tracking it and the
fix, if one is recorded.

**Access:** The operator (token or session) only.

**Credentials:** `operatorToken` or `operatorSession`

### Parameters

- `id` (path) *string*, **required** — The report's ID, from `GET /api/diagnostics/reports`.

### Responses

- `200` — The report as the collector holds it. Body: [`DiagnosticsReportLookup`](/docs/server/api/schemas/index.md#diagnosticsreportlookup) (`application/json`)
  - `report_id` *string*, **required** — The report's ID.
  - `received_at_unix_ms` *integer (int64)*, **required** — When the collector received it, Unix milliseconds. At least 0.
  - `deleted_at_unix_ms` *integer (int64) or null* — When its stored copy was deleted, Unix milliseconds, or null. At least 0.
  - `report` *[`StoredReportView`](/docs/server/api/schemas/index.md#storedreportview) or null* — The stored report, or null once deleted.
  - `issues` *array of [`ReportIssueView`](/docs/server/api/schemas/index.md#reportissueview)*, **required** — Issues tracking it, the tracking issue first.
  - `fix` *[`ReportFixView`](/docs/server/api/schemas/index.md#reportfixview) or null* — The tracking issue's fix, or null.
- `400` — The ID is not a version-4 UUID (`invalid_report_id`). Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `401` — The caller is not signed in, or the credential is wrong. Body: [`ApiError`](/docs/server/api/schemas/index.md#apierror) (`application/json`)
  - `error` *string*, **required** — Stable machine slug.
  - `message` *string* — Explanation for people.
  - `status` *integer* — The HTTP status, repeated.
- `403` — The caller's role does not allow this route. Body: [`ApiError`](/docs/server/api/schemas/index.md#apierror) (`application/json`)
  - `error` *string*, **required** — Stable machine slug.
  - `message` *string* — Explanation for people.
  - `status` *integer* — The HTTP status, repeated.
- `404` — This install has not sent that report (`report_unknown`), has no code for it (`no_access_code`), or the collector no longer has it (`report_not_found`). Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `429` — Too many lookups of this report lately; try again in a minute (`rate_limited`). Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `502` — The collector could not be reached or answered badly (`collector_error`). Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `503` — No collector is configured, or it offers no lookups (`lookup_unavailable`). Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `504` — The request ran past the API's time budget. Body: string (`text/plain`)

### Example request

```console
$ curl 'http://127.0.0.1:8787/api/diagnostics/reports/<id>' \
    -H 'Authorization: Bearer <operatorToken>'
```

```powershell
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/diagnostics/reports/<id>' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
```

```python
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/diagnostics/reports/<id>",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
```

```javascript
const response = await fetch("http://127.0.0.1:8787/api/diagnostics/reports/<id>", {
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
```

```rust
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/diagnostics/reports/<id>")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);
```

### Example response

Status `200`: The report as the collector holds it.

```json
{
  "report_id": "3f2a9c4e-7b1d-4e8a-9c0f-1a2b3c4d5e6f",
  "received_at_unix_ms": 1763520000000,
  "deleted_at_unix_ms": null,
  "report": {
    "version": "0.9.0",
    "trigger": "error_burst",
    "os": "linux",
    "arch": "x86_64",
    "distro": "debian",
    "events": [
      {
        "ts_unix_ms": 1763519999000,
        "level": "ERROR",
        "target": "bookclerk_library::scan",
        "message": "scan failed",
        "fields": []
      }
    ]
  },
  "issues": [
    {
      "number": 1204,
      "title": "Scan fails with timeout",
      "state": "open",
      "url": "https://github.com/bookclerk/bookclerk/issues/1204"
    }
  ],
  "fix": {
    "pr_number": 1210,
    "pr_url": "https://github.com/bookclerk/bookclerk/pull/1210",
    "fixed_in": "0.9.1"
  }
}
```

Schema:

```json
{
  "type": "object",
  "description": "Body of `GET /api/diagnostics/reports/{id}`: the report as the collector\nholds it, and what became of it.",
  "required": [
    "report_id",
    "received_at_unix_ms",
    "issues"
  ],
  "properties": {
    "report_id": {
      "type": "string",
      "description": "The report's ID.",
      "example": "3f2a9c4e-7b1d-4e8a-9c0f-1a2b3c4d5e6f"
    },
    "received_at_unix_ms": {
      "type": "integer",
      "format": "int64",
      "description": "When the collector received it, Unix milliseconds.",
      "example": 1763520000000,
      "minimum": 0
    },
    "deleted_at_unix_ms": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "When its stored copy was deleted, Unix milliseconds, or null.",
      "example": null,
      "minimum": 0
    },
    "report": {
      "oneOf": [
        {
          "type": "object",
          "description": "The stored report, or null once deleted.",
          "required": [
            "version",
            "trigger",
            "os",
            "arch",
            "distro",
            "events"
          ],
          "properties": {
            "version": {
              "type": "string",
              "description": "The Bookclerk version that sent it.",
              "example": "0.9.0"
            },
            "trigger": {
              "type": "string",
              "description": "Why it was sent.",
              "example": "error_burst"
            },
            "os": {
              "type": "string",
              "description": "The sender's operating system.",
              "example": "linux"
            },
            "arch": {
              "type": "string",
              "description": "The sender's CPU architecture.",
              "example": "x86_64"
            },
            "distro": {
              "type": "string",
              "description": "The sender's Linux distribution, or empty.",
              "example": "debian"
            },
            "events": {
              "type": "array",
              "items": {
                "type": "object",
                "description": "One logged event in a stored report.",
                "required": [
                  "ts_unix_ms",
                  "level",
                  "target",
                  "message",
                  "fields"
                ],
                "properties": {
                  "ts_unix_ms": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When it happened, Unix milliseconds, or `0` when the report had none.",
                    "example": 1763519999000,
                    "minimum": 0
                  },
                  "level": {
                    "type": "string",
                    "description": "Its severity.",
                    "enum": [
                      "ERROR",
                      "WARN",
                      "INFO",
                      "DEBUG",
                      "TRACE"
                    ]
                  },
                  "target": {
                    "type": "string",
                    "description": "Where it was logged (the tracing target).",
                    "example": "bookclerk_library::scan"
                  },
                  "message": {
                    "type": "string",
                    "description": "The message, redacted before the report was sent.",
                    "example": "scan failed"
                  },
                  "fields": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "description": "One field recorded with an event.",
                      "required": [
                        "name",
                        "value"
                      ],
                      "properties": {
                        "name": {
                          "type": "string",
                          "description": "The field's name.",
                          "example": "attempt"
                        },
                        "value": {
                          "type": "string",
                          "description": "Its value, redacted before the report was sent.",
                          "example": "2"
                        }
                      }
                    },
                    "description": "Fields recorded with it."
                  }
                }
              },
              "description": "Its events, oldest first."
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "issues": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A GitHub issue tracking the report.",
        "required": [
          "number",
          "title",
          "state",
          "url"
        ],
        "properties": {
          "number": {
            "type": "integer",
            "format": "int64",
            "description": "The issue number.",
            "example": 1204,
            "minimum": 0
          },
          "title": {
            "type": "string",
            "description": "Its title.",
            "example": "Scan fails with timeout"
          },
          "state": {
            "type": "string",
            "description": "Whether it is open.",
            "enum": [
              "open",
              "closed"
            ]
          },
          "url": {
            "type": "string",
            "description": "Its page (always `https://`).",
            "example": "https://github.com/bookclerk/bookclerk/issues/1204"
          }
        }
      },
      "description": "Issues tracking it, the tracking issue first."
    },
    "fix": {
      "oneOf": [
        {
          "type": "object",
          "description": "The tracking issue's fix, or null.",
          "properties": {
            "pr_number": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int64",
              "description": "The pull request that fixed it, when known.",
              "example": 1210,
              "minimum": 0
            },
            "pr_url": {
              "type": [
                "string",
                "null"
              ],
              "description": "That pull request's page (`https://`), when known.",
              "example": "https://github.com/bookclerk/bookclerk/pull/1210"
            },
            "fixed_in": {
              "type": [
                "string",
                "null"
              ],
              "description": "The first release with the fix, when one has shipped.",
              "example": "0.9.1"
            }
          }
        },
        {
          "type": "null"
        }
      ]
    }
  }
}
```

Status `400`: The ID is not a version-4 UUID (`invalid_report_id`).

```json
{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `401`: The caller is not signed in, or the credential is wrong.

```json
{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}
```

Schema:

```json
{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}
```

Status `403`: The caller's role does not allow this route.

```json
{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}
```

Schema:

```json
{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}
```

Status `404`: This install has not sent that report (`report_unknown`), has no code for it (`no_access_code`), or the collector no longer has it (`report_not_found`).

```json
{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `429`: Too many lookups of this report lately; try again in a minute (`rate_limited`).

```json
{
  "error": "too_many_requests",
  "message": "Too many requests. Try again shortly.",
  "status": 429
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `502`: The collector could not be reached or answered badly (`collector_error`).

```json
{
  "error": "bad_gateway",
  "message": "An upstream service failed.",
  "status": 502
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `503`: No collector is configured, or it offers no lookups (`lookup_unavailable`).

```json
{
  "error": "service_unavailable",
  "message": "The Bookclerk daemon is not ready to handle this request.",
  "status": 503
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `504`: The request ran past the API's time budget.

```text
request timed out
```

Schema:

A `text/plain` body: a string.

## `DELETE /api/diagnostics/reports/{id}`

Deletes the collector's stored copy of a sent report. The collector keeps
its one-line index entry and issue links, so the report still counts;
the install's history notes the deletion.

**Access:** The operator (token or session) only.

**Credentials:** `operatorToken` or `operatorSession`

### Parameters

- `id` (path) *string*, **required** — The report's ID, from `GET /api/diagnostics/reports`.

### Responses

- `200` — The stored copy is gone (deleting again answers the same). Body: [`DiagnosticsReportDeleted`](/docs/server/api/schemas/index.md#diagnosticsreportdeleted) (`application/json`)
  - `report_id` *string*, **required** — The report's ID.
  - `deleted_at_unix_ms` *integer (int64)*, **required** — When its stored copy was deleted, Unix milliseconds. At least 0.
- `400` — The ID is not a version-4 UUID (`invalid_report_id`). Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `401` — The caller is not signed in, or the credential is wrong. Body: [`ApiError`](/docs/server/api/schemas/index.md#apierror) (`application/json`)
  - `error` *string*, **required** — Stable machine slug.
  - `message` *string* — Explanation for people.
  - `status` *integer* — The HTTP status, repeated.
- `403` — The caller's role does not allow this route. A write sent with a session cookie but without a matching `Origin` or `Referer` is refused. Body: [`ApiError`](/docs/server/api/schemas/index.md#apierror) (`application/json`)
  - `error` *string*, **required** — Stable machine slug.
  - `message` *string* — Explanation for people.
  - `status` *integer* — The HTTP status, repeated.
- `404` — This install has not sent that report (`report_unknown`), has no code for it (`no_access_code`), or the collector no longer has it (`report_not_found`). Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `429` — Too many attempts for this report lately; try again in a minute (`rate_limited`). Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `502` — The collector could not be reached, answered badly or could not delete the copy (`collector_error`). Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `503` — No collector is configured, or it offers no lookups (`lookup_unavailable`). Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `504` — The request ran past the API's time budget. Body: string (`text/plain`)

### Example request

```console
$ curl 'http://127.0.0.1:8787/api/diagnostics/reports/<id>' \
    -X DELETE \
    -H 'Authorization: Bearer <operatorToken>'
```

```powershell
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/diagnostics/reports/<id>' `
    -Method Delete `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
```

```python
import requests

response = requests.delete(
    "http://127.0.0.1:8787/api/diagnostics/reports/<id>",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
```

```javascript
const response = await fetch("http://127.0.0.1:8787/api/diagnostics/reports/<id>", {
  method: "DELETE",
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
```

```rust
let client = reqwest::Client::new();
let response = client
    .delete("http://127.0.0.1:8787/api/diagnostics/reports/<id>")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);
```

### Example response

Status `200`: The stored copy is gone (deleting again answers the same).

```json
{
  "report_id": "3f2a9c4e-7b1d-4e8a-9c0f-1a2b3c4d5e6f",
  "deleted_at_unix_ms": 1763600000000
}
```

Schema:

```json
{
  "type": "object",
  "description": "Body of `DELETE /api/diagnostics/reports/{id}`.",
  "required": [
    "report_id",
    "deleted_at_unix_ms"
  ],
  "properties": {
    "report_id": {
      "type": "string",
      "description": "The report's ID.",
      "example": "3f2a9c4e-7b1d-4e8a-9c0f-1a2b3c4d5e6f"
    },
    "deleted_at_unix_ms": {
      "type": "integer",
      "format": "int64",
      "description": "When its stored copy was deleted, Unix milliseconds.",
      "example": 1763600000000,
      "minimum": 0
    }
  }
}
```

Status `400`: The ID is not a version-4 UUID (`invalid_report_id`).

```json
{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `401`: The caller is not signed in, or the credential is wrong.

```json
{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}
```

Schema:

```json
{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}
```

Status `403`: The caller's role does not allow this route. A write sent with a session cookie but without a matching `Origin` or `Referer` is refused.

```json
{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}
```

Schema:

```json
{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}
```

Status `404`: This install has not sent that report (`report_unknown`), has no code for it (`no_access_code`), or the collector no longer has it (`report_not_found`).

```json
{
  "error": "not_found",
  "message": "That page or resource was not found.",
  "status": 404
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `429`: Too many attempts for this report lately; try again in a minute (`rate_limited`).

```json
{
  "error": "too_many_requests",
  "message": "Too many requests. Try again shortly.",
  "status": 429
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `502`: The collector could not be reached, answered badly or could not delete the copy (`collector_error`).

```json
{
  "error": "bad_gateway",
  "message": "An upstream service failed.",
  "status": 502
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `503`: No collector is configured, or it offers no lookups (`lookup_unavailable`).

```json
{
  "error": "service_unavailable",
  "message": "The Bookclerk daemon is not ready to handle this request.",
  "status": 503
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `504`: The request ran past the API's time budget.

```text
request timed out
```

Schema:

A `text/plain` body: a string.

## `POST /api/database/migrate`

Copies library rows between database plugins and optionally switches `[database].plugin`.

**Access:** The operator (token or session) only.

**Credentials:** `operatorToken` or `operatorSession`

### Request body

`application/json`: [`DatabaseMigrateRequest`](/docs/server/api/schemas/index.md#databasemigraterequest)

- `from` *string or null* — Source plugin id. Defaults to the active `[database].plugin` before reload.
- `to` *string*, **required** — Destination database plugin id to copy into.
- `dry_run` *boolean* — When true, count rows without writing.
- `force` *boolean* — When true, overwrite a destination that is not empty.
- `apply` *boolean* — Update `[database].plugin` in config.toml after a successful copy.

### Responses

- `200` — The rows were copied. Body: [`ActionResponse`](/docs/server/api/schemas/index.md#actionresponse) (`application/json`)
  - `ok` *boolean*, **required** — True when the action was accepted or completed.
  - `message` *string*, **required** — Operator-facing status text.
  - `job_id` *string*, **required** — Queued job id, or empty when the action is synchronous.
  - `error` *string or null* — Machine slug when admission failed (`conflict`, `queue_full`).
- `400` — The target is invalid. As `text/plain`, when the body is not syntactically valid JSON. Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`); string (`text/plain`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `401` — The caller is not signed in, or the credential is wrong. Body: [`ApiError`](/docs/server/api/schemas/index.md#apierror) (`application/json`)
  - `error` *string*, **required** — Stable machine slug.
  - `message` *string* — Explanation for people.
  - `status` *integer* — The HTTP status, repeated.
- `403` — The caller's role does not allow this route. A write sent with a session cookie but without a matching `Origin` or `Referer` is refused. Body: [`ApiError`](/docs/server/api/schemas/index.md#apierror) (`application/json`)
  - `error` *string*, **required** — Stable machine slug.
  - `message` *string* — Explanation for people.
  - `status` *integer* — The HTTP status, repeated.
- `409` — The migration target matches more than one database plugin. Body: [`ApiError`](/docs/server/api/schemas/index.md#apierror) (`application/json`)
  - `error` *string*, **required** — Stable machine slug.
  - `message` *string* — Explanation for people.
  - `status` *integer* — The HTTP status, repeated.
- `415` — The request did not declare a JSON body. Body: string (`text/plain`)
- `422` — The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (`text/plain`)
- `500` — The copy failed. Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `504` — The request ran past the API's time budget. Body: string (`text/plain`)

### Example request

```console
$ curl 'http://127.0.0.1:8787/api/database/migrate' \
    -X POST \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{"to": "postgres"}'
```

```powershell
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/database/migrate' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{"to": "postgres"}'
```

```python
import requests

response = requests.post(
    "http://127.0.0.1:8787/api/database/migrate",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={"to": "postgres"},
)
print(response.status_code, response.text)
```

```javascript
const response = await fetch("http://127.0.0.1:8787/api/database/migrate", {
  method: "POST",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"to": "postgres"}),
});
console.log(response.status, await response.text());
```

```rust
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/api/database/migrate")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({"to": "postgres"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);
```

### Example response

Status `200`: The rows were copied.

```json
{
  "job_id": "",
  "message": "copied 1284 row(s) from `sqlite` to `postgres`; updated [database].plugin, wrote /home/bookclerk/BookclerkFiles/config.toml, and reloaded library connection",
  "ok": true
}
```

Schema:

```json
{
  "type": "object",
  "description": "Generic mutation result with success flag, message, and optional job id.",
  "required": [
    "ok",
    "message",
    "job_id"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "description": "True when the action was accepted or completed.",
      "example": true
    },
    "message": {
      "type": "string",
      "description": "Operator-facing status text.",
      "example": "scan queued"
    },
    "job_id": {
      "type": "string",
      "description": "Queued job id, or empty when the action is synchronous.",
      "example": "scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f"
    },
    "error": {
      "type": [
        "string",
        "null"
      ],
      "description": "Machine slug when admission failed (`conflict`, `queue_full`).",
      "example": "queue_full"
    }
  }
}
```

Status `400`: The target is invalid. As `text/plain`, when the body is not syntactically valid JSON.

```json
{
  "error": "bad_request",
  "message": "The request could not be understood.",
  "status": 400
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `401`: The caller is not signed in, or the credential is wrong.

```json
{
  "error": "unauthorized",
  "message": "Operator authentication is required. Sign in with your operator token.",
  "status": 401
}
```

Schema:

```json
{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}
```

Status `403`: The caller's role does not allow this route. A write sent with a session cookie but without a matching `Origin` or `Referer` is refused.

```json
{
  "error": "forbidden",
  "message": "You do not have access to this resource.",
  "status": 403
}
```

Schema:

```json
{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}
```

Status `409`: The migration target matches more than one database plugin.

```json
{
  "error": "conflict",
  "message": "Conflict",
  "status": 409
}
```

Schema:

```json
{
  "type": "object",
  "description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Stable machine slug.",
      "examples": [
        "not_found"
      ]
    },
    "message": {
      "type": "string",
      "description": "Explanation for people.",
      "examples": [
        "That page or resource was not found."
      ]
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status, repeated.",
      "examples": [
        404
      ]
    }
  }
}
```

Status `415`: The request did not declare a JSON body.

```text
Expected request with `Content-Type: application/json`
```

Schema:

A `text/plain` body: a string.

Status `422`: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

```text
Failed to deserialize the JSON body into the target type: missing field `to` at line 1 column 2
```

Schema:

A `text/plain` body: a string.

Status `500`: The copy failed.

```json
{
  "error": "internal_error",
  "message": "Something went wrong on the Bookclerk daemon.",
  "status": 500
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `504`: The request ran past the API's time budget.

```text
request timed out
```

Schema:

A `text/plain` body: a string.

## `GET /api/preferences`

Loads preferences for the caller with a 3s timeout, creating defaults when missing.

**Access:** The operator, or any library session, including a library card (refused with 403 `transport_insecure` off loopback without TLS, or `clerk_sign_in_unavailable` where remote installs are not served).

**Credentials:** `operatorToken` or `operatorSession` or `portalSession` or `clerkToken`

### Responses

- `200` — The caller's preferences. Body: [`PreferencesResponse`](/docs/server/api/schemas/index.md#preferencesresponse) (`application/json`)
  - `default_view` *string*, **required** — Landing view id (`library`, `discover`, …) after normalization.
  - `disabled_shelves` *array of string*, **required** — Lowercased Discover shelf ids the user has hidden.
  - `discover_sort` *string*, **required** — Discover sort key (`relevance`, `popularity`, …).
  - `discover_sort_dir` *string*, **required** — Discover sort direction (`asc` or `desc`).
  - `discover_language` *string or null* — `null` = use browser language on the client.
  - `discover_excluded_sources` *array of string*, **required** — Lowercased store ids hidden from Discover results.
  - `theme` *string*, **required** — Appearance preference (`system`, `light`, or `dark`).
- `401` — No signed-in caller. Body: string (`text/plain`)
- `403` — A library card sent over plain HTTP from another machine gets `transport_insecure`. A library card sent where the node API is not mounted gets `clerk_sign_in_unavailable`. Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `500` — The request could not be read or written. Body: string (`text/plain`)
- `503` — The sign-in could not be checked because the library did not answer in time (`session_check_unavailable`). The response carries `Retry-After`; ask again rather than treating the caller as signed out. Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `504` — The preferences row did not load in time. Body: string (`text/plain`)

### Example request

```console
$ curl 'http://127.0.0.1:8787/api/preferences' \
    -H 'Authorization: Bearer <operatorToken>'
```

```powershell
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/preferences' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
```

```python
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/preferences",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
```

```javascript
const response = await fetch("http://127.0.0.1:8787/api/preferences", {
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
```

```rust
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/api/preferences")
    .header("Authorization", "Bearer <operatorToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);
```

### Example response

Status `200`: The caller's preferences.

```json
{
  "default_view": "library",
  "disabled_shelves": [
    "chirp_deals",
    "from_store"
  ],
  "discover_sort": "relevance",
  "discover_sort_dir": "desc",
  "discover_language": "en",
  "discover_excluded_sources": [
    "chirp"
  ],
  "theme": "system"
}
```

Schema:

```json
{
  "type": "object",
  "description": "Normalized Discover/library preferences for the authenticated subject.",
  "required": [
    "default_view",
    "disabled_shelves",
    "discover_sort",
    "discover_sort_dir",
    "discover_excluded_sources",
    "theme"
  ],
  "properties": {
    "default_view": {
      "type": "string",
      "description": "Landing view id (`library`, `discover`, …) after normalization.",
      "example": "library"
    },
    "disabled_shelves": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Lowercased Discover shelf ids the user has hidden.",
      "example": [
        "chirp_deals",
        "from_store"
      ]
    },
    "discover_sort": {
      "type": "string",
      "description": "Discover sort key (`relevance`, `popularity`, …).",
      "example": "relevance"
    },
    "discover_sort_dir": {
      "type": "string",
      "description": "Discover sort direction (`asc` or `desc`).",
      "example": "desc"
    },
    "discover_language": {
      "type": [
        "string",
        "null"
      ],
      "description": "`null` = use browser language on the client.",
      "example": "en"
    },
    "discover_excluded_sources": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Lowercased store ids hidden from Discover results.",
      "example": [
        "chirp"
      ]
    },
    "theme": {
      "type": "string",
      "description": "Appearance preference (`system`, `light`, or `dark`).",
      "example": "system"
    }
  }
}
```

Status `401`: No signed-in caller.

```text
Unauthorized
```

Schema:

A `text/plain` body: a string.

Status `403`: A library card sent over plain HTTP from another machine gets `transport_insecure`. A library card sent where the node API is not mounted gets `clerk_sign_in_unavailable`.

```json
{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `500`: The request could not be read or written.

```text
ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection
```

Schema:

A `text/plain` body: a string.

Status `503`: The sign-in could not be checked because the library did not answer in time (`session_check_unavailable`). The response carries `Retry-After`; ask again rather than treating the caller as signed out.

```json
{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `504`: The preferences row did not load in time.

```text
preferences lookup timed out
```

Schema:

A `text/plain` body: a string.

## `PATCH /api/preferences`

Merges a preferences PATCH onto the caller’s stored row and writes it back.

**Access:** The operator, or any library session, including a library card (refused with 403 `transport_insecure` off loopback without TLS, or `clerk_sign_in_unavailable` where remote installs are not served).

**Credentials:** `operatorToken` or `operatorSession` or `portalSession` or `clerkToken`

### Request body

`application/json`: [`PatchPreferencesBody`](/docs/server/api/schemas/index.md#patchpreferencesbody)

- `default_view` *string or null* — Replacement landing view when set.
- `disabled_shelves` *array of string or null* — Replacement hidden-shelf list when set.
- `discover_sort` *string or null* — Replacement Discover sort key when set.
- `discover_sort_dir` *string or null* — Replacement Discover sort direction when set.
- `discover_language` *string or null* — Present + value sets language; present + `null` clears to browser default; omitted leaves unchanged.
- `discover_excluded_sources` *array of string or null* — Replacement excluded-store list when set.
- `theme` *string or null* — Replacement appearance preference when set (`system`, `light`, `dark`).

### Responses

- `200` — The preferences after the change. Body: [`PreferencesResponse`](/docs/server/api/schemas/index.md#preferencesresponse) (`application/json`)
  - `default_view` *string*, **required** — Landing view id (`library`, `discover`, …) after normalization.
  - `disabled_shelves` *array of string*, **required** — Lowercased Discover shelf ids the user has hidden.
  - `discover_sort` *string*, **required** — Discover sort key (`relevance`, `popularity`, …).
  - `discover_sort_dir` *string*, **required** — Discover sort direction (`asc` or `desc`).
  - `discover_language` *string or null* — `null` = use browser language on the client.
  - `discover_excluded_sources` *array of string*, **required** — Lowercased store ids hidden from Discover results.
  - `theme` *string*, **required** — Appearance preference (`system`, `light`, or `dark`).
- `400` — The body is not syntactically valid JSON. Body: string (`text/plain`)
- `401` — No signed-in caller. Body: string (`text/plain`)
- `403` — A library card sent over plain HTTP from another machine gets `transport_insecure`. A library card sent where the node API is not mounted gets `clerk_sign_in_unavailable`. A write sent with a session cookie but without a matching `Origin` or `Referer` is refused. Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `415` — The request did not declare a JSON body. Body: string (`text/plain`)
- `422` — The JSON does not fit the patch (a wrong type or an unknown shape). Body: string (`text/plain`)
- `500` — The request could not be read or written. Body: string (`text/plain`)
- `503` — The sign-in could not be checked because the library did not answer in time (`session_check_unavailable`). The response carries `Retry-After`; ask again rather than treating the caller as signed out. Body: [`ErrorJson`](/docs/server/api/schemas/index.md#errorjson) (`application/json`)
  - `error` *string*, **required** — Machine slug (same as [`ErrorBody::code`]).
  - `message` *string*, **required** — Operator-facing explanation.
  - `status` *integer (int32)*, **required** — Numeric HTTP status (duplicates the response status for clients). At least 0.
- `504` — The preferences row did not load or save in time. Body: string (`text/plain`)

### Example request

```console
$ curl 'http://127.0.0.1:8787/api/preferences' \
    -X PATCH \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{}'
```

```powershell
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/preferences' `
    -Method Patch `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{}'
```

```python
import requests

response = requests.patch(
    "http://127.0.0.1:8787/api/preferences",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={},
)
print(response.status_code, response.text)
```

```javascript
const response = await fetch("http://127.0.0.1:8787/api/preferences", {
  method: "PATCH",
  headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());
```

```rust
let client = reqwest::Client::new();
let response = client
    .patch("http://127.0.0.1:8787/api/preferences")
    .header("Authorization", "Bearer <operatorToken>")
    .json(&serde_json::json!({}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);
```

### Example response

Status `200`: The preferences after the change.

```json
{
  "default_view": "library",
  "disabled_shelves": [
    "chirp_deals",
    "from_store"
  ],
  "discover_sort": "relevance",
  "discover_sort_dir": "desc",
  "discover_language": "en",
  "discover_excluded_sources": [
    "chirp"
  ],
  "theme": "system"
}
```

Schema:

```json
{
  "type": "object",
  "description": "Normalized Discover/library preferences for the authenticated subject.",
  "required": [
    "default_view",
    "disabled_shelves",
    "discover_sort",
    "discover_sort_dir",
    "discover_excluded_sources",
    "theme"
  ],
  "properties": {
    "default_view": {
      "type": "string",
      "description": "Landing view id (`library`, `discover`, …) after normalization.",
      "example": "library"
    },
    "disabled_shelves": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Lowercased Discover shelf ids the user has hidden.",
      "example": [
        "chirp_deals",
        "from_store"
      ]
    },
    "discover_sort": {
      "type": "string",
      "description": "Discover sort key (`relevance`, `popularity`, …).",
      "example": "relevance"
    },
    "discover_sort_dir": {
      "type": "string",
      "description": "Discover sort direction (`asc` or `desc`).",
      "example": "desc"
    },
    "discover_language": {
      "type": [
        "string",
        "null"
      ],
      "description": "`null` = use browser language on the client.",
      "example": "en"
    },
    "discover_excluded_sources": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Lowercased store ids hidden from Discover results.",
      "example": [
        "chirp"
      ]
    },
    "theme": {
      "type": "string",
      "description": "Appearance preference (`system`, `light`, or `dark`).",
      "example": "system"
    }
  }
}
```

Status `400`: The body is not syntactically valid JSON.

```text
Failed to parse the request body as JSON: expected value at line 1 column 10
```

Schema:

A `text/plain` body: a string.

Status `401`: No signed-in caller.

```text
Unauthorized
```

Schema:

A `text/plain` body: a string.

Status `403`: A library card sent over plain HTTP from another machine gets `transport_insecure`. A library card sent where the node API is not mounted gets `clerk_sign_in_unavailable`. A write sent with a session cookie but without a matching `Origin` or `Referer` is refused.

```json
{
  "error": "clerk_sign_in_unavailable",
  "message": "This library does not accept clerks on this address.",
  "status": 403
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `415`: The request did not declare a JSON body.

```text
Expected request with `Content-Type: application/json`
```

Schema:

A `text/plain` body: a string.

Status `422`: The JSON does not fit the patch (a wrong type or an unknown shape).

```text
Failed to deserialize the JSON body into the target type: theme: invalid type: integer `3`, expected a string at line 1 column 11
```

Schema:

A `text/plain` body: a string.

Status `500`: The request could not be read or written.

```text
ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection
```

Schema:

A `text/plain` body: a string.

Status `503`: The sign-in could not be checked because the library did not answer in time (`session_check_unavailable`). The response carries `Retry-After`; ask again rather than treating the caller as signed out.

```json
{
  "error": "session_check_unavailable",
  "message": "Your sign-in could not be checked yet. Try again in a moment.",
  "status": 503
}
```

Schema:

```json
{
  "type": "object",
  "description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
  "required": [
    "error",
    "message",
    "status"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "Machine slug (same as [`ErrorBody::code`]).",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "description": "Operator-facing explanation.",
      "example": "That page or resource was not found."
    },
    "status": {
      "type": "integer",
      "format": "int32",
      "description": "Numeric HTTP status (duplicates the response status for clients).",
      "example": 404,
      "minimum": 0
    }
  }
}
```

Status `504`: The preferences row did not load or save in time.

```text
preferences update timed out
```

Schema:

A `text/plain` body: a string.
