Events

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

Last updated View as Markdown

Domain events and their deliveries.

Back to the web API reference.

GET /api/events

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

Responses

  • 200Recent domain events, newest first. Body: array of DomainEventInfo (application/json)11 fields
    • idstringrequiredEvent id.
    • eventTypestringrequiredEvent type (book_acquired).
    • schemaVersioninteger (int64)requiredPayload schema version.
    • dispatchStatestringrequiredpending or dispatched.
    • accountIdstringrequiredTenant / account id.
    • dedupKeystringrequiredProducer idempotency key.
    • createdAtstringrequiredRFC 3339 insert time.
    • queueNamestringrequiredQueue the row belongs to (core.events for 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 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 outbox could not be read. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/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?);

Example response

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.

GET /api/events/deliveries

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

Parameters

  • statequerystringDelivery state (dead_letter, pending, …).

Responses

  • 200Deliveries, newest first. Body: array of EventDeliveryInfo (application/json)16 fields
    • idstringrequiredDelivery 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 (network today).
    • 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 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 outbox could not be read. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/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?);

Example response

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.

GET /api/queues

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

Responses

  • 200Every known queue. Body: array of QueueInfo (application/json)7 fields
    • namestringrequiredQueue 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 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 outbox could not be read. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/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?);

Example response

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.

GET /api/queues/{name}

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

Parameters

  • namepathstringrequiredQueue name.

Responses

  • 200The queue. Body: QueueDetail (application/json)2 fields
    • messagesarray of DomainEventInforequiredRecent messages on the queue, newest first.
    • deliveriesarray of EventDeliveryInforequiredRecent deliveries on the queue, newest first.
  • 400The queue name is invalid. 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.
  • 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 outbox could not be read. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/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?);

Example response

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.

POST /api/events/deliveries/{id}/retry

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

Parameters

  • idpathstringrequiredDelivery id.

Responses

  • 200The delivery was queued again. 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. A write sent with a session cookie but without a matching Origin or Referer is refused. 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 delivery, or it is not in a state this applies to. 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 outbox could not be read or written. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/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?);

Example response

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.

POST /api/events/deliveries/{id}/acknowledge

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

Parameters

  • idpathstringrequiredDelivery id.

Responses

  • 200The delivery was acknowledged. 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. A write sent with a session cookie but without a matching Origin or Referer is refused. 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 delivery, or it is not in a state this applies to. 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 outbox could not be read or written. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/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?);

Example response

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.

POST /api/events/deliveries/{id}/cancel

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

Parameters

  • idpathstringrequiredDelivery id.

Responses

  • 200The delivery 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. A write sent with a session cookie but without a matching Origin or Referer is refused. 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 delivery, or it is not in a state this applies to. 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 outbox could not be read or written. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/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?);

Example response

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.

POST /api/events/deliveries/{id}/resume

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

Parameters

  • idpathstringrequiredDelivery id.

Responses

  • 200The delivery was resumed. 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. A write sent with a session cookie but without a matching Origin or Referer is refused. 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 delivery, or it is not in a state this applies to. 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 outbox could not be read or written. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 503The sign-in could not be checked because the library did not answer in time (session_check_unavailable). The response carries Retry-After; ask again rather than treating the caller as signed out. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/api/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?);

Example response

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