Status
Library and daemon snapshot.
Back to the web API reference.
Returns library counts, listen addresses, storage backends, and whether operator auth is on.
Access: The operator, or a signed-in Administrator, Owner or user allowed to acquire.
Credentials: operatorToken or operatorSession or portalSession
-
200Library counts and daemon state. Body:
StatusResponse(application/json)10 fieldsaccountsintegerrequiredCount of configured store accounts. At least 0.booksintegerrequiredHeld works in the library (the works page index). At least 0.acquiredinteger (int64)requiredHeld works whose furthest acquire state isacquired.pendinginteger (int64)requiredHeld works still needing acquire (not_acquired).errorinteger (int64)requiredHeld works stuck inerrorafter a failed acquire.in_progressinteger (int64)requiredHeld works currentlyqueuedordownloading.listenstringrequiredComma-joineddaemon.listenaddresses from live config.storage_backendstringrequiredComma-joined enabled destination plugin ids, ornone.auth_enabledbooleanrequiredWhether the live auth middleware requires operator credentials.eventsEventQueueStatusrequiredDurable domain-event delivery-queue counters.
-
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 signed-in user who must enroll a second factor first gets
mfa_enrollment_required. 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 library 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.
-
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 request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/status' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/status' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/status",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/status", {
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/status")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Library counts and daemon state.
{
"accounts": 2,
"books": 412,
"acquired": 380,
"pending": 27,
"error": 1,
"in_progress": 4,
"listen": "127.0.0.1:8787,[::1]:8787",
"storage_backend": "local",
"auth_enabled": true,
"events": {
"pending": 3,
"running": 1,
"suspended": 0,
"dead_letter": 0,
"acked": 1284,
"oldest_pending_age_secs": 12,
"retries_total": 7,
"suspensions_total": 2,
"dead_letters_total": 0,
"dispatch_latency_ms_avg": 140,
"handler_latency_ms_avg": 860
}
}
Schema:
{
"type": "object",
"description": "Library and daemon snapshot for `GET /api/status`.",
"required": [
"accounts",
"books",
"acquired",
"pending",
"error",
"in_progress",
"listen",
"storage_backend",
"auth_enabled",
"events"
],
"properties": {
"accounts": {
"type": "integer",
"description": "Count of configured store accounts.",
"example": 2,
"minimum": 0
},
"books": {
"type": "integer",
"description": "Held works in the library (the works page index).",
"example": 412,
"minimum": 0
},
"acquired": {
"type": "integer",
"format": "int64",
"description": "Held works whose furthest acquire state is `acquired`.",
"example": 380
},
"pending": {
"type": "integer",
"format": "int64",
"description": "Held works still needing acquire (`not_acquired`).",
"example": 27
},
"error": {
"type": "integer",
"format": "int64",
"description": "Held works stuck in `error` after a failed acquire.",
"example": 1
},
"in_progress": {
"type": "integer",
"format": "int64",
"description": "Held works currently `queued` or `downloading`.",
"example": 4
},
"listen": {
"type": "string",
"description": "Comma-joined `daemon.listen` addresses from live config.",
"example": "127.0.0.1:8787,[::1]:8787"
},
"storage_backend": {
"type": "string",
"description": "Comma-joined enabled destination plugin ids, or `none`.",
"example": "local"
},
"auth_enabled": {
"type": "boolean",
"description": "Whether the live auth middleware requires operator credentials.",
"example": true
},
"events": {
"type": "object",
"description": "Durable domain-event delivery-queue counters.",
"required": [
"pending",
"running",
"suspended",
"dead_letter",
"acked",
"retries_total",
"suspensions_total",
"dead_letters_total"
],
"properties": {
"pending": {
"type": "integer",
"format": "int64",
"description": "Pending deliveries without a suspend checkpoint.",
"example": 3
},
"running": {
"type": "integer",
"format": "int64",
"description": "Currently claimed deliveries.",
"example": 1
},
"suspended": {
"type": "integer",
"format": "int64",
"description": "Pending deliveries parked with a checkpoint.",
"example": 0
},
"dead_letter": {
"type": "integer",
"format": "int64",
"description": "Dead-lettered deliveries.",
"example": 0
},
"acked": {
"type": "integer",
"format": "int64",
"description": "Successfully acked deliveries.",
"example": 1284
},
"oldest_pending_age_secs": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Age in seconds of the oldest pending delivery, when any exist.",
"example": 12
},
"retries_total": {
"type": "integer",
"format": "int64",
"description": "Durable retry outcomes (including reclaim-as-retry).",
"example": 7
},
"suspensions_total": {
"type": "integer",
"format": "int64",
"description": "Durable suspend outcomes.",
"example": 2
},
"dead_letters_total": {
"type": "integer",
"format": "int64",
"description": "Durable transitions into `dead_letter`.",
"example": 0
},
"dispatch_latency_ms_avg": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Average first-dispatch latency in milliseconds, when sampled.",
"example": 140
},
"handler_latency_ms_avg": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Average `onEvent` handler duration in milliseconds, when sampled.",
"example": 860
}
}
}
}
}
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 signed-in user who must enroll a second factor first gets mfa_enrollment_required.
{
"error": "forbidden",
"message": "You do not have access to this resource.",
"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 library 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 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 request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Returns the audio codecs, file types and output encodings this build's media worker handles.
Access: The operator, or a signed-in Administrator, Owner or user allowed to acquire.
Credentials: operatorToken or operatorSession or portalSession
-
200What the media worker reads and writes. Body:
MediaCapabilitiesJson(application/json)3 fieldsdecodesarray of stringrequiredAudio codecs the worker decodes (aac,alac,flac,mp3,opus,vorbis, andeac3in builds with the FFmpeg decoders).readsarray of stringrequiredMedia types of files the worker opens, compared without case or parameters. Builds with the FFmpeg decoders add WMA, raw AC-3 and E-AC-3, and AMR types.encodesarray ofOutputEncodingJsonrequiredEncodings the worker writes.
-
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 signed-in user who must enroll a second factor first gets
mfa_enrollment_required. 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.
-
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 request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/status/media' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/status/media' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/status/media",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/status/media", {
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/status/media")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: What the media worker reads and writes.
{
"decodes": [
"aac",
"alac",
"flac",
"mp3",
"opus",
"vorbis"
],
"reads": [
"audio/mp4",
"audio/mpeg",
"audio/flac",
"audio/ogg"
],
"encodes": [
{
"advanced": false,
"name": "m4b"
},
{
"advanced": false,
"name": "mp3"
},
{
"advanced": true,
"name": "opus"
}
]
}
Schema:
{
"type": "object",
"description": "The codecs, containers and encodings this build's media worker handles.",
"required": [
"decodes",
"reads",
"encodes"
],
"properties": {
"decodes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Audio codecs the worker decodes (`aac`, `alac`, `flac`, `mp3`,\n`opus`, `vorbis`, and `eac3` in builds with the FFmpeg decoders).",
"example": [
"aac",
"alac",
"flac",
"mp3",
"opus",
"vorbis"
]
},
"reads": {
"type": "array",
"items": {
"type": "string"
},
"description": "Media types of files the worker opens, compared without case or\nparameters. Builds with the FFmpeg decoders add WMA, raw AC-3 and\nE-AC-3, and AMR types.",
"example": [
"audio/mp4",
"audio/mpeg",
"audio/flac",
"audio/ogg"
]
},
"encodes": {
"type": "array",
"items": {
"type": "object",
"description": "One encoding the media worker writes.",
"required": [
"name",
"advanced"
],
"properties": {
"name": {
"type": "string",
"description": "The output format id that selects it (`m4b`, `mp3` or `opus`).",
"example": "opus"
},
"advanced": {
"type": "boolean",
"description": "True when settings offer it only under their advanced options,\nbecause fewer players open it than M4B and MP3.",
"example": true
}
}
},
"description": "Encodings the worker writes.",
"example": [
{
"advanced": false,
"name": "m4b"
},
{
"advanced": false,
"name": "mp3"
},
{
"advanced": true,
"name": "opus"
}
]
}
}
}
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 signed-in user who must enroll a second factor first gets mfa_enrollment_required.
{
"error": "forbidden",
"message": "You do not have access to this resource.",
"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 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 request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
GET /api/library-status: library-wide health every node administrator
may see (node counts, committed capacity, active jobs, delivery backlog),
plus detail for the nodes the caller may see.
Access: The operator, a signed-in Owner or Administrator, or a Member who owns at least one node.
Credentials: operatorToken or operatorSession or portalSession
-
200Library-wide node health. Body:
LibraryStatusResponse(application/json)4 fieldslibraryLibrarySummaryrequiredLibrary-wide counters.node_idstringrequiredId of the node that answered.nodesarray ofNodeViewrequiredThe nodes the caller administers.capabilitiesNodeCapabilitiesrequiredWhat the caller may do with them.
-
401The caller is not signed in. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller may not do this. A signed-in user who must enroll a second factor first gets
mfa_enrollment_required. 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 configuration could not be read. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
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 request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/library-status' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/library-status' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/library-status",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/library-status", {
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/library-status")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Library-wide node health.
{
"library": {
"nodes": 3,
"live": 3,
"drained": 0,
"branch_nodes": 1,
"cpu_budget_millicores": 19200,
"cpu_reserved_millicores": 3200,
"memory_budget_bytes": 37748736000,
"memory_reserved_bytes": 2147483648,
"running_guests": 4,
"active_jobs": 2,
"deliveries": {
"pending": 3,
"running": 1,
"dead_letter": 0,
"oldest_pending_age_secs": 12
},
"leases": [
{
"name": "scheduler",
"holder": "node-7f3a9c",
"token": 42,
"held": true,
"expires_at_ms": 1793214480000
}
],
"schema": {
"compatible": true,
"state": "frozen@12+a1b2c3d4"
}
},
"node_id": "node-7f3a9c",
"nodes": [
{
"node_id": "node-7f3a9c",
"library_id": "c0ffee12-3456-4789-8abc-def012345678",
"created_at": "2026-10-01T08:00:00Z",
"heartbeat_at": "2026-10-28T19:07:00Z",
"software_version": "0.3.1",
"schema_state": "frozen@12+a1b2c3d4",
"compatible": true,
"target": "linux-x64-gnu",
"labels": [
"rack=a"
],
"implicit_labels": [
"node=node-7f3a9c",
"target=linux-x64-gnu"
],
"live": true,
"runtime": {
"label": "Living-room server",
"cpu_budget_percent": 80,
"memory_budget_percent": 75,
"schedulable": true,
"cache_budget_bytes": 536870912
},
"status": {
"node_id": "node-7f3a9c",
"incarnation": "01J9Q0Z5C7M8N3P4R6S8T9V0W1",
"started_at": "2026-10-28T06:00:00Z",
"heartbeat_at": "2026-10-28T19:07:00Z",
"heartbeat_ms": 1793214420000,
"interval_ms": 15000,
"cpu_millicores": 8000,
"memory_bytes": 16777216000,
"cpu_budget_millicores": 6400,
"memory_budget_bytes": 12582912000,
"schedulable": true,
"cpu_used_millicores": 350,
"memory_available_bytes": 9663676416,
"files_dir_free_bytes": 214748364800,
"reserved": {
"memory_bytes": 1073741824,
"cpu_millicores": 1600
},
"running_guests": 2,
"availability_ppm": 998500,
"online_since_ms": 1793167200000,
"cache_bytes": 734003200,
"cache_budget_bytes": 1073741824,
"cache_swept_ms": 1793212800000,
"public_origin": "https://branch.example"
},
"this_node": true,
"kind": "shared",
"relationship": "remote_branch",
"owner_user_id": 7,
"share_books": true,
"include_branches": false,
"owner": {
"user_id": 7,
"display_name": "Sam Reader",
"role": "owner"
}
}
],
"capabilities": {
"scope": "all",
"can_edit_runtime": true,
"can_edit_labels": true,
"can_assign_owner": true
}
}
Schema:
{
"type": "object",
"description": "`GET /api/library-status` body.",
"required": [
"library",
"node_id",
"nodes",
"capabilities"
],
"properties": {
"library": {
"type": "object",
"description": "Library-wide counters.",
"required": [
"nodes",
"live",
"drained",
"branch_nodes",
"cpu_budget_millicores",
"cpu_reserved_millicores",
"memory_budget_bytes",
"memory_reserved_bytes",
"running_guests",
"active_jobs",
"deliveries",
"leases",
"schema"
],
"properties": {
"nodes": {
"type": "integer",
"description": "Nodes in the library's node list.",
"example": 3,
"minimum": 0
},
"live": {
"type": "integer",
"description": "Nodes whose last heartbeat is recent enough.",
"example": 3,
"minimum": 0
},
"drained": {
"type": "integer",
"description": "Live nodes an operator drained.",
"example": 0,
"minimum": 0
},
"branch_nodes": {
"type": "integer",
"description": "Enrolled hosts (nodes with their own database).",
"example": 1,
"minimum": 0
},
"cpu_budget_millicores": {
"type": "integer",
"format": "int64",
"description": "CPU the scheduler may commit across live nodes, in millicores.",
"example": 19200
},
"cpu_reserved_millicores": {
"type": "integer",
"format": "int64",
"description": "CPU the running guests' ceilings add up to, in millicores.",
"example": 3200
},
"memory_budget_bytes": {
"type": "integer",
"format": "int64",
"description": "Memory the scheduler may commit across live nodes, in bytes.",
"example": 37748736000
},
"memory_reserved_bytes": {
"type": "integer",
"format": "int64",
"description": "Memory the running guests' ceilings add up to, in bytes.",
"example": 2147483648
},
"running_guests": {
"type": "integer",
"format": "int64",
"description": "Guests running across live nodes.",
"example": 4
},
"active_jobs": {
"type": "integer",
"format": "int64",
"description": "Jobs queued or running.",
"example": 2
},
"deliveries": {
"type": "object",
"description": "Event delivery backlog.",
"required": [
"pending",
"running",
"dead_letter"
],
"properties": {
"pending": {
"type": "integer",
"format": "int64",
"description": "Deliveries waiting for a consumer.",
"example": 3
},
"running": {
"type": "integer",
"format": "int64",
"description": "Deliveries a consumer is handling now.",
"example": 1
},
"dead_letter": {
"type": "integer",
"format": "int64",
"description": "Deliveries that exhausted their retries.",
"example": 0
},
"oldest_pending_age_secs": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Age of the oldest pending delivery in seconds; `null` when none is\npending.",
"example": 12
}
}
},
"leases": {
"type": "array",
"items": {
"type": "object",
"description": "A library lease as the status page shows it.",
"required": [
"name",
"holder",
"token",
"held",
"expires_at_ms"
],
"properties": {
"name": {
"type": "string",
"description": "Lease name.",
"example": "scheduler"
},
"holder": {
"type": "string",
"description": "Holder (a node id).",
"example": "node-7f3a9c"
},
"token": {
"type": "integer",
"format": "int64",
"description": "Fencing token; a new holder always gets a larger one.",
"example": 42
},
"held": {
"type": "boolean",
"description": "True while the lease has not expired.",
"example": true
},
"expires_at_ms": {
"type": "integer",
"format": "int64",
"description": "Expiry in Unix milliseconds.",
"example": 1793214480000
}
}
},
"description": "Every library lease, held or expired."
},
"schema": {
"type": "object",
"description": "The database schema against this binary.",
"required": [
"compatible"
],
"properties": {
"state": {
"type": [
"string",
"null"
],
"description": "The schema state (`uninitialized`, `unreleased@base<n>+<checksum>`\nor `frozen@<n>+<checksum>`); `null` when it could not be read.",
"example": "frozen@12+a1b2c3d4"
},
"compatible": {
"type": "boolean",
"description": "True when this binary can run against that schema.",
"example": true
},
"error": {
"type": [
"string",
"null"
],
"description": "Why the state could not be read; omitted when it was.",
"example": "database is locked"
}
},
"example": {
"compatible": true,
"state": "frozen@12+a1b2c3d4"
}
}
}
},
"node_id": {
"type": "string",
"description": "Id of the node that answered.",
"example": "node-7f3a9c"
},
"nodes": {
"type": "array",
"items": {
"type": "object",
"description": "One node with its latest heartbeat, budget and owner.",
"required": [
"node_id",
"library_id",
"created_at",
"heartbeat_at",
"software_version",
"schema_state",
"compatible",
"target",
"labels",
"implicit_labels",
"live",
"runtime",
"this_node",
"kind",
"relationship"
],
"properties": {
"node_id": {
"type": "string",
"description": "Node id.",
"example": "node-7f3a9c"
},
"library_id": {
"type": "string",
"description": "Library the node belongs to.",
"example": "c0ffee12-3456-4789-8abc-def012345678"
},
"created_at": {
"type": "string",
"description": "RFC 3339 time the node first enrolled.",
"example": "2026-10-01T08:00:00Z"
},
"heartbeat_at": {
"type": "string",
"description": "RFC 3339 time of the last heartbeat the node row recorded.",
"example": "2026-10-28T19:07:00Z"
},
"software_version": {
"type": "string",
"description": "Bookclerk version the node runs.",
"example": "0.3.1"
},
"schema_state": {
"type": "string",
"description": "Database schema the node last applied.",
"example": "frozen@12+a1b2c3d4"
},
"compatible": {
"type": "boolean",
"description": "True when the node's own binary accepted the schema it reported;\nnot a comparison with this daemon's schema.",
"example": true
},
"target": {
"type": "string",
"description": "Bookclerk target the node runs on.",
"example": "linux-x64-gnu"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-set placement labels.",
"example": [
"rack=a"
]
},
"implicit_labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "Labels the scheduler adds for the node (its id and target).",
"example": [
"node=node-7f3a9c",
"target=linux-x64-gnu"
]
},
"live": {
"type": "boolean",
"description": "True while the last heartbeat is recent enough.",
"example": true
},
"runtime": {
"type": "object",
"description": "The node's runtime document, or the defaults when it never wrote\none.",
"required": [
"label"
],
"properties": {
"label": {
"type": "string",
"description": "Operator label shown for this node. Empty is allowed.",
"example": "Living-room server"
},
"cpu_budget_percent": {
"type": "integer",
"format": "int32",
"description": "Share of detected CPU cores the scheduler may commit to plugin\nguests on this node (1..=100).",
"example": 80,
"maximum": 100,
"minimum": 1
},
"memory_budget_percent": {
"type": "integer",
"format": "int32",
"description": "Share of detected memory the scheduler may commit (1..=100).",
"example": 75,
"maximum": 100,
"minimum": 1
},
"schedulable": {
"type": "boolean",
"description": "False drains the node: the scheduler places nothing new here and\nmoves its replicas elsewhere. Hand-managed deployments still run.",
"example": true
},
"cache_budget_bytes": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Disk space, in bytes, this node's image caches may use together,\noverriding the library's `core.cache` budget (16 MiB to 1 TiB).\nAbsent means the library budget applies.",
"example": 536870912,
"maximum": 1099511627776,
"minimum": 16777216
}
}
},
"status": {
"oneOf": [
{
"type": "object",
"description": "The latest heartbeat; `null` before the first one.",
"required": [
"node_id",
"incarnation",
"started_at",
"heartbeat_at",
"heartbeat_ms",
"interval_ms",
"cpu_millicores",
"cpu_budget_millicores",
"schedulable",
"reserved",
"running_guests",
"availability_ppm",
"online_since_ms"
],
"properties": {
"node_id": {
"type": "string",
"description": "Reporting node.",
"example": "node-7f3a9c"
},
"incarnation": {
"type": "string",
"description": "Daemon process incarnation.",
"example": "01J9Q0Z5C7M8N3P4R6S8T9V0W1"
},
"started_at": {
"type": "string",
"description": "RFC 3339 daemon start.",
"example": "2026-10-28T06:00:00Z"
},
"heartbeat_at": {
"type": "string",
"description": "RFC 3339 heartbeat time.",
"example": "2026-10-28T19:07:00Z"
},
"heartbeat_ms": {
"type": "integer",
"format": "int64",
"description": "Heartbeat time in Unix milliseconds.",
"example": 1793214420000
},
"interval_ms": {
"type": "integer",
"format": "int64",
"description": "Promised interval in milliseconds.",
"example": 15000
},
"cpu_millicores": {
"type": "integer",
"format": "int64",
"description": "Detected CPU capacity in millicores.",
"example": 8000
},
"memory_bytes": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Detected memory in bytes.",
"example": 16777216000
},
"cpu_budget_millicores": {
"type": "integer",
"format": "int64",
"description": "CPU the scheduler may commit, in millicores.",
"example": 6400
},
"memory_budget_bytes": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Memory the scheduler may commit, in bytes.",
"example": 12582912000
},
"schedulable": {
"type": "boolean",
"description": "False when an operator drained the node.",
"example": true
},
"cpu_used_millicores": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Measured CPU in use, in millicores.",
"example": 350
},
"memory_available_bytes": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Measured memory available, in bytes.",
"example": 9663676416
},
"files_dir_free_bytes": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Free bytes on the files directory's filesystem.",
"example": 214748364800
},
"reserved": {
"type": "object",
"description": "Ceilings of the guests running here.",
"required": [
"memory_bytes",
"cpu_millicores"
],
"properties": {
"memory_bytes": {
"type": "integer",
"format": "int64",
"description": "Memory ceiling in bytes.",
"example": 1073741824
},
"cpu_millicores": {
"type": "integer",
"format": "int64",
"description": "CPU ceiling in millicores.",
"example": 1600
}
}
},
"running_guests": {
"type": "integer",
"format": "int64",
"description": "Guests running here.",
"example": 2
},
"availability_ppm": {
"type": "integer",
"format": "int64",
"description": "Recent online fraction in parts per million.",
"example": 998500
},
"online_since_ms": {
"type": "integer",
"format": "int64",
"description": "Unix milliseconds the current online stretch began.",
"example": 1793167200000
},
"cache_bytes": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bytes the node's image caches hold; `None` from a node that keeps\nnone.",
"example": 734003200
},
"cache_budget_bytes": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Bytes the node's image caches may hold.",
"example": 1073741824
},
"cache_swept_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "When the node's last cache sweep finished, in Unix milliseconds.",
"example": 1793212800000
},
"public_origin": {
"type": [
"string",
"null"
],
"description": "The address other installs reach this branch at, as it last\nreported it; `null` for a local branch and for a shared node. A\nbranch with one is a remote branch of this library.",
"example": "https://branch.example"
}
}
},
{
"type": "null"
}
]
},
"this_node": {
"type": "boolean",
"description": "True for the node that answered the request.",
"example": true
},
"kind": {
"type": "string",
"description": "`shared` for a node sharing this library's database, `branch` for an\nenrolled branch.",
"enum": [
"shared",
"branch"
],
"example": "shared"
},
"relationship": {
"type": "string",
"description": "How the node relates to this library: `shared_branch` (shares its\ndatabase), `remote_branch` (a branch reporting a public address in\nits heartbeat, `status.public_origin`) or `local_branch` (a branch\nwith none).",
"enum": [
"shared_branch",
"remote_branch",
"local_branch"
],
"example": "remote_branch"
},
"owner_user_id": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "User id of the node's owner; `null` when unassigned.",
"example": 7
},
"share_books": {
"type": [
"boolean",
"null"
],
"description": "A branch's sharing setting, as it last reported it; `null` for a\nshared node.",
"example": true
},
"include_branches": {
"type": [
"boolean",
"null"
],
"description": "A branch's include-branches setting, as it last reported it;\n`null` for a shared node.",
"example": false
},
"owner": {
"oneOf": [
{
"type": "object",
"description": "The owner, when the node has one and the user still exists.",
"required": [
"user_id",
"role"
],
"properties": {
"user_id": {
"type": "integer",
"format": "int64",
"description": "The owner's user id.",
"example": 7
},
"display_name": {
"type": [
"string",
"null"
],
"description": "Display name, or the login name when none is set; `null` when the\nuser has neither.",
"example": "Sam Reader"
},
"role": {
"type": "string",
"description": "The owner's role.",
"enum": [
"owner",
"administrator",
"member"
]
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "The nodes the caller administers."
},
"capabilities": {
"type": "object",
"description": "What the caller may do with them.",
"required": [
"scope",
"can_edit_runtime",
"can_edit_labels",
"can_assign_owner"
],
"properties": {
"scope": {
"type": "string",
"description": "`all` for the operator, `owned` for a node owner.",
"enum": [
"all",
"owned"
]
},
"can_edit_runtime": {
"type": "boolean",
"description": "True: every caller may edit the runtime settings of the nodes it\nsees.",
"example": true
},
"can_edit_labels": {
"type": "boolean",
"description": "True for the operator, who may replace placement labels.",
"example": true
},
"can_assign_owner": {
"type": "boolean",
"description": "True for the operator, who may assign or clear a node's owner.",
"example": true
}
}
}
}
}
Status 401: The caller is not signed in.
{
"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 may not do this. A signed-in user who must enroll a second factor first gets mfa_enrollment_required.
{
"error": "forbidden",
"message": "You do not have access to this resource.",
"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 configuration could not be read.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
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 request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Generated from crates/bookclerkd/openapi.json at main · View as Markdown