Legacy

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

Last updated View as Markdown

Old unprefixed paths; use the /api/… route named in each.

Back to the web API reference.

GET /status

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

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.

Example request

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

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
    }
  }
}

POST /scan

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

Request body

Optional.

application/json: ScanRequest or null

  • accountstring or nullWhen set, scan this account even if scan_enabled is false.
  • plugin_instance_idstring or nullWhen set, scan only this deployed plugin instance.

Responses

  • 200The scan jobs were accepted; see POST /api/library/scan for the other answers. Body: ScanPlanResponse (application/json)5 fields
    • okbooleanrequiredTrue 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 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.
  • 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 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.

Example request

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

Example response

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
    }
  }
}

POST /acquire

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

Request body

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 (id of 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 (in account when that is set); the edition's titles share its files.
  • forcebooleanRe-download titles already acquired.
  • pdf_onlybooleanFetch only each title's companion PDF.

Responses

  • 200The acquire jobs were accepted; see POST /api/library/acquire for the other answers. Body: ActionResponse (application/json)4 fields
    • okbooleanrequiredTrue 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 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.
  • 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 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.

Example request

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

Example response

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
    }
  }
}

GET /jobs

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

Responses

  • 200Jobs, newest first. Body: array of JobInfo (application/json)10 fields
    • idstringrequiredOpaque 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 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 job table 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.

Example request

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

Example response

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
    }
  }
}

POST /jobs/{id}/cancel

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

Parameters

  • idpathstringrequiredJob id.

Responses

  • 200The job was cancelled or asked to stop. Body: ActionResponse (application/json)4 fields
    • okbooleanrequiredTrue 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 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.
  • 404No such job. 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.

Example request

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

Example response

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
    }
  }
}

POST /integrations/{id}/scan

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

Parameters

  • idpathstringrequiredIntegration instance id.

Request body

Optional.

application/json: IntegrationScanRequest or null

  • forceboolean or nullWhen true, the integration rescans even if it considers itself current.

Responses

  • 200The job was accepted. Body: ActionResponse (application/json)4 fields
    • okbooleanrequiredTrue 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 fields
    • errorstringrequiredMachine 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 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.
  • 404No integration with this id. 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.
  • 409The same job is already pending or running, or no node can run it. Body: ActionResponse (application/json)4 fields
    • okbooleanrequiredTrue 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 fields
    • okbooleanrequiredTrue 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 fields
    • okbooleanrequiredTrue 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_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out. Body: ActionResponse or ErrorJson (application/json)

Example request

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

Example response

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