Settings
Daemon settings and user preferences.
Back to the web API reference.
Returns file-backed and runtime-effective Settings plus per-plugin groups.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
-
200The settings. Body:
SettingsResponse(application/json)6 fieldssettingsmap of string to stringrequiredValues as written in config.toml (and env overlays), plusoutput.*from thecore.outputdatabase document.effectivemap of string to stringrequiredRuntime-effective values after the last successful reload (auth, plugins).pluginsarray ofPluginSettingsGrouprequiredPer-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 thecore.outputdocument theoutput.*values insettingswere read from; send it back asexpected_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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
500The settings could not be read. Body:
ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
Validates, writes, and reloads allowlisted Settings keys under reload_lock.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
application/json: PatchSettingsRequest
settingsarray ofSettingsUpdaterequiredKey/value pairs to validate, persist, and reload.expected_output_revisioninteger (int64) or nullcore.outputdocument revision the client read (output_revisioninGET /api/settings). When set and stale, anoutput.*update is rejected with 409.
-
200The settings after the change. Body:
SettingsResponse(application/json)6 fieldssettingsmap of string to stringrequiredValues as written in config.toml (and env overlays), plusoutput.*from thecore.outputdatabase document.effectivemap of string to stringrequiredRuntime-effective values after the last successful reload (auth, plugins).pluginsarray ofPluginSettingsGrouprequiredPer-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 thecore.outputdocument theoutput.*values insettingswere read from; send it back asexpected_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 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredStable 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
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
409
output.*keys were sent with a staleexpected_output_revision, or another write won; the body'scurrent_revisionis the revision to retry against (revision_conflict). Body:ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
-
200The install's sent reports, newest first. Body:
DiagnosticsReportsResponse(application/json)1 fieldreportsarray ofDiagnosticsReportViewrequiredSent reports, newest first (the last 200 are kept).
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ 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?);
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.
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
idpathstringrequiredThe report's ID, fromGET /api/diagnostics/reports.
-
200The report as the collector holds it. Body:
DiagnosticsReportLookup(application/json)6 fieldsreport_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.reportStoredReportViewor nullThe stored report, or null once deleted.issuesarray ofReportIssueViewrequiredIssues tracking it, the tracking issue first.fixReportFixViewor nullThe tracking issue's fix, or null.
-
400The ID is not a version-4 UUID (
invalid_report_id). Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
idpathstringrequiredThe report's ID, fromGET /api/diagnostics/reports.
-
200The stored copy is gone (deleting again answers the same). Body:
DiagnosticsReportDeleted(application/json)2 fieldsreport_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 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredStable 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
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
Copies library rows between database plugins and optionally switches [database].plugin.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
application/json: DatabaseMigrateRequest
fromstring or nullSource plugin id. Defaults to the active[database].pluginbefore 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].pluginin config.toml after a successful copy.
-
200The rows were copied. Body:
ActionResponse(application/json)4 fieldsokbooleanrequiredTrue 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 fieldserrorstringrequiredMachine 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 fieldserrorstringrequiredStable 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
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
409The migration target matches more than one database plugin. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable 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 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
-
200The caller's preferences. Body:
PreferencesResponse(application/json)7 fieldsdefault_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 (ascordesc).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, ordark).
- 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 getsclerk_sign_in_unavailable. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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.
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
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 +nullclears 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).
-
200The preferences after the change. Body:
PreferencesResponse(application/json)7 fieldsdefault_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 (ascordesc).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, ordark).
- 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 getsclerk_sign_in_unavailable. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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 carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine 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)
$ 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?);
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