Settings

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Daemon settings and user preferences.

Back to the web API reference.

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

  • 200The settings. Body: SettingsResponse (application/json)6 fields
    • settingsmap of string to stringrequiredValues as written in config.toml (and env overlays), plus output.* from the core.output database document.
    • effectivemap of string to stringrequiredRuntime-effective values after the last successful reload (auth, plugins).
    • pluginsarray of PluginSettingsGrouprequiredPer-plugin setting groups rendered by the Settings UI.
    • host_cpu_cores_maxnumber (double)requiredHost max jail CPU in cores (2 d.p.; equals logical CPU count).
    • jail_cpu_coresnumber (double) or nullOptional global per-jail CPU ceiling in cores (from [plugins.jail]).
    • output_revisioninteger (int64) or nullRevision 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.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The settings could not be read. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/settings' \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/settings' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/settings",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/settings", {
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
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.

{
  "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:

{
  "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.

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

Schema:

{
  "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.

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

Schema:

{
  "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.

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

Schema:

{
  "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.

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

  • settingsarray of SettingsUpdaterequiredKey/value pairs to validate, persist, and reload.
  • expected_output_revisioninteger (int64) or nullcore.output document revision the client read (output_revision in GET /api/settings). When set and stale, an output.* update is rejected with 409.

Responses

  • 200The settings after the change. Body: SettingsResponse (application/json)6 fields
    • settingsmap of string to stringrequiredValues as written in config.toml (and env overlays), plus output.* from the core.output database document.
    • effectivemap of string to stringrequiredRuntime-effective values after the last successful reload (auth, plugins).
    • pluginsarray of PluginSettingsGrouprequiredPer-plugin setting groups rendered by the Settings UI.
    • host_cpu_cores_maxnumber (double)requiredHost max jail CPU in cores (2 d.p.; equals logical CPU count).
    • jail_cpu_coresnumber (double) or nullOptional global per-jail CPU ceiling in cores (from [plugins.jail]).
    • output_revisioninteger (int64) or nullRevision 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.
  • 400A key is unknown or a value is invalid. As text/plain, when the body is not syntactically valid JSON. Body: ErrorJson (application/json); string (text/plain)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The 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 (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 409output.* 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 (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The settings could not be written. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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"}]}'
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"}]}'
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)
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());
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.

{
  "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:

{
  "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.

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

Schema:

{
  "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.

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

Schema:

{
  "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.

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

Schema:

{
  "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).

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

Schema:

{
  "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.

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.

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.

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

Schema:

{
  "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.

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

  • 200The install's sent reports, newest first. Body: DiagnosticsReportsResponse (application/json)1 field
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/diagnostics/reports' \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/diagnostics/reports' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/diagnostics/reports",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/diagnostics/reports", {
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
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.

{
  "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:

{
  "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.

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

Schema:

{
  "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.

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

Schema:

{
  "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.

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

  • idpathstringrequiredThe report's ID, from GET /api/diagnostics/reports.

Responses

  • 200The report as the collector holds it. Body: DiagnosticsReportLookup (application/json)6 fields
    • report_idstringrequiredThe report's ID.
    • received_at_unix_msinteger (int64)requiredWhen the collector received it, Unix milliseconds. At least 0.
    • deleted_at_unix_msinteger (int64) or nullWhen its stored copy was deleted, Unix milliseconds, or null. At least 0.
    • reportStoredReportView or nullThe stored report, or null once deleted.
    • issuesarray of ReportIssueViewrequiredIssues tracking it, the tracking issue first.
    • fixReportFixView or nullThe tracking issue's fix, or null.
  • 400The ID is not a version-4 UUID (invalid_report_id). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404This 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 (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 429Too many lookups of this report lately; try again in a minute (rate_limited). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 502The collector could not be reached or answered badly (collector_error). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503No collector is configured, or it offers no lookups (lookup_unavailable). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/diagnostics/reports/<id>' \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/diagnostics/reports/<id>' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
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)
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());
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.

{
  "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:

{
  "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).

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

Schema:

{
  "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.

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

Schema:

{
  "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.

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

Schema:

{
  "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).

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

Schema:

{
  "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).

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

Schema:

{
  "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).

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

Schema:

{
  "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).

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

Schema:

{
  "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.

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

  • idpathstringrequiredThe report's ID, from GET /api/diagnostics/reports.

Responses

  • 200The stored copy is gone (deleting again answers the same). Body: DiagnosticsReportDeleted (application/json)2 fields
    • report_idstringrequiredThe report's ID.
    • deleted_at_unix_msinteger (int64)requiredWhen its stored copy was deleted, Unix milliseconds. At least 0.
  • 400The ID is not a version-4 UUID (invalid_report_id). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The 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 (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404This 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 (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 429Too many attempts for this report lately; try again in a minute (rate_limited). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 502The collector could not be reached, answered badly or could not delete the copy (collector_error). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503No collector is configured, or it offers no lookups (lookup_unavailable). Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/diagnostics/reports/<id>' \
    -X DELETE \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/diagnostics/reports/<id>' `
    -Method Delete `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
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)
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());
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).

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

Schema:

{
  "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).

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

Schema:

{
  "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.

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

Schema:

{
  "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.

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

Schema:

{
  "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).

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

Schema:

{
  "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).

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

Schema:

{
  "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).

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

Schema:

{
  "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).

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

Schema:

{
  "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.

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

  • fromstring or nullSource plugin id. Defaults to the active [database].plugin before reload.
  • tostringrequiredDestination database plugin id to copy into.
  • dry_runbooleanWhen true, count rows without writing.
  • forcebooleanWhen true, overwrite a destination that is not empty.
  • applybooleanUpdate [database].plugin in config.toml after a successful copy.

Responses

  • 200The rows were copied. Body: ActionResponse (application/json)4 fields
    • okbooleanrequiredTrue when the action was accepted or completed.
    • messagestringrequiredOperator-facing status text.
    • job_idstringrequiredQueued job id, or empty when the action is synchronous.
    • errorstring or nullMachine slug when admission failed (conflict, queue_full).
  • 400The target is invalid. As text/plain, when the body is not syntactically valid JSON. Body: ErrorJson (application/json); string (text/plain)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The 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 (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 409The migration target matches more than one database plugin. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The copy failed. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/database/migrate' \
    -X POST \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{"to": "postgres"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/database/migrate' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{"to": "postgres"}'
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)
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());
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.

{
  "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:

{
  "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.

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

Schema:

{
  "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.

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

Schema:

{
  "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.

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

Schema:

{
  "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.

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

Schema:

{
  "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.

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.

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.

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

Schema:

{
  "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.

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

  • 200The caller's preferences. Body: PreferencesResponse (application/json)7 fields
    • default_viewstringrequiredLanding view id (library, discover, …) after normalization.
    • disabled_shelvesarray of stringrequiredLowercased Discover shelf ids the user has hidden.
    • discover_sortstringrequiredDiscover sort key (relevance, popularity, …).
    • discover_sort_dirstringrequiredDiscover sort direction (asc or desc).
    • discover_languagestring or nullnull = use browser language on the client.
    • discover_excluded_sourcesarray of stringrequiredLowercased store ids hidden from Discover results.
    • themestringrequiredAppearance preference (system, light, or dark).
  • 401No signed-in caller. Body: string (text/plain)
  • 403A 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 (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The request could not be read or written. Body: string (text/plain)
  • 503The 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 (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The preferences row did not load in time. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/preferences' \
    -H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/preferences' `
    -Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/api/preferences",
    headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/preferences", {
  headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
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.

{
  "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:

{
  "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.

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.

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

Schema:

{
  "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.

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.

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

Schema:

{
  "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.

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

  • default_viewstring or nullReplacement landing view when set.
  • disabled_shelvesarray of string or nullReplacement hidden-shelf list when set.
  • discover_sortstring or nullReplacement Discover sort key when set.
  • discover_sort_dirstring or nullReplacement Discover sort direction when set.
  • discover_languagestring or nullPresent + value sets language; present + null clears to browser default; omitted leaves unchanged.
  • discover_excluded_sourcesarray of string or nullReplacement excluded-store list when set.
  • themestring or nullReplacement appearance preference when set (system, light, dark).

Responses

  • 200The preferences after the change. Body: PreferencesResponse (application/json)7 fields
    • default_viewstringrequiredLanding view id (library, discover, …) after normalization.
    • disabled_shelvesarray of stringrequiredLowercased Discover shelf ids the user has hidden.
    • discover_sortstringrequiredDiscover sort key (relevance, popularity, …).
    • discover_sort_dirstringrequiredDiscover sort direction (asc or desc).
    • discover_languagestring or nullnull = use browser language on the client.
    • discover_excluded_sourcesarray of stringrequiredLowercased store ids hidden from Discover results.
    • themestringrequiredAppearance preference (system, light, or dark).
  • 400The body is not syntactically valid JSON. Body: string (text/plain)
  • 401No signed-in caller. Body: string (text/plain)
  • 403A 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 (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the patch (a wrong type or an unknown shape). Body: string (text/plain)
  • 500The request could not be read or written. Body: string (text/plain)
  • 503The 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 (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The preferences row did not load or save in time. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/preferences' \
    -X PATCH \
    -H 'Authorization: Bearer <operatorToken>' \
    -H 'Content-Type: application/json' \
    -d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/preferences' `
    -Method Patch `
    -Headers @{ Authorization = 'Bearer <operatorToken>' } `
    -ContentType 'application/json' `
    -Body '{}'
import requests

response = requests.patch(
    "http://127.0.0.1:8787/api/preferences",
    headers={"Authorization": "Bearer <operatorToken>"},
    json={},
)
print(response.status_code, response.text)
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());
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.

{
  "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:

{
  "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.

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.

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.

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

Schema:

{
  "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.

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).

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.

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.

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

Schema:

{
  "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.

preferences update timed out

Schema:

A text/plain body: a string.

Generated from crates/bookclerkd/openapi.json at main · View as Markdown