Accounts
Store accounts a library user connects (the Accounts page).
Back to the web API reference.
Redeems a claim ticket, optionally setting a first password, and sets the session cookie.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
application/json: RedeemBody
ticketstringrequiredRaw claim-ticket token to redeem into a portal session.noncestringrequiredBrowser-generated one-time nonce persisted across HTTP retries.passwordstring or nullRequired when the linked local user has no password (invite / reset).
-
200Signed in; the response sets the portal session cookie. Body:
PortalOk(application/json)1 fieldokbooleanrequiredAlwaystrue.
-
400The ticket or nonce is invalid, used or expired, the ticket's integration is not deployed here, a first local claim needs a password of at least 8 characters, or the library refused the claim (the body carries its message). As
text/plain, when the body is not syntactically valid JSON. Body:PortalErrorBody(application/json); string (text/plain)1 fielderrorstringrequiredOperator-facing error text (no structured code).
- 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) -
503The library's atomic redeem did not answer in time or its reply was lost; redeem again with the same ticket and nonce. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/portal/redeem' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"ticket": "3f9a1c7e5b2d4a6f8e0c1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f2a4c6e8b0d1f3a", "nonce": "a7c3e9f1b5d2486e0f3a9c7b1d5e2f8a4c6b0d9e3f7a1c5b8d2e6f0a4c8b1d3e"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/portal/redeem' `
-Method Post `
-ContentType 'application/json' `
-Body '{"ticket": "3f9a1c7e5b2d4a6f8e0c1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f2a4c6e8b0d1f3a", "nonce": "a7c3e9f1b5d2486e0f3a9c7b1d5e2f8a4c6b0d9e3f7a1c5b8d2e6f0a4c8b1d3e"}'
import requests
response = requests.post(
"http://127.0.0.1:8787/api/portal/redeem",
json={"ticket": "3f9a1c7e5b2d4a6f8e0c1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f2a4c6e8b0d1f3a", "nonce": "a7c3e9f1b5d2486e0f3a9c7b1d5e2f8a4c6b0d9e3f7a1c5b8d2e6f0a4c8b1d3e"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/portal/redeem", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({"ticket": "3f9a1c7e5b2d4a6f8e0c1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f2a4c6e8b0d1f3a", "nonce": "a7c3e9f1b5d2486e0f3a9c7b1d5e2f8a4c6b0d9e3f7a1c5b8d2e6f0a4c8b1d3e"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/portal/redeem")
.json(&serde_json::json!({"ticket": "3f9a1c7e5b2d4a6f8e0c1b3d5f7a9c2e4b6d8f0a1c3e5b7d9f2a4c6e8b0d1f3a", "nonce": "a7c3e9f1b5d2486e0f3a9c7b1d5e2f8a4c6b0d9e3f7a1c5b8d2e6f0a4c8b1d3e"}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Signed in; the response sets the portal session cookie.
{
"ok": true
}
Schema:
{
"type": "object",
"description": "JSON body of a portal route that has nothing to report beyond success.",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean",
"description": "Always `true`.",
"example": true
}
}
}
Status 400: The ticket or nonce is invalid, used or expired, the ticket's integration is not deployed here, a first local claim needs a password of at least 8 characters, or the library refused the claim (the body carries its message). As text/plain, when the body is not syntactically valid JSON.
{
"error": "integration `audiobookshelf` is not deployed on this host"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
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 `ticket` at line 1 column 2
Schema:
A text/plain body: a string.
Status 503: The library's atomic redeem did not answer in time or its reply was lost; redeem again with the same ticket and nonce.
{
"error": "deadline_exceeded: host RPC deadline elapsed"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Authenticates against an enabled integration and mints a portal session.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
application/json: IntegrationLoginBody
providerstringrequiredIntegration plugin id (must be enabled in config).usernamestringrequiredProvider login name forwarded toauthenticate_user.passwordstringrequiredProvider password; never logged.
-
200Signed in through the integration; the response sets the portal session cookie. Body:
PortalOk(application/json)1 fieldokbooleanrequiredAlwaystrue.
-
400The integration is not deployed here, does not take a username and password, or refused them, or the library database refused the step. As
text/plain, when the body is not syntactically valid JSON. Body:PortalErrorBody(application/json); string (text/plain)1 fielderrorstringrequiredOperator-facing error text (no structured code).
- 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) - 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/portal/login/integration' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"provider": "audiobookshelf", "username": "dana", "password": "correct horse battery staple"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/portal/login/integration' `
-Method Post `
-ContentType 'application/json' `
-Body '{"provider": "audiobookshelf", "username": "dana", "password": "correct horse battery staple"}'
import requests
response = requests.post(
"http://127.0.0.1:8787/api/portal/login/integration",
json={"provider": "audiobookshelf", "username": "dana", "password": "correct horse battery staple"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/portal/login/integration", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({"provider": "audiobookshelf", "username": "dana", "password": "correct horse battery staple"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/portal/login/integration")
.json(&serde_json::json!({"provider": "audiobookshelf", "username": "dana", "password": "correct horse battery staple"}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Signed in through the integration; the response sets the portal session cookie.
{
"ok": true
}
Schema:
{
"type": "object",
"description": "JSON body of a portal route that has nothing to report beyond success.",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean",
"description": "Always `true`.",
"example": true
}
}
}
Status 400: The integration is not deployed here, does not take a username and password, or refused them, or the library database refused the step. As text/plain, when the body is not syntactically valid JSON.
{
"error": "ORM / database plugin error: Execution Error: error returned from database: database is locked"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
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 `provider` at line 1 column 2
Schema:
A text/plain body: a string.
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Revokes the portal session row and clears the session cookie.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
-
200Signed out; the cookie is cleared. Body:
PortalOk(application/json)1 fieldokbooleanrequiredAlwaystrue.
-
403A write sent with a session cookie but without a matching
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/portal/logout' \
-X POST
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/portal/logout' `
-Method Post
import requests
response = requests.post("http://127.0.0.1:8787/api/portal/logout")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/portal/logout", {
method: "POST",
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/portal/logout")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Signed out; the cookie is cleared.
{
"ok": true
}
Schema:
{
"type": "object",
"description": "JSON body of a portal route that has nothing to report beyond success.",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean",
"description": "Always `true`.",
"example": true
}
}
}
Status 403: A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "forbidden",
"message": "You do not have access to this resource.",
"status": 403
}
Schema:
{
"type": "object",
"description": "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 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Returns the signed-in portal identity, or 401 when the cookie is missing or expired.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: portalSession
-
200The signed-in identity. Body:
MeResponse(application/json)3 fieldsproviderstringrequiredIdentity provider id (localor an integration plugin id).external_user_idstringrequiredProvider-scoped user id stored on the portal identity row.labelstring or nullOptional display label from the identity row.
-
400The library database refused the lookup. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
401The caller is not signed in, or the portal session expired. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/portal/me' \
-b 'bookclerk_portal_session=<portalSession>'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/portal/me' `
-WebSession $session
import requests
response = requests.get(
"http://127.0.0.1:8787/api/portal/me",
headers={"Cookie": "bookclerk_portal_session=<portalSession>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/portal/me", {
headers: { Cookie: "bookclerk_portal_session=<portalSession>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/api/portal/me")
.header("Cookie", "bookclerk_portal_session=<portalSession>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The signed-in identity.
{
"provider": "local",
"external_user_id": "user:7",
"label": "Dana Reader"
}
Schema:
{
"type": "object",
"description": "JSON body for `GET /me`.",
"required": [
"provider",
"external_user_id"
],
"properties": {
"provider": {
"type": "string",
"description": "Identity provider id (`local` or an integration plugin id).",
"example": "local"
},
"external_user_id": {
"type": "string",
"description": "Provider-scoped user id stored on the portal identity row.",
"example": "user:7"
},
"label": {
"type": [
"string",
"null"
],
"description": "Optional display label from the identity row.",
"example": "Dana Reader"
}
}
}
Status 400: The library database refused the lookup.
{
"error": "ORM / database plugin error: Execution Error: error returned from database: database is locked"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 401: The caller is not signed in, or the portal session expired.
{
"error": "not signed in"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Lists the deployed content sources (one per plugin, through its default instance) with portal auth mode, config options, and brand colors.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
-
200Deployed content sources. Body:
SourcesResponse(application/json)1 fieldsourcesarray ofSourceInforequiredEnabled storefronts the SPA may offer for connect / login.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/portal/sources'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/portal/sources'
import requests
response = requests.get("http://127.0.0.1:8787/api/portal/sources")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/portal/sources");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/api/portal/sources").await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Deployed content sources.
{
"sources": [
{
"id": "libro",
"name": "Libro.fm",
"auth": "password",
"config_options": [
{
"key": "container",
"label": "Container",
"values": []
}
],
"brand": {
"bg": "#1F4E3D",
"fg": "#F4F1EA",
"accent": "#2F6B53",
"logo": "/api/images/aHR0cHM6Ly93d3cuZ29vZ2xlLmNvbS9zMi9mYXZpY29ucz9kb21haW49bGlicm8uZm0mc3o9MTI4.N14rqh66Bok9-eCqJKBNoQ"
}
}
]
}
Schema:
{
"type": "object",
"description": "JSON body for `GET /sources`.",
"required": [
"sources"
],
"properties": {
"sources": {
"type": "array",
"items": {
"type": "object",
"description": "One enabled storefront as shown on the portal Accounts page.",
"required": [
"id",
"name",
"auth",
"brand"
],
"properties": {
"id": {
"type": "string",
"description": "Source plugin id (`audible`, `libro`, …).",
"example": "libro"
},
"name": {
"type": "string",
"description": "Operator-facing storefront name.",
"example": "Libro.fm"
},
"auth": {
"type": "string",
"description": "Portal auth mode (`password` or `oauth`).",
"example": "password"
},
"config_options": {
"type": "array",
"items": {
"type": "object",
"description": "One storefront config option (key, label, allowed values).",
"required": [
"key",
"label",
"values"
],
"properties": {
"key": {
"type": "string",
"description": "Config table key (for example `container`).",
"example": "container"
},
"label": {
"type": "string",
"description": "Operator-facing option name.",
"example": "Container"
},
"values": {
"type": "array",
"items": {
"type": "object",
"description": "One allowed value for a storefront config option.",
"required": [
"id",
"label"
],
"properties": {
"id": {
"type": "string",
"description": "Stored option value (for example `m4b`).",
"example": "m4b"
},
"label": {
"type": "string",
"description": "Operator-facing value label.",
"example": "M4B"
}
}
},
"description": "Allowed values the SPA may offer for this option."
}
}
},
"description": "Store-specific knobs the SPA can present (omitted when empty)."
},
"brand": {
"type": "object",
"description": "Storefront colors and logo href for the Accounts UI.",
"required": [
"bg",
"fg",
"accent",
"logo"
],
"properties": {
"bg": {
"type": "string",
"description": "Background color (`#RRGGBB`).",
"example": "#1F4E3D"
},
"fg": {
"type": "string",
"description": "Foreground / text color (`#RRGGBB`).",
"example": "#F4F1EA"
},
"accent": {
"type": "string",
"description": "Accent color (`#RRGGBB`).",
"example": "#2F6B53"
},
"logo": {
"type": "string",
"description": "Same-origin logo image (a 128 px copy of the brand's icon), or empty\nwhen there is none.",
"example": "/api/images/aHR0cHM6Ly93d3cuZ29vZ2xlLmNvbS9zMi9mYXZpY29ucz9kb21haW49bGlicm8uZm0mc3o9MTI4.N14rqh66Bok9-eCqJKBNoQ"
}
}
}
}
},
"description": "Enabled storefronts the SPA may offer for connect / login."
}
}
}
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Connects a password storefront, upserts the account, and links it to the signed-in identity.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: portalSession
idpathstringrequiredSource plugin id.
application/json: PasswordLoginBody
emailstringrequiredStore account email / username.passwordstringrequiredStore account password; never logged.
-
200The account was connected. Body:
SourceConnected(application/json)4 fieldsokbooleanrequiredAlwaystrue.account_idstringrequiredThe store's id for the account.sourcestringrequiredThe source's id, as listed byGET /api/portal/sources.plugin_keystringrequiredThe plugin that owns the account.
-
400No deployed source has that id, the source signs in through OAuth, or the store or the library database refused the step (the body carries its message). As
text/plain, when the body is not syntactically valid JSON. Body:PortalErrorBody(application/json); string (text/plain)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
401The caller is not signed in, or the portal session expired. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
403The library's administrator has not allowed the caller to connect store accounts here. A write sent with a session cookie but without a matching
OriginorRefereris refused. Body:PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
409The account has no saved sign-in when the login links it: a refused login of the same store account, or a revoke, took it back meanwhile (or the store's login saved none). Signing in again connects it. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
- 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) - 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/portal/sources/<id>/login' \
-X POST \
-b 'bookclerk_portal_session=<portalSession>' \
-H 'Origin: http://127.0.0.1:8787' \
-H 'Content-Type: application/json' \
-d '{"email": "reader@example.com", "password": "correct horse battery staple"}'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/portal/sources/<id>/login' `
-Method Post `
-WebSession $session `
-Headers @{ Origin = 'http://127.0.0.1:8787' } `
-ContentType 'application/json' `
-Body '{"email": "reader@example.com", "password": "correct horse battery staple"}'
import requests
response = requests.post(
"http://127.0.0.1:8787/api/portal/sources/<id>/login",
headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
json={"email": "reader@example.com", "password": "correct horse battery staple"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/portal/sources/<id>/login", {
method: "POST",
headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787", "Content-Type": "application/json" },
body: JSON.stringify({"email": "reader@example.com", "password": "correct horse battery staple"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/portal/sources/<id>/login")
.header("Cookie", "bookclerk_portal_session=<portalSession>")
.header("Origin", "http://127.0.0.1:8787")
.json(&serde_json::json!({"email": "reader@example.com", "password": "correct horse battery staple"}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The account was connected.
{
"ok": true,
"account_id": "reader@example.com",
"source": "libro",
"plugin_key": "bookclerk:source-libro"
}
Schema:
{
"type": "object",
"description": "JSON body of a connected store account.",
"required": [
"ok",
"account_id",
"source",
"plugin_key"
],
"properties": {
"ok": {
"type": "boolean",
"description": "Always `true`.",
"example": true
},
"account_id": {
"type": "string",
"description": "The store's id for the account.",
"example": "reader@example.com"
},
"source": {
"type": "string",
"description": "The source's id, as listed by `GET /api/portal/sources`.",
"example": "libro"
},
"plugin_key": {
"type": "string",
"description": "The plugin that owns the account.",
"example": "bookclerk:source-libro"
}
}
}
Status 400: No deployed source has that id, the source signs in through OAuth, or the store or the library database refused the step (the body carries its message). As text/plain, when the body is not syntactically valid JSON.
{
"error": "ORM / database plugin error: Execution Error: error returned from database: database is locked"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 401: The caller is not signed in, or the portal session expired.
{
"error": "not signed in"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 403: The library's administrator has not allowed the caller to connect store accounts here. A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "this library's administrator hasn't allowed you to connect store accounts here"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 409: The account has no saved sign-in when the login links it: a refused login of the same store account, or a revoke, took it back meanwhile (or the store's login saved none). Signing in again connects it.
{
"error": "this account has no saved sign-in (it was disconnected while the sign-in finished); sign in again"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
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 `email` at line 1 column 2
Schema:
A text/plain body: a string.
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Starts interactive OAuth for an OAuth storefront and returns the browser login URL.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: portalSession
idpathstringrequiredSource plugin id.
-
200The browser login URL. Body:
OAuthStartUrl(application/json)1 fieldurlstringrequiredThe store's login page, bound to this sign-in.
-
400No deployed source has that id, the source signs in with a password, the store produced no login URL in time, the login stopped before it produced one, or the library database refused the step. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
401The caller is not signed in, or the portal session expired. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
403The library's administrator has not allowed the caller to connect store accounts here. A write sent with a session cookie but without a matching
OriginorRefereris refused. Body:PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/portal/sources/<id>/oauth/start' \
-X POST \
-b 'bookclerk_portal_session=<portalSession>' \
-H 'Origin: http://127.0.0.1:8787'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/portal/sources/<id>/oauth/start' `
-Method Post `
-WebSession $session `
-Headers @{ Origin = 'http://127.0.0.1:8787' }
import requests
response = requests.post(
"http://127.0.0.1:8787/api/portal/sources/<id>/oauth/start",
headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/portal/sources/<id>/oauth/start", {
method: "POST",
headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/portal/sources/<id>/oauth/start")
.header("Cookie", "bookclerk_portal_session=<portalSession>")
.header("Origin", "http://127.0.0.1:8787")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The browser login URL.
{
"url": "https://www.amazon.com/ap/signin?openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0&…"
}
Schema:
{
"type": "object",
"description": "JSON body of an OAuth start: the browser login URL to open.",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"description": "The store's login page, bound to this sign-in.",
"example": "https://www.amazon.com/ap/signin?openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0&…"
}
}
}
Status 400: No deployed source has that id, the source signs in with a password, the store produced no login URL in time, the login stopped before it produced one, or the library database refused the step.
{
"error": "ORM / database plugin error: Execution Error: error returned from database: database is locked"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 401: The caller is not signed in, or the portal session expired.
{
"error": "not signed in"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 403: The library's administrator has not allowed the caller to connect store accounts here. A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "this library's administrator hasn't allowed you to connect store accounts here"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Deprecated.
Legacy POST /libro/login alias that forwards to the Libro password-login handler.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: portalSession
application/json: PasswordLoginBody
emailstringrequiredStore account email / username.passwordstringrequiredStore account password; never logged.
-
200The account was connected. Body:
SourceConnected(application/json)4 fieldsokbooleanrequiredAlwaystrue.account_idstringrequiredThe store's id for the account.sourcestringrequiredThe source's id, as listed byGET /api/portal/sources.plugin_keystringrequiredThe plugin that owns the account.
-
400The Libro.fm source is not deployed here, or the store or the library database refused the step (the body carries its message). As
text/plain, when the body is not syntactically valid JSON. Body:PortalErrorBody(application/json); string (text/plain)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
401The caller is not signed in, or the portal session expired. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
403The library's administrator has not allowed the caller to connect store accounts here. A write sent with a session cookie but without a matching
OriginorRefereris refused. Body:PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
- 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) - 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/portal/libro/login' \
-X POST \
-b 'bookclerk_portal_session=<portalSession>' \
-H 'Origin: http://127.0.0.1:8787' \
-H 'Content-Type: application/json' \
-d '{"email": "reader@example.com", "password": "correct horse battery staple"}'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/portal/libro/login' `
-Method Post `
-WebSession $session `
-Headers @{ Origin = 'http://127.0.0.1:8787' } `
-ContentType 'application/json' `
-Body '{"email": "reader@example.com", "password": "correct horse battery staple"}'
import requests
response = requests.post(
"http://127.0.0.1:8787/api/portal/libro/login",
headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
json={"email": "reader@example.com", "password": "correct horse battery staple"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/portal/libro/login", {
method: "POST",
headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787", "Content-Type": "application/json" },
body: JSON.stringify({"email": "reader@example.com", "password": "correct horse battery staple"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/portal/libro/login")
.header("Cookie", "bookclerk_portal_session=<portalSession>")
.header("Origin", "http://127.0.0.1:8787")
.json(&serde_json::json!({"email": "reader@example.com", "password": "correct horse battery staple"}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The account was connected.
{
"ok": true,
"account_id": "reader@example.com",
"source": "libro",
"plugin_key": "bookclerk:source-libro"
}
Schema:
{
"type": "object",
"description": "JSON body of a connected store account.",
"required": [
"ok",
"account_id",
"source",
"plugin_key"
],
"properties": {
"ok": {
"type": "boolean",
"description": "Always `true`.",
"example": true
},
"account_id": {
"type": "string",
"description": "The store's id for the account.",
"example": "reader@example.com"
},
"source": {
"type": "string",
"description": "The source's id, as listed by `GET /api/portal/sources`.",
"example": "libro"
},
"plugin_key": {
"type": "string",
"description": "The plugin that owns the account.",
"example": "bookclerk:source-libro"
}
}
}
Status 400: The Libro.fm source is not deployed here, or the store or the library database refused the step (the body carries its message). As text/plain, when the body is not syntactically valid JSON.
{
"error": "ORM / database plugin error: Execution Error: error returned from database: database is locked"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 401: The caller is not signed in, or the portal session expired.
{
"error": "not signed in"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 403: The library's administrator has not allowed the caller to connect store accounts here. A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "this library's administrator hasn't allowed you to connect store accounts here"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
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 `email` at line 1 column 2
Schema:
A text/plain body: a string.
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Deprecated.
Legacy POST /audible/start alias that forwards to Audible OAuth start.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: portalSession
-
200The browser login URL. Body:
OAuthStartUrl(application/json)1 fieldurlstringrequiredThe store's login page, bound to this sign-in.
-
400The Audible source is not deployed here, the store produced no login URL in time, the login stopped before it produced one, or the library database refused the step. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
401The caller is not signed in, or the portal session expired. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
403The library's administrator has not allowed the caller to connect store accounts here. A write sent with a session cookie but without a matching
OriginorRefereris refused. Body:PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/portal/audible/start' \
-X POST \
-b 'bookclerk_portal_session=<portalSession>' \
-H 'Origin: http://127.0.0.1:8787'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/portal/audible/start' `
-Method Post `
-WebSession $session `
-Headers @{ Origin = 'http://127.0.0.1:8787' }
import requests
response = requests.post(
"http://127.0.0.1:8787/api/portal/audible/start",
headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/portal/audible/start", {
method: "POST",
headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/portal/audible/start")
.header("Cookie", "bookclerk_portal_session=<portalSession>")
.header("Origin", "http://127.0.0.1:8787")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The browser login URL.
{
"url": "https://www.amazon.com/ap/signin?openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0&…"
}
Schema:
{
"type": "object",
"description": "JSON body of an OAuth start: the browser login URL to open.",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"description": "The store's login page, bound to this sign-in.",
"example": "https://www.amazon.com/ap/signin?openid.ns=http%3A%2F%2Fspecs.openid.net%2Fauth%2F2.0&…"
}
}
}
Status 400: The Audible source is not deployed here, the store produced no login URL in time, the login stopped before it produced one, or the library database refused the step.
{
"error": "ORM / database plugin error: Execution Error: error returned from database: database is locked"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 401: The caller is not signed in, or the portal session expired.
{
"error": "not signed in"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 403: The library's administrator has not allowed the caller to connect store accounts here. A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "this library's administrator hasn't allowed you to connect store accounts here"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Lists store accounts linked to the signed-in identity, including disabled sources.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: portalSession
-
200Store accounts linked to the caller. Body:
ConnectionsResponse(application/json)1 fieldconnectionsarray ofConnectionInforequiredLinked store accounts the SPA may show or revoke.
-
400The library database refused the lookup. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
401The caller is not signed in, or the portal session expired. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/portal/connections' \
-b 'bookclerk_portal_session=<portalSession>'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/portal/connections' `
-WebSession $session
import requests
response = requests.get(
"http://127.0.0.1:8787/api/portal/connections",
headers={"Cookie": "bookclerk_portal_session=<portalSession>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/portal/connections", {
headers: { Cookie: "bookclerk_portal_session=<portalSession>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/api/portal/connections")
.header("Cookie", "bookclerk_portal_session=<portalSession>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Store accounts linked to the caller.
{
"connections": [
{
"account_id": "reader@example.com",
"source": "libro",
"plugin_key": "platform:bookclerk/bookclerk-plugin-source-libro#libro",
"label": "Household",
"connection_status": "active",
"source_enabled": true,
"brand": {
"bg": "#1F4E3D",
"fg": "#F4F1EA",
"accent": "#2F6B53",
"logo": "/api/images/aHR0cHM6Ly93d3cuZ29vZ2xlLmNvbS9zMi9mYXZpY29ucz9kb21haW49bGlicm8uZm0mc3o9MTI4.N14rqh66Bok9-eCqJKBNoQ"
},
"pace": {
"mode": "default",
"downloads_per_day": 100,
"min_gap_seconds": 30,
"store_downloads_per_day": 100,
"store_min_gap_seconds": 30,
"custom_downloads_per_day": null,
"custom_min_gap_seconds": null,
"downloads_last_day": 12,
"cooldown_until": null,
"next_automatic_at": null
}
}
]
}
Schema:
{
"type": "object",
"description": "JSON body for `GET /connections`.",
"required": [
"connections"
],
"properties": {
"connections": {
"type": "array",
"items": {
"type": "object",
"description": "One linked store account on the portal Accounts page.",
"required": [
"account_id",
"source",
"plugin_key",
"connection_status",
"source_enabled",
"pace"
],
"properties": {
"account_id": {
"type": "string",
"description": "Store account id (unique within its source).",
"example": "reader@example.com"
},
"source": {
"type": "string",
"description": "Source plugin id that owns this account.",
"example": "libro"
},
"plugin_key": {
"type": "string",
"description": "Provenance-qualified PluginKey that owns the account.",
"example": "platform:bookclerk/bookclerk-plugin-source-libro#libro"
},
"label": {
"type": [
"string",
"null"
],
"description": "Operator-facing account label when the store provided one.",
"example": "Household"
},
"connection_status": {
"type": "string",
"description": "Connection state (`active`, revoked, …); defaults to `active` if the account row is missing.",
"example": "active"
},
"source_enabled": {
"type": "boolean",
"description": "Whether `[sources.<id>] enabled` is currently true (new connects blocked when false).",
"example": true
},
"brand": {
"oneOf": [
{
"type": "object",
"description": "Storefront or integration brand when a plugin or fallback palette is available.",
"required": [
"bg",
"fg",
"accent",
"logo"
],
"properties": {
"bg": {
"type": "string",
"description": "Background color (`#RRGGBB`).",
"example": "#1F4E3D"
},
"fg": {
"type": "string",
"description": "Foreground / text color (`#RRGGBB`).",
"example": "#F4F1EA"
},
"accent": {
"type": "string",
"description": "Accent color (`#RRGGBB`).",
"example": "#2F6B53"
},
"logo": {
"type": "string",
"description": "Same-origin logo image (a 128 px copy of the brand's icon), or empty\nwhen there is none.",
"example": "/api/images/aHR0cHM6Ly93d3cuZ29vZ2xlLmNvbS9zMi9mYXZpY29ucz9kb21haW49bGlicm8uZm0mc3o9MTI4.N14rqh66Bok9-eCqJKBNoQ"
}
}
},
{
"type": "null"
}
]
},
"pace": {
"type": "object",
"description": "How fast Bookclerk downloads from this account when it starts the\ndownloads itself.",
"required": [
"mode",
"min_gap_seconds",
"downloads_last_day"
],
"properties": {
"mode": {
"type": "string",
"description": "`default` (the store's pace), `custom` or `unlimited`.",
"example": "default"
},
"downloads_per_day": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Downloads allowed in any rolling 24 hours now in force; `null` for\nno daily budget.",
"example": 100,
"minimum": 0
},
"min_gap_seconds": {
"type": "integer",
"format": "int64",
"description": "Seconds between two downloads now in force.",
"example": 30,
"minimum": 0
},
"store_downloads_per_day": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "The store's declared daily budget; `null` when it declares none or\nits plugin is not deployed here.",
"example": 100,
"minimum": 0
},
"store_min_gap_seconds": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The store's declared gap in seconds; `null` when its plugin is not\ndeployed here.",
"example": 30,
"minimum": 0
},
"custom_downloads_per_day": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Custom daily budget the operator set, when `mode` is `custom`.",
"example": null,
"minimum": 0
},
"custom_min_gap_seconds": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Custom gap the operator set, when `mode` is `custom`.",
"example": null,
"minimum": 0
},
"downloads_last_day": {
"type": "integer",
"description": "Downloads from this account in the last 24 hours, by hand or not.",
"example": 12,
"minimum": 0
},
"cooldown_until": {
"type": [
"string",
"null"
],
"description": "End of the cool-down the store asked for (RFC 3339), when one is\nrunning.",
"example": null
},
"next_automatic_at": {
"type": [
"string",
"null"
],
"description": "When the next automatic download may start (RFC 3339); `null` when\none may start now.",
"example": null
}
}
}
}
},
"description": "Linked store accounts the SPA may show or revoke."
}
}
}
Status 400: The library database refused the lookup.
{
"error": "ORM / database plugin error: Execution Error: error returned from database: database is locked"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 401: The caller is not signed in, or the portal session expired.
{
"error": "not signed in"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Marks a store account revoked, signs it out, deletes its stored credentials, then unlinks it.
The account is addressed by (source, account_id): the same store id may
exist under two plugins. source is the alias or plugin key of the link.
Links are exclusive (one identity per account), so the caller's link is
the account's only one and revoking it always clears the credentials.
Every step runs while the link still exists, in this order: the account
is marked revoked (which also turns scanning off, so no job picks it up
half-cleaned) and its holdings and scan checkpoints go; the plugin signs
it out at the store (for example, Audible deregisters its device), best
effort; then one atomic batch, guarded on the link and serialized with
logins of the same store account, marks it revoked again, deletes its
encrypted_secrets rows and removes the link. Any failed library step
answers 503 and keeps the link, so the same request retries the
cleanup. Already-acquired library rows stay (product policy).
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: portalSession
sourcepathstringrequiredSource plugin id.account_idpathstringrequiredStore account id.
-
200The account was marked revoked, its stored credentials were deleted, and it was unlinked. Body:
PortalOk(application/json)1 fieldokbooleanrequiredAlwaystrue.
-
400The account is not linked to this identity (also when a concurrent revoke unlinked it first), or the library database refused to read this identity's links (the body carries its message). Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
401The caller is not signed in, or the portal session expired. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
403A write sent with a session cookie but without a matching
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
503A cleanup step failed: marking the account revoked, or the batch that deletes its stored credentials and removes the link. The account stays linked, so repeating the request runs the cleanup again. When the cleanup task itself stopped, the daemon log names it; a repeat either finishes the cleanup or, if the unlink had already run, answers 400
account not linked to this identity. Body:PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/portal/sources/<source>/connections/<account_id>/revoke' \
-X POST \
-b 'bookclerk_portal_session=<portalSession>' \
-H 'Origin: http://127.0.0.1:8787'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/portal/sources/<source>/connections/<account_id>/revoke' `
-Method Post `
-WebSession $session `
-Headers @{ Origin = 'http://127.0.0.1:8787' }
import requests
response = requests.post(
"http://127.0.0.1:8787/api/portal/sources/<source>/connections/<account_id>/revoke",
headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/portal/sources/<source>/connections/<account_id>/revoke", {
method: "POST",
headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/portal/sources/<source>/connections/<account_id>/revoke")
.header("Cookie", "bookclerk_portal_session=<portalSession>")
.header("Origin", "http://127.0.0.1:8787")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The account was marked revoked, its stored credentials were deleted, and it was unlinked.
{
"ok": true
}
Schema:
{
"type": "object",
"description": "JSON body of a portal route that has nothing to report beyond success.",
"required": [
"ok"
],
"properties": {
"ok": {
"type": "boolean",
"description": "Always `true`.",
"example": true
}
}
}
Status 400: The account is not linked to this identity (also when a concurrent revoke unlinked it first), or the library database refused to read this identity's links (the body carries its message).
{
"error": "ORM / database plugin error: Execution Error: error returned from database: database is locked"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 401: The caller is not signed in, or the portal session expired.
{
"error": "not signed in"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 403: A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "forbidden",
"message": "You do not have access to this resource.",
"status": 403
}
Schema:
{
"type": "object",
"description": "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 503: A cleanup step failed: marking the account revoked, or the batch that deletes its stored credentials and removes the link. The account stays linked, so repeating the request runs the cleanup again. When the cleanup task itself stopped, the daemon log names it; a repeat either finishes the cleanup or, if the unlink had already run, answers 400 account not linked to this identity.
{
"error": "revoke cleanup failed: ORM / database plugin error: Execution Error: error returned from database: database is locked"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Changes how fast Bookclerk downloads from one of the caller's store accounts when it starts the downloads itself, and returns the result.
The body sets mode (default, custom or unlimited); a custom pace
carries downloads_per_day (1 to 10000) and/or min_gap_seconds (0 to
86400). clear_cooldown: true also ends a cool-down the store asked
for. Downloads a person starts are never held, whatever the pace.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: portalSession
sourcepathstringrequiredSource plugin id or PluginKey.account_idpathstringrequiredStore account id.
application/json: PaceRequestBody
modePaceModeSchemaor nulldefault,customorunlimited. Leave it out to only end the cool-down (thenclear_cooldownmust betrue) and keep the stored pace.downloads_per_dayinteger (int32) or nullCustom downloads per rolling 24 hours;customonly. At least 1; at most 10000.min_gap_secondsinteger (int32) or nullCustom seconds between downloads;customonly. At least 0; at most 86400.clear_cooldownboolean or nullAlso end a cool-down the store asked for.
-
200The pace was stored; the account's pace as it now stands. Body:
PaceView(application/json)10 fieldsmodestringrequireddefault(the store's pace),customorunlimited.downloads_per_dayinteger (int32) or nullDownloads allowed in any rolling 24 hours now in force;nullfor no daily budget. At least 0.min_gap_secondsinteger (int64)requiredSeconds between two downloads now in force. At least 0.store_downloads_per_dayinteger (int32) or nullThe store's declared daily budget;nullwhen it declares none or its plugin is not deployed here. At least 0.store_min_gap_secondsinteger (int64) or nullThe store's declared gap in seconds;nullwhen its plugin is not deployed here. At least 0.custom_downloads_per_dayinteger (int32) or nullCustom daily budget the operator set, whenmodeiscustom. At least 0.custom_min_gap_secondsinteger (int32) or nullCustom gap the operator set, whenmodeiscustom. At least 0.downloads_last_dayintegerrequiredDownloads from this account in the last 24 hours, by hand or not. At least 0.cooldown_untilstring or nullEnd of the cool-down the store asked for (RFC 3339), when one is running.next_automatic_atstring or nullWhen the next automatic download may start (RFC 3339);nullwhen one may start now.
-
400The body breaks a rule, or the account is not linked to this identity. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
401The caller is not signed in, or the portal session expired. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
403A write sent with a session cookie but without a matching
OriginorRefereris refused. Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
413The body is longer than 4096 bytes. Body:
PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
-
415The request did not declare an
application/jsonbody. Body:PortalErrorBody(application/json)1 fielderrorstringrequiredOperator-facing error text (no structured code).
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/portal/sources/<source>/connections/<account_id>/pace' \
-X POST \
-b 'bookclerk_portal_session=<portalSession>' \
-H 'Origin: http://127.0.0.1:8787' \
-H 'Content-Type: application/json' \
-d '{}'
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
$session.Cookies.Add((New-Object System.Net.Cookie('bookclerk_portal_session', '<portalSession>', '/', '127.0.0.1')))
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/portal/sources/<source>/connections/<account_id>/pace' `
-Method Post `
-WebSession $session `
-Headers @{ Origin = 'http://127.0.0.1:8787' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.post(
"http://127.0.0.1:8787/api/portal/sources/<source>/connections/<account_id>/pace",
headers={"Cookie": "bookclerk_portal_session=<portalSession>", "Origin": "http://127.0.0.1:8787"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/portal/sources/<source>/connections/<account_id>/pace", {
method: "POST",
headers: { Cookie: "bookclerk_portal_session=<portalSession>", Origin: "http://127.0.0.1:8787", "Content-Type": "application/json" },
body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/portal/sources/<source>/connections/<account_id>/pace")
.header("Cookie", "bookclerk_portal_session=<portalSession>")
.header("Origin", "http://127.0.0.1:8787")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The pace was stored; the account's pace as it now stands.
{
"mode": "default",
"downloads_per_day": 100,
"min_gap_seconds": 30,
"store_downloads_per_day": 100,
"store_min_gap_seconds": 30,
"custom_downloads_per_day": null,
"custom_min_gap_seconds": null,
"downloads_last_day": 12,
"cooldown_until": null,
"next_automatic_at": null
}
Schema:
{
"type": "object",
"description": "How fast Bookclerk downloads from one store account when it starts the\ndownloads itself, for the Accounts page.",
"required": [
"mode",
"min_gap_seconds",
"downloads_last_day"
],
"properties": {
"mode": {
"type": "string",
"description": "`default` (the store's pace), `custom` or `unlimited`.",
"example": "default"
},
"downloads_per_day": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Downloads allowed in any rolling 24 hours now in force; `null` for\nno daily budget.",
"example": 100,
"minimum": 0
},
"min_gap_seconds": {
"type": "integer",
"format": "int64",
"description": "Seconds between two downloads now in force.",
"example": 30,
"minimum": 0
},
"store_downloads_per_day": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "The store's declared daily budget; `null` when it declares none or\nits plugin is not deployed here.",
"example": 100,
"minimum": 0
},
"store_min_gap_seconds": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The store's declared gap in seconds; `null` when its plugin is not\ndeployed here.",
"example": 30,
"minimum": 0
},
"custom_downloads_per_day": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Custom daily budget the operator set, when `mode` is `custom`.",
"example": null,
"minimum": 0
},
"custom_min_gap_seconds": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Custom gap the operator set, when `mode` is `custom`.",
"example": null,
"minimum": 0
},
"downloads_last_day": {
"type": "integer",
"description": "Downloads from this account in the last 24 hours, by hand or not.",
"example": 12,
"minimum": 0
},
"cooldown_until": {
"type": [
"string",
"null"
],
"description": "End of the cool-down the store asked for (RFC 3339), when one is\nrunning.",
"example": null
},
"next_automatic_at": {
"type": [
"string",
"null"
],
"description": "When the next automatic download may start (RFC 3339); `null` when\none may start now.",
"example": null
}
}
}
Status 400: The body breaks a rule, or the account is not linked to this identity.
{
"error": "invalid input: pace body: a custom pace needs downloads_per_day or min_gap_seconds"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 401: The caller is not signed in, or the portal session expired.
{
"error": "not signed in"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 403: A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "forbidden",
"message": "You do not have access to this resource.",
"status": 403
}
Schema:
{
"type": "object",
"description": "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 413: The body is longer than 4096 bytes.
{
"error": "the body is at most 4096 bytes"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
Status 415: The request did not declare an application/json body.
{
"error": "the body must be sent as application/json"
}
Schema:
{
"type": "object",
"description": "JSON body of every portal error response.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Operator-facing error text (no structured code).",
"example": "not signed in"
}
}
}
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