Status

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

Last updated View as Markdown

Library and daemon snapshot.

Back to the web API reference.

GET /api/status

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

Responses

  • 200Library counts and daemon state. Body: StatusResponse (application/json)10 fields
    • accountsintegerrequiredCount 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 is acquired.
    • pendinginteger (int64)requiredHeld works still needing acquire (not_acquired).
    • errorinteger (int64)requiredHeld works stuck in error after a failed acquire.
    • in_progressinteger (int64)requiredHeld works currently queued or downloading.
    • listenstringrequiredComma-joined daemon.listen addresses from live config.
    • storage_backendstringrequiredComma-joined enabled destination plugin ids, or none.
    • 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 fields
    • errorstringrequiredStable 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 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The library could not be read. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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.

GET /api/status/media

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

Responses

  • 200What the media worker reads and writes. Body: MediaCapabilitiesJson (application/json)3 fields
    • decodesarray of stringrequiredAudio codecs the worker decodes (aac, alac, flac, mp3, opus, vorbis, and eac3 in 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 of OutputEncodingJsonrequiredEncodings the worker writes.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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

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

Responses

  • 200Library-wide node health. Body: LibraryStatusResponse (application/json)4 fields
    • libraryLibrarySummaryrequiredLibrary-wide counters.
    • node_idstringrequiredId of the node that answered.
    • nodesarray of NodeViewrequiredThe nodes the caller administers.
    • capabilitiesNodeCapabilitiesrequiredWhat the caller may do with them.
  • 401The caller is not signed in. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable 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 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The configuration could not be read. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat 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 carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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