Legacy
Old unprefixed paths; use the /api/… route named in each.
Back to the web API reference.
Deprecated.
Deprecated alias of GET /api/status.
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.
$ curl 'http://127.0.0.1:8787/status' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/status' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/status",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/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/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
}
}
}
Deprecated.
Deprecated alias of POST /api/library/scan.
Access: The operator, or a signed-in Administrator, Owner or user allowed to acquire.
Credentials: operatorToken or operatorSession or portalSession
Optional.
application/json: ScanRequest or null
accountstring or nullWhen set, scan this account even ifscan_enabledis false.plugin_instance_idstring or nullWhen set, scan only this deployed plugin instance.
-
200The scan jobs were accepted; see
POST /api/library/scanfor the other answers. Body:ScanPlanResponse(application/json)5 fieldsokbooleanrequiredTrue when at least one job was accepted.messagestringrequiredOperator-facing status text.job_idstringrequiredFirst accepted (or, when none was, already queued) job id.job_idsarray of stringrequiredEvery accepted or already-queued job id, in plan order.errorstring or nullMachine slug when nothing was accepted (conflict,queue_full,nothing_to_scan,nothing_to_acquire).
- 400The body is not syntactically valid JSON. Body: string (
text/plain) -
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.
- 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
503The sign-in could not be checked because the library did not answer in time (
session_check_unavailable). The response carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine slug (same as [ErrorBody::code]).messagestringrequiredOperator-facing explanation.statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
$ curl 'http://127.0.0.1:8787/scan' \
-X POST \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/scan' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.post(
"http://127.0.0.1:8787/scan",
headers={"Authorization": "Bearer <operatorToken>"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/scan", {
method: "POST",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/scan")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The scan jobs were accepted; see POST /api/library/scan for the other answers.
{
"job_id": "scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f",
"job_ids": [
"scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f"
],
"message": "scan job scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f accepted",
"ok": true
}
Schema:
{
"type": "object",
"description": "Result of a planned scan or acquire: [`ActionResponse`] plus every job id.",
"required": [
"ok",
"message",
"job_id",
"job_ids"
],
"properties": {
"ok": {
"type": "boolean",
"description": "True when at least one job was accepted.",
"example": true
},
"message": {
"type": "string",
"description": "Operator-facing status text.",
"example": "scan planned: 2 accepted, 0 already pending or running, 0 not admitted (queue full)"
},
"job_id": {
"type": "string",
"description": "First accepted (or, when none was, already queued) job id.",
"example": "scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f"
},
"job_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Every accepted or already-queued job id, in plan order.",
"example": [
"scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f",
"scan-8c1d2e3f-4a5b-4c6d-9e7f-0a1b2c3d4e5f"
]
},
"error": {
"type": [
"string",
"null"
],
"description": "Machine slug when nothing was accepted (`conflict`, `queue_full`,\n`nothing_to_scan`, `nothing_to_acquire`).",
"example": "nothing_to_scan"
}
}
}
Status 400: The body is not syntactically valid JSON.
Failed to parse the request body as JSON: expected value at line 1 column 1
Schema:
A text/plain body: a string.
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 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: account: invalid type: integer `1`, expected a string at line 1 column 12
Schema:
A text/plain body: a string.
Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.
{
"error": "session_check_unavailable",
"message": "Your sign-in could not be checked yet. Try again in a moment.",
"status": 503
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Deprecated.
Deprecated alias of POST /api/library/acquire.
Access: The operator, or a signed-in Administrator, Owner or user allowed to acquire.
Credentials: operatorToken or operatorSession or portalSession
Optional.
application/json: AcquireRequestBody or null
asinstring or nullAudible ASIN filter; first of uuid/asin/isbn/product_id wins.uuidstring or nullLibrary title UUID filter.isbnstring or nullISBN filter for non-Audible stores.product_idstring or nullStore product id filter.accountstring or nullRestrict acquire to this store account.plugin_instance_idstring or nullWhen set, fetch through this deployed plugin instance.titlesarray of stringMore title ids; each (with the single filter above) becomes its own job.editionsarray of stringEditions to acquire (idof an edition in a work's detail). Each becomes one job for a title that sells it in an account the caller may acquire for (inaccountwhen that is set); the edition's titles share its files.forcebooleanRe-download titles already acquired.pdf_onlybooleanFetch only each title's companion PDF.
-
200The acquire jobs were accepted; see
POST /api/library/acquirefor the other answers. Body:ActionResponse(application/json)4 fieldsokbooleanrequiredTrue when the action was accepted or completed.messagestringrequiredOperator-facing status text.job_idstringrequiredQueued job id, or empty when the action is synchronous.errorstring or nullMachine slug when admission failed (conflict,queue_full).
- 400The body is not syntactically valid JSON. Body: string (
text/plain) -
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.
- 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
503The sign-in could not be checked because the library did not answer in time (
session_check_unavailable). The response carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine slug (same as [ErrorBody::code]).messagestringrequiredOperator-facing explanation.statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
$ curl 'http://127.0.0.1:8787/acquire' \
-X POST \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/acquire' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.post(
"http://127.0.0.1:8787/acquire",
headers={"Authorization": "Bearer <operatorToken>"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/acquire", {
method: "POST",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/acquire")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The acquire jobs were accepted; see POST /api/library/acquire for the other answers.
{
"job_id": "acquire-3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"message": "acquire job acquire-3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b accepted",
"ok": true
}
Schema:
{
"type": "object",
"description": "Generic mutation result with success flag, message, and optional job id.",
"required": [
"ok",
"message",
"job_id"
],
"properties": {
"ok": {
"type": "boolean",
"description": "True when the action was accepted or completed.",
"example": true
},
"message": {
"type": "string",
"description": "Operator-facing status text.",
"example": "scan queued"
},
"job_id": {
"type": "string",
"description": "Queued job id, or empty when the action is synchronous.",
"example": "scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f"
},
"error": {
"type": [
"string",
"null"
],
"description": "Machine slug when admission failed (`conflict`, `queue_full`).",
"example": "queue_full"
}
}
}
Status 400: The body is not syntactically valid JSON.
Failed to parse the request body as JSON: expected value at line 1 column 1
Schema:
A text/plain body: a string.
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 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: asin: invalid type: integer `1`, expected a string at line 1 column 9
Schema:
A text/plain body: a string.
Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.
{
"error": "session_check_unavailable",
"message": "Your sign-in could not be checked yet. Try again in a moment.",
"status": 503
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Deprecated.
Deprecated alias of GET /api/jobs.
Access: The operator, or a signed-in Administrator, Owner or user allowed to acquire.
Credentials: operatorToken or operatorSession or portalSession
-
200Jobs, newest first. Body: array of
JobInfo(application/json)10 fieldsidstringrequiredOpaque job id returned to the client when the job is accepted.kindJobKindrequiredWhat the job does.statusJobStaterequiredWhere the job is in its lifecycle.detailstring or nullOptional operator-facing progress or error text.progressstring or nullHuman-readable progress string while the job is running.attempt_countinteger (int64)Number of times a worker has claimed this row.max_attemptsinteger (int64)Maximum claims before a failure is terminal.error_kindstring or nullStructured error kind when failed or cancelled.created_atstring or nullRFC 3339 timestamp when the row was inserted.finished_atstring or nullRFC 3339 timestamp when the row reached a terminal state.
-
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 job table 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.
$ curl 'http://127.0.0.1:8787/jobs' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/jobs' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/jobs",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/jobs", {
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/jobs")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Jobs, newest first.
[
{
"id": "scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f",
"kind": "scan",
"status": "pending",
"detail": "scanning reader@example.com (libro)",
"progress": "12 of 40 titles",
"attempt_count": 1,
"max_attempts": 3,
"error_kind": "cancelled",
"created_at": "2026-10-29T10:12:00Z",
"finished_at": "2026-10-29T10:14:22Z"
}
]
Schema:
{
"type": "array",
"items": {
"type": "object",
"description": "Snapshot of one queued or running control-plane job.",
"required": [
"id",
"kind",
"status"
],
"properties": {
"id": {
"type": "string",
"description": "Opaque job id returned to the client when the job is accepted.",
"example": "scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f"
},
"kind": {
"type": "string",
"description": "What the job does.",
"enum": [
"scan",
"acquire",
"listen_sync",
"integration_scan",
"plugin_copy",
"plugin_scheduled",
"discover_candidates",
"discover_feed",
"discover_request_queue",
"cache_sweep",
"search_index_rebuild",
"library_index_rebuild",
"branch_request",
"ingest_batch",
"notify_send",
"invalid"
]
},
"status": {
"type": "string",
"description": "Where the job is in its lifecycle.",
"enum": [
"pending",
"running",
"succeeded",
"failed",
"cancelled"
]
},
"detail": {
"type": [
"string",
"null"
],
"description": "Optional operator-facing progress or error text.",
"example": "scanning reader@example.com (libro)"
},
"progress": {
"type": [
"string",
"null"
],
"description": "Human-readable progress string while the job is running.",
"example": "12 of 40 titles"
},
"attempt_count": {
"type": "integer",
"format": "int64",
"description": "Number of times a worker has claimed this row.",
"example": 1
},
"max_attempts": {
"type": "integer",
"format": "int64",
"description": "Maximum claims before a failure is terminal.",
"example": 3
},
"error_kind": {
"type": [
"string",
"null"
],
"description": "Structured error kind when failed or cancelled.",
"example": "cancelled"
},
"created_at": {
"type": [
"string",
"null"
],
"description": "RFC 3339 timestamp when the row was inserted.",
"example": "2026-10-29T10:12:00Z"
},
"finished_at": {
"type": [
"string",
"null"
],
"description": "RFC 3339 timestamp when the row reached a terminal state.",
"example": "2026-10-29T10:14:22Z"
}
}
}
}
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 job table 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
}
}
}
Deprecated.
Deprecated alias of POST /api/jobs/{id}/cancel.
Access: The operator, or a signed-in Administrator, Owner or user allowed to acquire.
Credentials: operatorToken or operatorSession or portalSession
idpathstringrequiredJob id.
-
200The job was cancelled or asked to stop. Body:
ActionResponse(application/json)4 fieldsokbooleanrequiredTrue when the action was accepted or completed.messagestringrequiredOperator-facing status text.job_idstringrequiredQueued job id, or empty when the action is synchronous.errorstring or nullMachine slug when admission failed (conflict,queue_full).
-
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.
-
404No such job. 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.
$ curl 'http://127.0.0.1:8787/jobs/<id>/cancel' \
-X POST \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/jobs/<id>/cancel' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.post(
"http://127.0.0.1:8787/jobs/<id>/cancel",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/jobs/<id>/cancel", {
method: "POST",
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/jobs/<id>/cancel")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The job was cancelled or asked to stop.
{
"job_id": "scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f",
"message": "job scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f cancelled",
"ok": true
}
Schema:
{
"type": "object",
"description": "Generic mutation result with success flag, message, and optional job id.",
"required": [
"ok",
"message",
"job_id"
],
"properties": {
"ok": {
"type": "boolean",
"description": "True when the action was accepted or completed.",
"example": true
},
"message": {
"type": "string",
"description": "Operator-facing status text.",
"example": "scan queued"
},
"job_id": {
"type": "string",
"description": "Queued job id, or empty when the action is synchronous.",
"example": "scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f"
},
"error": {
"type": [
"string",
"null"
],
"description": "Machine slug when admission failed (`conflict`, `queue_full`).",
"example": "queue_full"
}
}
}
Status 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 404: No such job.
{
"error": "not_found",
"message": "That page or resource was not found.",
"status": 404
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Status 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
}
}
}
Enqueues a remote integration library scan; 404 if missing, 400 if unsupported.
Access: The operator, or a signed-in Administrator, Owner or user allowed to acquire.
Credentials: operatorToken or operatorSession or portalSession
idpathstringrequiredIntegration instance id.
Optional.
application/json: IntegrationScanRequest or null
forceboolean or nullWhen true, the integration rescans even if it considers itself current.
-
200The job was accepted. Body:
ActionResponse(application/json)4 fieldsokbooleanrequiredTrue when the action was accepted or completed.messagestringrequiredOperator-facing status text.job_idstringrequiredQueued job id, or empty when the action is synchronous.errorstring or nullMachine slug when admission failed (conflict,queue_full).
-
400The integration cannot scan a library. As
text/plain, when the body is not syntactically valid JSON. Body:ErrorJson(application/json); string (text/plain)3 fieldserrorstringrequiredMachine slug (same as [ErrorBody::code]).messagestringrequiredOperator-facing explanation.statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. A 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.
-
404No integration with this id. Body:
ErrorJson(application/json)3 fieldserrorstringrequiredMachine slug (same as [ErrorBody::code]).messagestringrequiredOperator-facing explanation.statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
-
409The same job is already pending or running, or no node can run it. Body:
ActionResponse(application/json)4 fieldsokbooleanrequiredTrue when the action was accepted or completed.messagestringrequiredOperator-facing status text.job_idstringrequiredQueued job id, or empty when the action is synchronous.errorstring or nullMachine slug when admission failed (conflict,queue_full).
- 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
429The job queue is full. Body:
ActionResponse(application/json)4 fieldsokbooleanrequiredTrue when the action was accepted or completed.messagestringrequiredOperator-facing status text.job_idstringrequiredQueued job id, or empty when the action is synchronous.errorstring or nullMachine slug when admission failed (conflict,queue_full).
-
500The job could not be queued. Body:
ActionResponse(application/json)4 fieldsokbooleanrequiredTrue when the action was accepted or completed.messagestringrequiredOperator-facing status text.job_idstringrequiredQueued job id, or empty when the action is synchronous.errorstring or nullMachine slug when admission failed (conflict,queue_full).
- 503Job admission is paused. When the sign-in could not be checked because the library did not answer in time, the answer is
session_check_unavailableinstead, withRetry-After; ask again rather than treating the caller as signed out. Body:ActionResponseorErrorJson(application/json)
$ curl 'http://127.0.0.1:8787/integrations/<id>/scan' \
-X POST \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/integrations/<id>/scan' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.post(
"http://127.0.0.1:8787/integrations/<id>/scan",
headers={"Authorization": "Bearer <operatorToken>"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/integrations/<id>/scan", {
method: "POST",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/integrations/<id>/scan")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The job was accepted.
{
"job_id": "integration_scan-9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
"message": "integration_scan job integration_scan-9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b accepted",
"ok": true
}
Schema:
{
"type": "object",
"description": "Generic mutation result with success flag, message, and optional job id.",
"required": [
"ok",
"message",
"job_id"
],
"properties": {
"ok": {
"type": "boolean",
"description": "True when the action was accepted or completed.",
"example": true
},
"message": {
"type": "string",
"description": "Operator-facing status text.",
"example": "scan queued"
},
"job_id": {
"type": "string",
"description": "Queued job id, or empty when the action is synchronous.",
"example": "scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f"
},
"error": {
"type": [
"string",
"null"
],
"description": "Machine slug when admission failed (`conflict`, `queue_full`).",
"example": "queue_full"
}
}
}
Status 400: The integration cannot scan a library. As text/plain, when the body is not syntactically valid JSON.
{
"error": "bad_request",
"message": "The request could not be understood.",
"status": 400
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route. A 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 404: No integration with this id.
{
"error": "not_found",
"message": "That page or resource was not found.",
"status": 404
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Status 409: The same job is already pending or running, or no node can run it.
{
"error": "conflict",
"job_id": "integration_scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f",
"message": "integration_scan already pending or running",
"ok": false
}
Schema:
{
"type": "object",
"description": "Generic mutation result with success flag, message, and optional job id.",
"required": [
"ok",
"message",
"job_id"
],
"properties": {
"ok": {
"type": "boolean",
"description": "True when the action was accepted or completed.",
"example": true
},
"message": {
"type": "string",
"description": "Operator-facing status text.",
"example": "scan queued"
},
"job_id": {
"type": "string",
"description": "Queued job id, or empty when the action is synchronous.",
"example": "scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f"
},
"error": {
"type": [
"string",
"null"
],
"description": "Machine slug when admission failed (`conflict`, `queue_full`).",
"example": "queue_full"
}
}
}
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: force: invalid type: integer `1`, expected a boolean at line 1 column 10
Schema:
A text/plain body: a string.
Status 429: The job queue is full.
{
"error": "queue_full",
"job_id": "",
"message": "job queue is full",
"ok": false
}
Schema:
{
"type": "object",
"description": "Generic mutation result with success flag, message, and optional job id.",
"required": [
"ok",
"message",
"job_id"
],
"properties": {
"ok": {
"type": "boolean",
"description": "True when the action was accepted or completed.",
"example": true
},
"message": {
"type": "string",
"description": "Operator-facing status text.",
"example": "scan queued"
},
"job_id": {
"type": "string",
"description": "Queued job id, or empty when the action is synchronous.",
"example": "scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f"
},
"error": {
"type": [
"string",
"null"
],
"description": "Machine slug when admission failed (`conflict`, `queue_full`).",
"example": "queue_full"
}
}
}
Status 500: The job could not be queued.
{
"error": "internal_error",
"job_id": "",
"message": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection",
"ok": false
}
Schema:
{
"type": "object",
"description": "Generic mutation result with success flag, message, and optional job id.",
"required": [
"ok",
"message",
"job_id"
],
"properties": {
"ok": {
"type": "boolean",
"description": "True when the action was accepted or completed.",
"example": true
},
"message": {
"type": "string",
"description": "Operator-facing status text.",
"example": "scan queued"
},
"job_id": {
"type": "string",
"description": "Queued job id, or empty when the action is synchronous.",
"example": "scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f"
},
"error": {
"type": [
"string",
"null"
],
"description": "Machine slug when admission failed (`conflict`, `queue_full`).",
"example": "queue_full"
}
}
}
Status 503: Job admission is paused. When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out.
{
"error": "admission_paused",
"job_id": "",
"message": "job admission paused (database reload in progress)",
"ok": false
}
Schema:
{
"anyOf": [
{
"type": "object",
"description": "Generic mutation result with success flag, message, and optional job id.",
"required": [
"ok",
"message",
"job_id"
],
"properties": {
"ok": {
"type": "boolean",
"description": "True when the action was accepted or completed.",
"example": true
},
"message": {
"type": "string",
"description": "Operator-facing status text.",
"example": "scan queued"
},
"job_id": {
"type": "string",
"description": "Queued job id, or empty when the action is synchronous.",
"example": "scan-7d0c1e2f-3a4b-4c5d-8e6f-9a0b1c2d3e4f"
},
"error": {
"type": [
"string",
"null"
],
"description": "Machine slug when admission failed (`conflict`, `queue_full`).",
"example": "queue_full"
}
}
},
{
"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
}
}
}
]
}
Generated from crates/bookclerkd/openapi.json at main · View as Markdown