Jobs
Queued and running control-plane jobs.
Back to the web API reference.
Returns durable scan/acquire/listen_sync jobs, newest first.
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.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/jobs' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/jobs' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/jobs",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/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/api/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
}
}
}
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Cancel a pending job or request cooperative stop of a running job.
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. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine slug (same as [ErrorBody::code]).messagestringrequiredOperator-facing explanation.statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
-
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.
-
500The job could not be updated. Body:
ErrorJson(application/json)3 fieldserrorstringrequiredMachine slug (same as [ErrorBody::code]).messagestringrequiredOperator-facing explanation.statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
-
503The sign-in could not be checked because the library did not answer in time (
session_check_unavailable). The response carriesRetry-After; ask again rather than treating the caller as signed out. Body:ErrorJson(application/json)3 fieldserrorstringrequiredMachine slug (same as [ErrorBody::code]).messagestringrequiredOperator-facing explanation.statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/jobs/<id>/cancel' \
-X POST \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/jobs/<id>/cancel' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.post(
"http://127.0.0.1:8787/api/jobs/<id>/cancel",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/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/api/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. A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "forbidden",
"message": "You do not have access to this resource.",
"status": 403
}
Schema:
{
"type": "object",
"description": "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 500: The job could not be updated.
{
"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.
Generated from crates/bookclerkd/openapi.json at main · View as Markdown