Playback
Play sessions, audio streams, listening progress and bookmarks.
Back to the web API reference.
Opens a play session for the caller.
Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).
Credentials: operatorToken or operatorSession or portalSession or clerkToken
application/json: OpenSessionBody
edition_idstringrequiredThe edition to play (1 to 128 bytes).playerPlayerKindParamWhat kind of player asks;webwhen left out.player_namestringThe player's own name, shown in listening history. Control characters are dropped and at most 64 bytes are kept.
-
200The session, its tracks and where to start. Body:
SessionJson(application/json)7 fieldssession_idstringrequiredThe session's id, for its sync, close and track routes.edition_idstringrequiredThe edition being played.work_idstring or nullIts work.position_msinteger (int64)requiredWhere to start, in milliseconds: the caller's stored position, or 0 for a first listen or an edition they had finished. At least 0.duration_msinteger (int64) or nullRuntime in milliseconds when known (see the manifest). At least 0.tracksarray ofTrackJsonrequiredThe tracks in play order, each with the path to stream it from.idle_secsinteger (int64)requiredSeconds without a report after which the session stops streaming and the player opens a new one.
-
400The edition id is empty or over 128 bytes. As
text/plain, when the body is not syntactically valid JSON. Body:ErrorMessage(application/json); string (text/plain)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The session ended. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 403The session has no library user. A signed-in user who must enroll a second factor first gets
mfa_enrollment_required. A library card sent over plain HTTP from another machine getstransport_insecure. A library card sent where the node API is not mounted getsclerk_sign_in_unavailable. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorMessageorErrorJsonorErrorJsonorErrorJson(application/json) -
404No such edition (
edition ... not found), or no copy of it on this node that the caller may play (not_playable). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
413The body is over 4096 bytes. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
500The library could not be read or written. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 503This node's storage could not be asked; retry (
unavailable). When the sign-in could not be checked because the library did not answer in time, the answer issession_check_unavailableinstead, withRetry-After; ask again rather than treating the caller as signed out. Body:ErrorMessageorErrorJson(application/json) - 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/playback/sessions' \
-X POST \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{"edition_id": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/playback/sessions' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{"edition_id": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d"}'
import requests
response = requests.post(
"http://127.0.0.1:8787/api/playback/sessions",
headers={"Authorization": "Bearer <operatorToken>"},
json={"edition_id": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/playback/sessions", {
method: "POST",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({"edition_id": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/playback/sessions")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({"edition_id": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d"}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The session, its tracks and where to start.
{
"session_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"edition_id": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d",
"work_id": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b",
"position_ms": 754000,
"duration_ms": 41400000,
"tracks": [
{
"index": 0,
"path": "/api/playback/sessions/7c9e6679-7425-40de-944b-e07fc1f90ae7/tracks/0",
"content_type": "audio/mp4",
"bitrate_kbps": 125,
"lossless": false
}
],
"idle_secs": 86400
}
Schema:
{
"type": "object",
"description": "`POST /api/playback/sessions` answer.",
"required": [
"session_id",
"edition_id",
"position_ms",
"tracks",
"idle_secs"
],
"properties": {
"session_id": {
"type": "string",
"description": "The session's id, for its sync, close and track routes.",
"example": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
},
"edition_id": {
"type": "string",
"description": "The edition being played.",
"example": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d"
},
"work_id": {
"type": [
"string",
"null"
],
"description": "Its work.",
"example": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b"
},
"position_ms": {
"type": "integer",
"format": "int64",
"description": "Where to start, in milliseconds: the caller's stored position, or\n0 for a first listen or an edition they had finished.",
"example": 754000,
"minimum": 0
},
"duration_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Runtime in milliseconds when known (see the manifest).",
"example": 41400000,
"minimum": 0
},
"tracks": {
"type": "array",
"items": {
"type": "object",
"description": "One audio file of an edition, as a player sees it.",
"required": [
"index",
"content_type",
"lossless"
],
"properties": {
"index": {
"type": "integer",
"description": "The track's place in play order, from 0.",
"example": 0,
"minimum": 0
},
"path": {
"type": [
"string",
"null"
],
"description": "Path to stream it from, on this origin; only in a session's answer.",
"example": "/api/playback/sessions/7c9e6679-7425-40de-944b-e07fc1f90ae7/tracks/0"
},
"content_type": {
"type": "string",
"description": "Media type the stream states, such as `audio/mp4`.",
"example": "audio/mp4"
},
"bitrate_kbps": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Average bitrate in kilobits per second, once probed.",
"example": 125,
"minimum": 0
},
"lossless": {
"type": "boolean",
"description": "True for a lossless encoding.",
"example": false
}
}
},
"description": "The tracks in play order, each with the path to stream it from."
},
"idle_secs": {
"type": "integer",
"format": "int64",
"description": "Seconds without a report after which the session stops streaming\nand the player opens a new one.",
"example": 86400
}
}
}
Status 400: The edition id is empty or over 128 bytes. As text/plain, when the body is not syntactically valid JSON.
{
"error": "edition_id must be 1 to 128 bytes"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The session ended.
{
"error": "sign in again"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 403: The session has no library user. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "clerk_sign_in_unavailable",
"message": "This library does not accept clerks on this address.",
"status": 403
}
Schema:
{
"anyOf": [
{
"anyOf": [
{
"anyOf": [
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
},
{
"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
}
}
}
]
},
{
"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
}
}
}
]
},
{
"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 edition (edition ... not found), or no copy of it on this node that the caller may play (not_playable).
{
"error": "not_playable"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 413: The body is over 4096 bytes.
{
"error": "the body is at most 4096 bytes"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: missing field `edition_id` at line 1 column 2
Schema:
A text/plain body: a string.
Status 500: The library could not be read or written.
{
"error": "the library could not be read"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 503: This node's storage could not be asked; retry (unavailable). When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out.
{
"error": "session_check_unavailable",
"message": "Your sign-in could not be checked yet. Try again in a moment.",
"status": 503
}
Schema:
{
"anyOf": [
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
},
{
"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.
Reports where the caller is in a playing session.
Players report every few seconds while playing, and on pause and seek.
Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).
Credentials: operatorToken or operatorSession or portalSession or clerkToken
idpathstringrequiredSession id fromPOST /api/playback/sessions.
application/json: PlaybackSyncBody
position_msinteger (int64)requiredPosition on the edition's timeline, in milliseconds from its start (at most sixty days). At least 0.listened_msinteger (int64)requiredMilliseconds listened since this session's last report, as the player counted them; left out reads as 0. At least 0.duration_msinteger (int64) or nullThe edition's whole runtime in milliseconds, when the player knows it; left out ornullkeeps the stored one. At least 0.
-
200The caller's progress after the report. Body:
SyncJson(application/json)2 fieldsprogressProgressJsonrequiredThe caller's progress after the report.finished_nowbooleanrequiredTrue when this report is the one that reached the edition's end: the edition and its work are now finished for the caller.
-
400A length is past sixty days. As
text/plain, when the body is not syntactically valid JSON. Body:ErrorMessage(application/json); string (text/plain)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
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 session has no library user. A signed-in user who must enroll a second factor first gets
mfa_enrollment_required. A library card sent over plain HTTP from another machine getstransport_insecure. A library card sent where the node API is not mounted getsclerk_sign_in_unavailable. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorMessageorErrorJsonorErrorJsonorErrorJson(application/json) -
404No such session of the caller's (
unknown_session). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
409The session was already closed (
session_ended); open a new one. Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
413The body is over 1024 bytes. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
500The library could not be read or written. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
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/playback/sessions/<id>/sync' \
-X POST \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{"position_ms": 754000, "listened_ms": 15000}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/playback/sessions/<id>/sync' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{"position_ms": 754000, "listened_ms": 15000}'
import requests
response = requests.post(
"http://127.0.0.1:8787/api/playback/sessions/<id>/sync",
headers={"Authorization": "Bearer <operatorToken>"},
json={"position_ms": 754000, "listened_ms": 15000},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/playback/sessions/<id>/sync", {
method: "POST",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({"position_ms": 754000, "listened_ms": 15000}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/playback/sessions/<id>/sync")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({"position_ms": 754000, "listened_ms": 15000}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The caller's progress after the report.
{
"progress": {
"edition_id": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d",
"work_id": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b",
"position_ms": 754000,
"duration_ms": 41400000,
"is_finished": false,
"started_at": "2026-11-19T08:15:00+00:00",
"finished_at": null,
"updated_at": "2026-11-19T09:02:41+00:00"
},
"finished_now": false
}
Schema:
{
"type": "object",
"description": "`POST /api/playback/sessions/{id}/sync` and `.../close` answer.",
"required": [
"progress",
"finished_now"
],
"properties": {
"progress": {
"type": "object",
"description": "The caller's progress after the report.",
"required": [
"edition_id",
"position_ms",
"is_finished",
"started_at",
"updated_at"
],
"properties": {
"edition_id": {
"type": "string",
"description": "The edition.",
"example": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d"
},
"work_id": {
"type": [
"string",
"null"
],
"description": "The edition's work, when known: what a Continue listening shelf\nreads the title and cover from.",
"example": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b"
},
"position_ms": {
"type": "integer",
"format": "int64",
"description": "Position on the edition's timeline, in milliseconds.",
"example": 754000,
"minimum": 0
},
"duration_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The edition's runtime in milliseconds as the last player reported\nit; null until one has.",
"example": 41400000,
"minimum": 0
},
"is_finished": {
"type": "boolean",
"description": "True once the caller reached the end of this edition.",
"example": false
},
"started_at": {
"type": "string",
"description": "When the caller first played it (RFC 3339).",
"example": "2026-11-19T08:15:00+00:00"
},
"finished_at": {
"type": [
"string",
"null"
],
"description": "When the caller last reached the end (RFC 3339).",
"example": null
},
"updated_at": {
"type": "string",
"description": "When the progress last changed (RFC 3339).",
"example": "2026-11-19T09:02:41+00:00"
}
}
},
"finished_now": {
"type": "boolean",
"description": "True when this report is the one that reached the edition's end:\nthe edition and its work are now finished for the caller.",
"example": false
}
}
}
Status 400: A length is past sixty days. As text/plain, when the body is not syntactically valid JSON.
{
"error": "position_ms must be at most 5184000000"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
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 session has no library user. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "clerk_sign_in_unavailable",
"message": "This library does not accept clerks on this address.",
"status": 403
}
Schema:
{
"anyOf": [
{
"anyOf": [
{
"anyOf": [
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
},
{
"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
}
}
}
]
},
{
"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
}
}
}
]
},
{
"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 session of the caller's (unknown_session).
{
"error": "unknown_session"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 409: The session was already closed (session_ended); open a new one.
{
"error": "session_ended"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 413: The body is over 1024 bytes.
{
"error": "the body is at most 1024 bytes"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: missing field `position_ms` at line 1 column 2
Schema:
A text/plain body: a string.
Status 500: The library could not be read or written.
{
"error": "the listening state could not be written"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
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.
Sends a session's last report and ends it.
Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).
Credentials: operatorToken or operatorSession or portalSession or clerkToken
idpathstringrequiredSession id fromPOST /api/playback/sessions.
application/json: PlaybackSyncBody
position_msinteger (int64)requiredPosition on the edition's timeline, in milliseconds from its start (at most sixty days). At least 0.listened_msinteger (int64)requiredMilliseconds listened since this session's last report, as the player counted them; left out reads as 0. At least 0.duration_msinteger (int64) or nullThe edition's whole runtime in milliseconds, when the player knows it; left out ornullkeeps the stored one. At least 0.
-
200The caller's progress after the report; the session is closed. Body:
SyncJson(application/json)2 fieldsprogressProgressJsonrequiredThe caller's progress after the report.finished_nowbooleanrequiredTrue when this report is the one that reached the edition's end: the edition and its work are now finished for the caller.
-
400A length is past sixty days. As
text/plain, when the body is not syntactically valid JSON. Body:ErrorMessage(application/json); string (text/plain)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
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 session has no library user. A signed-in user who must enroll a second factor first gets
mfa_enrollment_required. A library card sent over plain HTTP from another machine getstransport_insecure. A library card sent where the node API is not mounted getsclerk_sign_in_unavailable. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorMessageorErrorJsonorErrorJsonorErrorJson(application/json) -
404No such session of the caller's (
unknown_session). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
409The session was already closed (
session_ended). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
413The body is over 1024 bytes. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
500The library could not be read or written. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
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/playback/sessions/<id>/close' \
-X POST \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{"position_ms": 754000, "listened_ms": 15000}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/playback/sessions/<id>/close' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{"position_ms": 754000, "listened_ms": 15000}'
import requests
response = requests.post(
"http://127.0.0.1:8787/api/playback/sessions/<id>/close",
headers={"Authorization": "Bearer <operatorToken>"},
json={"position_ms": 754000, "listened_ms": 15000},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/playback/sessions/<id>/close", {
method: "POST",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({"position_ms": 754000, "listened_ms": 15000}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/playback/sessions/<id>/close")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({"position_ms": 754000, "listened_ms": 15000}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The caller's progress after the report; the session is closed.
{
"progress": {
"edition_id": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d",
"work_id": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b",
"position_ms": 754000,
"duration_ms": 41400000,
"is_finished": false,
"started_at": "2026-11-19T08:15:00+00:00",
"finished_at": null,
"updated_at": "2026-11-19T09:02:41+00:00"
},
"finished_now": false
}
Schema:
{
"type": "object",
"description": "`POST /api/playback/sessions/{id}/sync` and `.../close` answer.",
"required": [
"progress",
"finished_now"
],
"properties": {
"progress": {
"type": "object",
"description": "The caller's progress after the report.",
"required": [
"edition_id",
"position_ms",
"is_finished",
"started_at",
"updated_at"
],
"properties": {
"edition_id": {
"type": "string",
"description": "The edition.",
"example": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d"
},
"work_id": {
"type": [
"string",
"null"
],
"description": "The edition's work, when known: what a Continue listening shelf\nreads the title and cover from.",
"example": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b"
},
"position_ms": {
"type": "integer",
"format": "int64",
"description": "Position on the edition's timeline, in milliseconds.",
"example": 754000,
"minimum": 0
},
"duration_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The edition's runtime in milliseconds as the last player reported\nit; null until one has.",
"example": 41400000,
"minimum": 0
},
"is_finished": {
"type": "boolean",
"description": "True once the caller reached the end of this edition.",
"example": false
},
"started_at": {
"type": "string",
"description": "When the caller first played it (RFC 3339).",
"example": "2026-11-19T08:15:00+00:00"
},
"finished_at": {
"type": [
"string",
"null"
],
"description": "When the caller last reached the end (RFC 3339).",
"example": null
},
"updated_at": {
"type": "string",
"description": "When the progress last changed (RFC 3339).",
"example": "2026-11-19T09:02:41+00:00"
}
}
},
"finished_now": {
"type": "boolean",
"description": "True when this report is the one that reached the edition's end:\nthe edition and its work are now finished for the caller.",
"example": false
}
}
}
Status 400: A length is past sixty days. As text/plain, when the body is not syntactically valid JSON.
{
"error": "position_ms must be at most 5184000000"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
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 session has no library user. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "clerk_sign_in_unavailable",
"message": "This library does not accept clerks on this address.",
"status": 403
}
Schema:
{
"anyOf": [
{
"anyOf": [
{
"anyOf": [
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
},
{
"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
}
}
}
]
},
{
"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
}
}
}
]
},
{
"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 session of the caller's (unknown_session).
{
"error": "unknown_session"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 409: The session was already closed (session_ended).
{
"error": "session_ended"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 413: The body is over 1024 bytes.
{
"error": "the body is at most 1024 bytes"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: missing field `position_ms` at line 1 column 2
Schema:
A text/plain body: a string.
Status 500: The library could not be read or written.
{
"error": "the listening state could not be written"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
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.
Streams one track of a play session.
Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).
Credentials: operatorToken or operatorSession or portalSession or clerkToken
idpathstringrequiredSession id fromPOST /api/playback/sessions.indexpathinteger (int32)requiredThe track'sindexin the session'stracks.Rangeheaderstring or nullOne byte range (bytes=A-B,bytes=A-orbytes=-N); anything else reads the whole file.
- 200The whole track. Body:
BinaryBody(audio/mp4);BinaryBody(audio/mpeg);BinaryBody(audio/aac);BinaryBody(audio/flac);BinaryBody(audio/ogg);BinaryBody(audio/wav);BinaryBody(application/octet-stream) - 206The requested byte range, with
Content-Range. Body:BinaryBody(audio/mp4);BinaryBody(audio/mpeg);BinaryBody(audio/aac);BinaryBody(audio/flac);BinaryBody(audio/ogg);BinaryBody(audio/wav);BinaryBody(application/octet-stream) -
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 session has no library user. A signed-in user who must enroll a second factor first gets
mfa_enrollment_required. A library card sent over plain HTTP from another machine getstransport_insecure. A library card sent where the node API is not mounted getsclerk_sign_in_unavailable. Body:ErrorMessageorErrorJsonorErrorJsonorErrorJson(application/json) -
404No such session of the caller's (
unknown_session), or the index names no track of it (unknown_track). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
409The session no longer streams (
session_ended): it was closed, sat a day without a report, the caller may no longer play the edition, or the edition's files changed. Open a new session. Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
416The range starts at or past the end of the file (
range_not_satisfiable);Content-Rangestates the size. Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
421Another node opened this session (
misdirected). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
500The library could not be read. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 503Storage is unavailable; retry (
unavailable). When the sign-in could not be checked because the library did not answer in time, the answer issession_check_unavailableinstead, withRetry-After; ask again rather than treating the caller as signed out. Body:ErrorMessageorErrorJson(application/json) - 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/playback/sessions/<id>/tracks/<index>' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/playback/sessions/<id>/tracks/<index>' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/playback/sessions/<id>/tracks/<index>",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/playback/sessions/<id>/tracks/<index>", {
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/playback/sessions/<id>/tracks/<index>")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The whole track. The body is binary (audio/mp4).
Schema:
A audio/mp4 body: binary bytes.
Status 206: The requested byte range, with Content-Range. The body is binary (audio/mp4).
Schema:
A audio/mp4 body: binary bytes.
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 session has no library user. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable.
{
"error": "clerk_sign_in_unavailable",
"message": "This library does not accept clerks on this address.",
"status": 403
}
Schema:
{
"anyOf": [
{
"anyOf": [
{
"anyOf": [
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
},
{
"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
}
}
}
]
},
{
"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
}
}
}
]
},
{
"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 session of the caller's (unknown_session), or the index names no track of it (unknown_track).
{
"error": "unknown_track"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 409: The session no longer streams (session_ended): it was closed, sat a day without a report, the caller may no longer play the edition, or the edition's files changed. Open a new session.
{
"error": "session_ended"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 416: The range starts at or past the end of the file (range_not_satisfiable); Content-Range states the size.
{
"error": "range_not_satisfiable"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 421: Another node opened this session (misdirected).
{
"error": "misdirected"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 500: The library could not be read.
{
"error": "the library could not be read"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 503: Storage is unavailable; retry (unavailable). When the sign-in could not be checked because the library did not answer in time, the answer is session_check_unavailable instead, with Retry-After; ask again rather than treating the caller as signed out.
{
"error": "session_check_unavailable",
"message": "Your sign-in could not be checked yet. Try again in a moment.",
"status": 503
}
Schema:
{
"anyOf": [
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
},
{
"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.
Lists the caller's progress, most recently played first.
Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).
Credentials: operatorToken or operatorSession or portalSession or clerkToken
limitqueryinteger (int64)Rows per page: 1 to 100, default 20.cursorquerystringnext_cursorof the page before.include_finishedquerybooleanTrue also lists editions the caller finished; default false (Continue listening).
-
200A page of the caller's progress. Body:
ProgressPage(application/json)2 fieldsitemsarray ofProgressJsonrequiredThe caller's progress rows, most recently played first. Editions their patron scope no longer shows are left out, so a page can be shorter thanlimitwith more to come.next_cursorstring or nullCursor of the next page; absent on the last.
-
400The cursor is not one this route returned. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The session ended. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 403The session has no library user. A signed-in user who must enroll a second factor first gets
mfa_enrollment_required. A library card sent over plain HTTP from another machine getstransport_insecure. A library card sent where the node API is not mounted getsclerk_sign_in_unavailable. Body:ErrorMessageorErrorJsonorErrorJsonorErrorJson(application/json) -
500The library could not be read. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
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/playback/progress' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/playback/progress' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/playback/progress",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/playback/progress", {
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/playback/progress")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: A page of the caller's progress.
{
"items": [
{
"edition_id": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d",
"work_id": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b",
"position_ms": 754000,
"duration_ms": 41400000,
"is_finished": false,
"started_at": "2026-11-19T08:15:00+00:00",
"finished_at": null,
"updated_at": "2026-11-19T09:02:41+00:00"
}
],
"next_cursor": "MjAyNi0xMS0xOVQwOTowMjo0MSswMDowMHw1ZDJj"
}
Schema:
{
"type": "object",
"description": "`GET /api/playback/progress` answer.",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"description": "One person's progress in one edition.",
"required": [
"edition_id",
"position_ms",
"is_finished",
"started_at",
"updated_at"
],
"properties": {
"edition_id": {
"type": "string",
"description": "The edition.",
"example": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d"
},
"work_id": {
"type": [
"string",
"null"
],
"description": "The edition's work, when known: what a Continue listening shelf\nreads the title and cover from.",
"example": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b"
},
"position_ms": {
"type": "integer",
"format": "int64",
"description": "Position on the edition's timeline, in milliseconds.",
"example": 754000,
"minimum": 0
},
"duration_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The edition's runtime in milliseconds as the last player reported\nit; null until one has.",
"example": 41400000,
"minimum": 0
},
"is_finished": {
"type": "boolean",
"description": "True once the caller reached the end of this edition.",
"example": false
},
"started_at": {
"type": "string",
"description": "When the caller first played it (RFC 3339).",
"example": "2026-11-19T08:15:00+00:00"
},
"finished_at": {
"type": [
"string",
"null"
],
"description": "When the caller last reached the end (RFC 3339).",
"example": null
},
"updated_at": {
"type": "string",
"description": "When the progress last changed (RFC 3339).",
"example": "2026-11-19T09:02:41+00:00"
}
}
},
"description": "The caller's progress rows, most recently played first. Editions\ntheir patron scope no longer shows are left out, so a page can be\nshorter than `limit` with more to come."
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": "Cursor of the next page; absent on the last.",
"example": "MjAyNi0xMS0xOVQwOTowMjo0MSswMDowMHw1ZDJj"
}
}
}
Status 400: The cursor is not one this route returned.
{
"error": "invalid page cursor"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The session ended.
{
"error": "sign in again"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 403: The session has no library user. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable.
{
"error": "clerk_sign_in_unavailable",
"message": "This library does not accept clerks on this address.",
"status": 403
}
Schema:
{
"anyOf": [
{
"anyOf": [
{
"anyOf": [
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
},
{
"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
}
}
}
]
},
{
"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
}
}
}
]
},
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
]
}
Status 500: The library could not be read.
{
"error": "the library could not be read"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
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.
Sets the caller's progress in an edition outright: Mark finished, Start over, or a place chosen with no session open.
Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).
Credentials: operatorToken or operatorSession or portalSession or clerkToken
edition_idpathstringrequiredEdition id.
application/json: ProgressEditBody
position_msinteger (int64) or nullPosition in milliseconds (at most sixty days). At least 0.duration_msinteger (int64) or nullThe edition's runtime in milliseconds, when the page knows it. At least 0.is_finishedboolean or nullTrue marks the edition and its work finished; false clears the edition's flag (the work's stays, and is changed with the work's own state). Left out, the position decides.
-
200The caller's progress after the change. Body:
SyncJson(application/json)2 fieldsprogressProgressJsonrequiredThe caller's progress after the report.finished_nowbooleanrequiredTrue when this report is the one that reached the edition's end: the edition and its work are now finished for the caller.
-
400A length is past sixty days. As
text/plain, when the body is not syntactically valid JSON. Body:ErrorMessage(application/json); string (text/plain)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The session ended. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 403The session has no library user. A signed-in user who must enroll a second factor first gets
mfa_enrollment_required. A library card sent over plain HTTP from another machine getstransport_insecure. A library card sent where the node API is not mounted getsclerk_sign_in_unavailable. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorMessageorErrorJsonorErrorJsonorErrorJson(application/json) -
404No such edition. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
413The body is over 4096 bytes. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
500The library could not be read or written. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
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/playback/progress/<edition_id>' \
-X PUT \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/playback/progress/<edition_id>' `
-Method Put `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.put(
"http://127.0.0.1:8787/api/playback/progress/<edition_id>",
headers={"Authorization": "Bearer <operatorToken>"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/playback/progress/<edition_id>", {
method: "PUT",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.put("http://127.0.0.1:8787/api/playback/progress/<edition_id>")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The caller's progress after the change.
{
"progress": {
"edition_id": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d",
"work_id": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b",
"position_ms": 754000,
"duration_ms": 41400000,
"is_finished": false,
"started_at": "2026-11-19T08:15:00+00:00",
"finished_at": null,
"updated_at": "2026-11-19T09:02:41+00:00"
},
"finished_now": false
}
Schema:
{
"type": "object",
"description": "`POST /api/playback/sessions/{id}/sync` and `.../close` answer.",
"required": [
"progress",
"finished_now"
],
"properties": {
"progress": {
"type": "object",
"description": "The caller's progress after the report.",
"required": [
"edition_id",
"position_ms",
"is_finished",
"started_at",
"updated_at"
],
"properties": {
"edition_id": {
"type": "string",
"description": "The edition.",
"example": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d"
},
"work_id": {
"type": [
"string",
"null"
],
"description": "The edition's work, when known: what a Continue listening shelf\nreads the title and cover from.",
"example": "0b8f6a52-3c1d-4e2f-9a7b-6c5d4e3f2a1b"
},
"position_ms": {
"type": "integer",
"format": "int64",
"description": "Position on the edition's timeline, in milliseconds.",
"example": 754000,
"minimum": 0
},
"duration_ms": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The edition's runtime in milliseconds as the last player reported\nit; null until one has.",
"example": 41400000,
"minimum": 0
},
"is_finished": {
"type": "boolean",
"description": "True once the caller reached the end of this edition.",
"example": false
},
"started_at": {
"type": "string",
"description": "When the caller first played it (RFC 3339).",
"example": "2026-11-19T08:15:00+00:00"
},
"finished_at": {
"type": [
"string",
"null"
],
"description": "When the caller last reached the end (RFC 3339).",
"example": null
},
"updated_at": {
"type": "string",
"description": "When the progress last changed (RFC 3339).",
"example": "2026-11-19T09:02:41+00:00"
}
}
},
"finished_now": {
"type": "boolean",
"description": "True when this report is the one that reached the edition's end:\nthe edition and its work are now finished for the caller.",
"example": false
}
}
}
Status 400: A length is past sixty days. As text/plain, when the body is not syntactically valid JSON.
{
"error": "position_ms must be at most 5184000000"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The session ended.
{
"error": "sign in again"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 403: The session has no library user. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "clerk_sign_in_unavailable",
"message": "This library does not accept clerks on this address.",
"status": 403
}
Schema:
{
"anyOf": [
{
"anyOf": [
{
"anyOf": [
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
},
{
"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
}
}
}
]
},
{
"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
}
}
}
]
},
{
"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 edition.
{
"error": "edition 5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d not found"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 413: The body is over 4096 bytes.
{
"error": "the body is at most 4096 bytes"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: is_finished: invalid type: integer `1`, expected a boolean at line 1 column 16
Schema:
A text/plain body: a string.
Status 500: The library could not be read or written.
{
"error": "the listening state could not be written"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
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.
Forgets the caller's progress in an edition. The work's finished flag is left as it is.
Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).
Credentials: operatorToken or operatorSession or portalSession or clerkToken
edition_idpathstringrequiredEdition id.
- 204The caller has no progress in the edition now. No body.
-
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 session has no library user. A signed-in user who must enroll a second factor first gets
mfa_enrollment_required. A library card sent over plain HTTP from another machine getstransport_insecure. A library card sent where the node API is not mounted getsclerk_sign_in_unavailable. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorMessageorErrorJsonorErrorJsonorErrorJson(application/json) -
500The library could not be written. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
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/playback/progress/<edition_id>' \
-X DELETE \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/playback/progress/<edition_id>' `
-Method Delete `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.delete(
"http://127.0.0.1:8787/api/playback/progress/<edition_id>",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/playback/progress/<edition_id>", {
method: "DELETE",
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.delete("http://127.0.0.1:8787/api/playback/progress/<edition_id>")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 204: The caller has no progress in the edition now. No body.
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 session has no library user. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "clerk_sign_in_unavailable",
"message": "This library does not accept clerks on this address.",
"status": 403
}
Schema:
{
"anyOf": [
{
"anyOf": [
{
"anyOf": [
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
},
{
"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
}
}
}
]
},
{
"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
}
}
}
]
},
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
]
}
Status 500: The library could not be written.
{
"error": "the listening state could not be written"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
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.
Changes one of the caller's bookmarks.
Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).
Credentials: operatorToken or operatorSession or portalSession or clerkToken
idpathstringrequiredBookmark id.
application/json: BookmarkEditBody
position_msinteger (int64) or nullThe new place, in milliseconds. At least 0.titlestring or nullThe new note; an empty string clears it.
-
200The bookmark after the change. Body:
BookmarkJson(application/json)5 fieldsidstringrequiredBookmark id.edition_idstringrequiredThe edition it is in.position_msinteger (int64)requiredThe marked place, in milliseconds from the edition's start. At least 0.titlestringrequiredThe caller's note; may be empty.created_atstringrequiredWhen it was made (RFC 3339).
-
400The position is past sixty days, or the title is too long or has control characters. As
text/plain, when the body is not syntactically valid JSON. Body:ErrorMessage(application/json); string (text/plain)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
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 session has no library user. A signed-in user who must enroll a second factor first gets
mfa_enrollment_required. A library card sent over plain HTTP from another machine getstransport_insecure. A library card sent where the node API is not mounted getsclerk_sign_in_unavailable. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorMessageorErrorJsonorErrorJsonorErrorJson(application/json) -
404No such bookmark of the caller's (
unknown_bookmark). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
413The body is over 4096 bytes. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
500The library could not be written. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
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/playback/bookmarks/<id>' \
-X PUT \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/playback/bookmarks/<id>' `
-Method Put `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.put(
"http://127.0.0.1:8787/api/playback/bookmarks/<id>",
headers={"Authorization": "Bearer <operatorToken>"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/playback/bookmarks/<id>", {
method: "PUT",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.put("http://127.0.0.1:8787/api/playback/bookmarks/<id>")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The bookmark after the change.
{
"id": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
"edition_id": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d",
"position_ms": 754000,
"title": "The storm",
"created_at": "2026-11-19T09:02:41+00:00"
}
Schema:
{
"type": "object",
"description": "A place the caller marked in an edition.",
"required": [
"id",
"edition_id",
"position_ms",
"title",
"created_at"
],
"properties": {
"id": {
"type": "string",
"description": "Bookmark id.",
"example": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d"
},
"edition_id": {
"type": "string",
"description": "The edition it is in.",
"example": "5d2c8e1a-7b3f-4a6e-9c0d-1e2f3a4b5c6d"
},
"position_ms": {
"type": "integer",
"format": "int64",
"description": "The marked place, in milliseconds from the edition's start.",
"example": 754000,
"minimum": 0
},
"title": {
"type": "string",
"description": "The caller's note; may be empty.",
"example": "The storm"
},
"created_at": {
"type": "string",
"description": "When it was made (RFC 3339).",
"example": "2026-11-19T09:02:41+00:00"
}
}
}
Status 400: The position is past sixty days, or the title is too long or has control characters. As text/plain, when the body is not syntactically valid JSON.
{
"error": "title must be at most 200 bytes"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
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 session has no library user. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "clerk_sign_in_unavailable",
"message": "This library does not accept clerks on this address.",
"status": 403
}
Schema:
{
"anyOf": [
{
"anyOf": [
{
"anyOf": [
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
},
{
"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
}
}
}
]
},
{
"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
}
}
}
]
},
{
"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 bookmark of the caller's (unknown_bookmark).
{
"error": "unknown_bookmark"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 413: The body is over 4096 bytes.
{
"error": "the body is at most 4096 bytes"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: title: invalid type: integer `1`, expected a string at line 1 column 10
Schema:
A text/plain body: a string.
Status 500: The library could not be written.
{
"error": "the listening state could not be written"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
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.
Removes one of the caller's bookmarks.
Access: The operator, or any library session, including a library card (refused with 403 transport_insecure off loopback without TLS, or clerk_sign_in_unavailable where remote installs are not served).
Credentials: operatorToken or operatorSession or portalSession or clerkToken
idpathstringrequiredBookmark id.
- 204The bookmark is gone. No body.
-
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 session has no library user. A signed-in user who must enroll a second factor first gets
mfa_enrollment_required. A library card sent over plain HTTP from another machine getstransport_insecure. A library card sent where the node API is not mounted getsclerk_sign_in_unavailable. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorMessageorErrorJsonorErrorJsonorErrorJson(application/json) -
404No such bookmark of the caller's (
unknown_bookmark). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
500The library could not be written. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
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/playback/bookmarks/<id>' \
-X DELETE \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/playback/bookmarks/<id>' `
-Method Delete `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.delete(
"http://127.0.0.1:8787/api/playback/bookmarks/<id>",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/playback/bookmarks/<id>", {
method: "DELETE",
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.delete("http://127.0.0.1:8787/api/playback/bookmarks/<id>")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 204: The bookmark is gone. No body.
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 session has no library user. A signed-in user who must enroll a second factor first gets mfa_enrollment_required. A library card sent over plain HTTP from another machine gets transport_insecure. A library card sent where the node API is not mounted gets clerk_sign_in_unavailable. A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "clerk_sign_in_unavailable",
"message": "This library does not accept clerks on this address.",
"status": 403
}
Schema:
{
"anyOf": [
{
"anyOf": [
{
"anyOf": [
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
},
{
"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
}
}
}
]
},
{
"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
}
}
}
]
},
{
"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 bookmark of the caller's (unknown_bookmark).
{
"error": "unknown_bookmark"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 500: The library could not be written.
{
"error": "the listening state could not be written"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
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