Events
Domain events and their deliveries.
Back to the web API reference.
Returns recent domain-event outbox rows, newest first.
Access: The operator, or a signed-in Administrator, Owner or user allowed to acquire.
Credentials: operatorToken or operatorSession or portalSession
-
200Recent domain events, newest first. Body: array of
DomainEventInfo(application/json)11 fieldsidstringrequiredEvent id.eventTypestringrequiredEvent type (book_acquired).schemaVersioninteger (int64)requiredPayload schema version.dispatchStatestringrequiredpendingordispatched.accountIdstringrequiredTenant / account id.dedupKeystringrequiredProducer idempotency key.createdAtstringrequiredRFC 3339 insert time.queueNamestringrequiredQueue the row belongs to (core.eventsfor domain events).contentTypestringrequiredBody encoding (json,text,bytes).sourcestringrequiredProducer plugin id; empty when the host published it.deliverAfterstring or nullRFC 3339 earliest delivery time for delayed queue messages.
-
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 outbox 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/events' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/events' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/events",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/events", {
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/events")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Recent domain events, newest first.
[
{
"id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"eventType": "book_acquired",
"schemaVersion": 1,
"dispatchState": "dispatched",
"accountId": "reader@example.com",
"dedupKey": "book_acquired:3f2c0d7e-9d4b-4a62-8b1e-6d0f7c2a9b31",
"createdAt": "2026-10-29T10:12:00Z",
"queueName": "core.events",
"contentType": "json",
"source": "",
"deliverAfter": "2026-10-29T10:15:00Z"
}
]
Schema:
{
"type": "array",
"items": {
"type": "object",
"description": "Operator JSON for one `domain_events` row.",
"required": [
"id",
"eventType",
"schemaVersion",
"dispatchState",
"accountId",
"dedupKey",
"createdAt",
"queueName",
"contentType",
"source"
],
"properties": {
"id": {
"type": "string",
"description": "Event id.",
"example": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
},
"eventType": {
"type": "string",
"description": "Event type (`book_acquired`).",
"example": "book_acquired"
},
"schemaVersion": {
"type": "integer",
"format": "int64",
"description": "Payload schema version.",
"example": 1
},
"dispatchState": {
"type": "string",
"description": "`pending` or `dispatched`.",
"example": "dispatched"
},
"accountId": {
"type": "string",
"description": "Tenant / account id.",
"example": "reader@example.com"
},
"dedupKey": {
"type": "string",
"description": "Producer idempotency key.",
"example": "book_acquired:3f2c0d7e-9d4b-4a62-8b1e-6d0f7c2a9b31"
},
"createdAt": {
"type": "string",
"description": "RFC 3339 insert time.",
"example": "2026-10-29T10:12:00Z"
},
"queueName": {
"type": "string",
"description": "Queue the row belongs to (`core.events` for domain events).",
"example": "core.events"
},
"contentType": {
"type": "string",
"description": "Body encoding (`json`, `text`, `bytes`).",
"example": "json"
},
"source": {
"type": "string",
"description": "Producer plugin id; empty when the host published it.",
"example": ""
},
"deliverAfter": {
"type": [
"string",
"null"
],
"description": "RFC 3339 earliest delivery time for delayed queue messages.",
"example": "2026-10-29T10:15:00Z"
}
}
}
}
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 outbox could not be read.
{
"error": "internal_error",
"message": "Something went wrong on the Bookclerk daemon.",
"status": 500
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.
{
"error": "session_check_unavailable",
"message": "Your sign-in could not be checked yet. Try again in a moment.",
"status": 503
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Returns event deliveries, optionally filtered by state.
Access: The operator, or a signed-in Administrator, Owner or user allowed to acquire.
Credentials: operatorToken or operatorSession or portalSession
statequerystringDelivery state (dead_letter,pending, …).
-
200Deliveries, newest first. Body: array of
EventDeliveryInfo(application/json)16 fieldsidstringrequiredDelivery id ({event_id}:{plugin_id}).eventIdstringrequiredParent event id.pluginIdstringrequiredSubscriber plugin id.statestringrequiredLifecycle state.attemptCountinteger (int64)requiredClaim count (not incremented on resume).leaseGenerationinteger (int64)requiredFence generation.invocationSequenceinteger (int64)requiredResume ordinal.outcomestring or nullTerminal outcome when set.errorMessagestring or nullOperator-facing error.runAfterstringrequiredRFC 3339 earliest claim time.updatedAtstringrequiredRFC 3339 last update.cancelRequestedbooleanrequiredCooperative cancel flag.resourceClassstringrequiredConcurrency class (networktoday).resumePendingbooleanrequiredNext claim should resume rather than increment attempt.hasCheckpointbooleanrequiredTrue when a suspend checkpoint is stored.queueNamestringrequiredQueue of the parent event.
-
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 outbox 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/events/deliveries' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/events/deliveries' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/events/deliveries",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/events/deliveries", {
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/events/deliveries")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Deliveries, newest first.
[
{
"id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:audiobookshelf",
"eventId": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"pluginId": "audiobookshelf",
"state": "pending",
"attemptCount": 1,
"leaseGeneration": 2,
"invocationSequence": 0,
"outcome": "ack",
"errorMessage": "integration API error (503): library scan in progress",
"runAfter": "2026-10-29T10:12:00Z",
"updatedAt": "2026-10-29T10:12:30Z",
"cancelRequested": false,
"resourceClass": "network",
"resumePending": false,
"hasCheckpoint": false,
"queueName": "core.events"
}
]
Schema:
{
"type": "array",
"items": {
"type": "object",
"description": "Operator JSON for one `event_deliveries` row.",
"required": [
"id",
"eventId",
"pluginId",
"state",
"attemptCount",
"leaseGeneration",
"invocationSequence",
"runAfter",
"updatedAt",
"cancelRequested",
"resourceClass",
"resumePending",
"hasCheckpoint",
"queueName"
],
"properties": {
"id": {
"type": "string",
"description": "Delivery id (`{event_id}:{plugin_id}`).",
"example": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:audiobookshelf"
},
"eventId": {
"type": "string",
"description": "Parent event id.",
"example": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
},
"pluginId": {
"type": "string",
"description": "Subscriber plugin id.",
"example": "audiobookshelf"
},
"state": {
"type": "string",
"description": "Lifecycle state.",
"example": "pending"
},
"attemptCount": {
"type": "integer",
"format": "int64",
"description": "Claim count (not incremented on resume).",
"example": 1
},
"leaseGeneration": {
"type": "integer",
"format": "int64",
"description": "Fence generation.",
"example": 2
},
"invocationSequence": {
"type": "integer",
"format": "int64",
"description": "Resume ordinal.",
"example": 0
},
"outcome": {
"type": [
"string",
"null"
],
"description": "Terminal outcome when set.",
"example": "ack"
},
"errorMessage": {
"type": [
"string",
"null"
],
"description": "Operator-facing error.",
"example": "integration API error (503): library scan in progress"
},
"runAfter": {
"type": "string",
"description": "RFC 3339 earliest claim time.",
"example": "2026-10-29T10:12:00Z"
},
"updatedAt": {
"type": "string",
"description": "RFC 3339 last update.",
"example": "2026-10-29T10:12:30Z"
},
"cancelRequested": {
"type": "boolean",
"description": "Cooperative cancel flag.",
"example": false
},
"resourceClass": {
"type": "string",
"description": "Concurrency class (`network` today).",
"example": "network"
},
"resumePending": {
"type": "boolean",
"description": "Next claim should resume rather than increment attempt.",
"example": false
},
"hasCheckpoint": {
"type": "boolean",
"description": "True when a suspend checkpoint is stored.",
"example": false
},
"queueName": {
"type": "string",
"description": "Queue of the parent event.",
"example": "core.events"
}
}
}
}
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 outbox could not be read.
{
"error": "internal_error",
"message": "Something went wrong on the Bookclerk daemon.",
"status": 500
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.
{
"error": "session_check_unavailable",
"message": "Your sign-in could not be checked yet. Try again in a moment.",
"status": 503
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Returns every queue the outbox or the live catalog knows about, with delivery counters and the consumers subscribed to it.
Access: The operator, or a signed-in Administrator, Owner or user allowed to acquire.
Credentials: operatorToken or operatorSession or portalSession
-
200Every known queue. Body: array of
QueueInfo(application/json)7 fieldsnamestringrequiredQueue name.corebooleanrequiredTrue for the domain-event bus (core.events).pendinginteger (int64)requiredDeliveries waiting to be claimed (including suspended rows).runninginteger (int64)requiredDeliveries currently claimed by a worker.ackedinteger (int64)requiredDeliveries acked.deadLetterinteger (int64)requiredDeliveries parked for operator review.consumersarray of stringrequiredLive catalog consumers (plugin keys or instance ids) of this queue.
-
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 outbox 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/queues' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/queues' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/queues",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/queues", {
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/queues")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Every known queue.
[
{
"name": "core.events",
"core": true,
"pending": 3,
"running": 1,
"acked": 1284,
"deadLetter": 0,
"consumers": [
"platform:bookclerk/bookclerk-plugin-integration-audiobookshelf#audiobookshelf"
]
}
]
Schema:
{
"type": "array",
"items": {
"type": "object",
"description": "Operator JSON for one queue on `GET /api/queues`.",
"required": [
"name",
"core",
"pending",
"running",
"acked",
"deadLetter",
"consumers"
],
"properties": {
"name": {
"type": "string",
"description": "Queue name.",
"example": "core.events"
},
"core": {
"type": "boolean",
"description": "True for the domain-event bus (`core.events`).",
"example": true
},
"pending": {
"type": "integer",
"format": "int64",
"description": "Deliveries waiting to be claimed (including suspended rows).",
"example": 3
},
"running": {
"type": "integer",
"format": "int64",
"description": "Deliveries currently claimed by a worker.",
"example": 1
},
"acked": {
"type": "integer",
"format": "int64",
"description": "Deliveries acked.",
"example": 1284
},
"deadLetter": {
"type": "integer",
"format": "int64",
"description": "Deliveries parked for operator review.",
"example": 0
},
"consumers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Live catalog consumers (plugin keys or instance ids) of this queue.",
"example": [
"platform:bookclerk/bookclerk-plugin-integration-audiobookshelf#audiobookshelf"
]
}
}
}
}
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 outbox could not be read.
{
"error": "internal_error",
"message": "Something went wrong on the Bookclerk daemon.",
"status": 500
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Status 503: The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out.
{
"error": "session_check_unavailable",
"message": "Your sign-in could not be checked yet. Try again in a moment.",
"status": 503
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Returns one queue's counters, consumers, recent messages, and deliveries.
Access: The operator, or a signed-in Administrator, Owner or user allowed to acquire.
Credentials: operatorToken or operatorSession or portalSession
namepathstringrequiredQueue name.
-
200The queue. Body:
QueueDetail(application/json)2 fieldsmessagesarray ofDomainEventInforequiredRecent messages on the queue, newest first.deliveriesarray ofEventDeliveryInforequiredRecent deliveries on the queue, newest first.
-
400The queue name is invalid. 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.
-
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 outbox 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/queues/<name>' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/queues/<name>' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/queues/<name>",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/queues/<name>", {
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/queues/<name>")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The queue.
{
"name": "core.events",
"core": true,
"pending": 3,
"running": 1,
"acked": 1284,
"deadLetter": 0,
"consumers": [
"platform:bookclerk/bookclerk-plugin-integration-audiobookshelf#audiobookshelf"
],
"messages": [
{
"id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"eventType": "book_acquired",
"schemaVersion": 1,
"dispatchState": "dispatched",
"accountId": "reader@example.com",
"dedupKey": "book_acquired:3f2c0d7e-9d4b-4a62-8b1e-6d0f7c2a9b31",
"createdAt": "2026-10-29T10:12:00Z",
"queueName": "core.events",
"contentType": "json",
"source": "",
"deliverAfter": "2026-10-29T10:15:00Z"
}
],
"deliveries": [
{
"id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:audiobookshelf",
"eventId": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"pluginId": "audiobookshelf",
"state": "pending",
"attemptCount": 1,
"leaseGeneration": 2,
"invocationSequence": 0,
"outcome": "ack",
"errorMessage": "integration API error (503): library scan in progress",
"runAfter": "2026-10-29T10:12:00Z",
"updatedAt": "2026-10-29T10:12:30Z",
"cancelRequested": false,
"resourceClass": "network",
"resumePending": false,
"hasCheckpoint": false,
"queueName": "core.events"
}
]
}
Schema:
{
"allOf": [
{
"type": "object",
"description": "Queue summary.",
"required": [
"name",
"core",
"pending",
"running",
"acked",
"deadLetter",
"consumers"
],
"properties": {
"name": {
"type": "string",
"description": "Queue name.",
"example": "core.events"
},
"core": {
"type": "boolean",
"description": "True for the domain-event bus (`core.events`).",
"example": true
},
"pending": {
"type": "integer",
"format": "int64",
"description": "Deliveries waiting to be claimed (including suspended rows).",
"example": 3
},
"running": {
"type": "integer",
"format": "int64",
"description": "Deliveries currently claimed by a worker.",
"example": 1
},
"acked": {
"type": "integer",
"format": "int64",
"description": "Deliveries acked.",
"example": 1284
},
"deadLetter": {
"type": "integer",
"format": "int64",
"description": "Deliveries parked for operator review.",
"example": 0
},
"consumers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Live catalog consumers (plugin keys or instance ids) of this queue.",
"example": [
"platform:bookclerk/bookclerk-plugin-integration-audiobookshelf#audiobookshelf"
]
}
}
},
{
"type": "object",
"required": [
"messages",
"deliveries"
],
"properties": {
"messages": {
"type": "array",
"items": {
"type": "object",
"description": "Operator JSON for one `domain_events` row.",
"required": [
"id",
"eventType",
"schemaVersion",
"dispatchState",
"accountId",
"dedupKey",
"createdAt",
"queueName",
"contentType",
"source"
],
"properties": {
"id": {
"type": "string",
"description": "Event id.",
"example": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
},
"eventType": {
"type": "string",
"description": "Event type (`book_acquired`).",
"example": "book_acquired"
},
"schemaVersion": {
"type": "integer",
"format": "int64",
"description": "Payload schema version.",
"example": 1
},
"dispatchState": {
"type": "string",
"description": "`pending` or `dispatched`.",
"example": "dispatched"
},
"accountId": {
"type": "string",
"description": "Tenant / account id.",
"example": "reader@example.com"
},
"dedupKey": {
"type": "string",
"description": "Producer idempotency key.",
"example": "book_acquired:3f2c0d7e-9d4b-4a62-8b1e-6d0f7c2a9b31"
},
"createdAt": {
"type": "string",
"description": "RFC 3339 insert time.",
"example": "2026-10-29T10:12:00Z"
},
"queueName": {
"type": "string",
"description": "Queue the row belongs to (`core.events` for domain events).",
"example": "core.events"
},
"contentType": {
"type": "string",
"description": "Body encoding (`json`, `text`, `bytes`).",
"example": "json"
},
"source": {
"type": "string",
"description": "Producer plugin id; empty when the host published it.",
"example": ""
},
"deliverAfter": {
"type": [
"string",
"null"
],
"description": "RFC 3339 earliest delivery time for delayed queue messages.",
"example": "2026-10-29T10:15:00Z"
}
}
},
"description": "Recent messages on the queue, newest first."
},
"deliveries": {
"type": "array",
"items": {
"type": "object",
"description": "Operator JSON for one `event_deliveries` row.",
"required": [
"id",
"eventId",
"pluginId",
"state",
"attemptCount",
"leaseGeneration",
"invocationSequence",
"runAfter",
"updatedAt",
"cancelRequested",
"resourceClass",
"resumePending",
"hasCheckpoint",
"queueName"
],
"properties": {
"id": {
"type": "string",
"description": "Delivery id (`{event_id}:{plugin_id}`).",
"example": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:audiobookshelf"
},
"eventId": {
"type": "string",
"description": "Parent event id.",
"example": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
},
"pluginId": {
"type": "string",
"description": "Subscriber plugin id.",
"example": "audiobookshelf"
},
"state": {
"type": "string",
"description": "Lifecycle state.",
"example": "pending"
},
"attemptCount": {
"type": "integer",
"format": "int64",
"description": "Claim count (not incremented on resume).",
"example": 1
},
"leaseGeneration": {
"type": "integer",
"format": "int64",
"description": "Fence generation.",
"example": 2
},
"invocationSequence": {
"type": "integer",
"format": "int64",
"description": "Resume ordinal.",
"example": 0
},
"outcome": {
"type": [
"string",
"null"
],
"description": "Terminal outcome when set.",
"example": "ack"
},
"errorMessage": {
"type": [
"string",
"null"
],
"description": "Operator-facing error.",
"example": "integration API error (503): library scan in progress"
},
"runAfter": {
"type": "string",
"description": "RFC 3339 earliest claim time.",
"example": "2026-10-29T10:12:00Z"
},
"updatedAt": {
"type": "string",
"description": "RFC 3339 last update.",
"example": "2026-10-29T10:12:30Z"
},
"cancelRequested": {
"type": "boolean",
"description": "Cooperative cancel flag.",
"example": false
},
"resourceClass": {
"type": "string",
"description": "Concurrency class (`network` today).",
"example": "network"
},
"resumePending": {
"type": "boolean",
"description": "Next claim should resume rather than increment attempt.",
"example": false
},
"hasCheckpoint": {
"type": "boolean",
"description": "True when a suspend checkpoint is stored.",
"example": false
},
"queueName": {
"type": "string",
"description": "Queue of the parent event.",
"example": "core.events"
}
}
},
"description": "Recent deliveries on the queue, newest first."
}
}
}
],
"description": "Operator JSON for `GET /api/queues/{name}`."
}
Status 400: The queue name is invalid.
{
"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 500: The outbox 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.
Re-queue a dead-lettered delivery.
Access: The operator, or a signed-in Administrator, Owner or user allowed to acquire.
Credentials: operatorToken or operatorSession or portalSession
idpathstringrequiredDelivery id.
-
200The delivery was queued again. 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 delivery, or it is not in a state this applies to. 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 outbox could not be read or written. 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/events/deliveries/<id>/retry' \
-X POST \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/events/deliveries/<id>/retry' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.post(
"http://127.0.0.1:8787/api/events/deliveries/<id>/retry",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/events/deliveries/<id>/retry", {
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/events/deliveries/<id>/retry")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The delivery was queued again.
{
"job_id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:audiobookshelf",
"message": "delivery b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:audiobookshelf re-queued",
"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 delivery, or it is not in a state this applies to.
{
"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 outbox could not be read or written.
{
"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.
Acknowledge a dead-lettered delivery (no further retry).
Access: The operator, or a signed-in Administrator, Owner or user allowed to acquire.
Credentials: operatorToken or operatorSession or portalSession
idpathstringrequiredDelivery id.
-
200The delivery was acknowledged. 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 delivery, or it is not in a state this applies to. 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 outbox could not be read or written. 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/events/deliveries/<id>/acknowledge' \
-X POST \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/events/deliveries/<id>/acknowledge' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.post(
"http://127.0.0.1:8787/api/events/deliveries/<id>/acknowledge",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/events/deliveries/<id>/acknowledge", {
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/events/deliveries/<id>/acknowledge")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The delivery was acknowledged.
{
"job_id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:audiobookshelf",
"message": "delivery b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:audiobookshelf acknowledged",
"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 delivery, or it is not in a state this applies to.
{
"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 outbox could not be read or written.
{
"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 delivery or request cooperative stop of a running one.
Access: The operator, or a signed-in Administrator, Owner or user allowed to acquire.
Credentials: operatorToken or operatorSession or portalSession
idpathstringrequiredDelivery id.
-
200The delivery 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 delivery, or it is not in a state this applies to. 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 outbox could not be read or written. 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/events/deliveries/<id>/cancel' \
-X POST \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/events/deliveries/<id>/cancel' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.post(
"http://127.0.0.1:8787/api/events/deliveries/<id>/cancel",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/events/deliveries/<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/events/deliveries/<id>/cancel")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The delivery was cancelled or asked to stop.
{
"job_id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:audiobookshelf",
"message": "delivery b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:audiobookshelf rejected",
"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 delivery, or it is not in a state this applies to.
{
"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 outbox could not be read or written.
{
"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.
Resume a suspended delivery (wake now, next claim uses resume_pending).
Access: The operator, or a signed-in Administrator, Owner or user allowed to acquire.
Credentials: operatorToken or operatorSession or portalSession
idpathstringrequiredDelivery id.
-
200The delivery was resumed. 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 delivery, or it is not in a state this applies to. 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 outbox could not be read or written. 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/events/deliveries/<id>/resume' \
-X POST \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/events/deliveries/<id>/resume' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.post(
"http://127.0.0.1:8787/api/events/deliveries/<id>/resume",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/events/deliveries/<id>/resume", {
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/events/deliveries/<id>/resume")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The delivery was resumed.
{
"job_id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:audiobookshelf",
"message": "delivery b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d:audiobookshelf resumed",
"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 delivery, or it is not in a state this applies to.
{
"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 outbox could not be read or written.
{
"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