Node protocol
Node-to-node enrollment, socket, artifacts and uploads; each route checks its own credential.
Back to the web API reference.
POST /api/node/v1/enroll: redeem an enrollment link. Answers
{library_id, node_id}; 403 transport_insecure when the connection
fails the transport policy, 403 enrollment_refused for any link that
does not redeem.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
application/json: EnrollBody
link_idstringrequiredLink id from the token.secretstringrequiredLink secret from the token.sign_pkstringrequiredEd25519 public signing key.box_pkstringrequiredX25519 public box key.software_versionstringHost's Bookclerk version.
-
200The host is enrolled; its node credential. Body:
EnrolledNodeView(application/json)2 fieldslibrary_idstringrequiredThe library the node joined.node_idstringrequiredThe node id minted for it.
-
400The body is not an enroll request, or its keys are not base64url. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 403The connection failed the transport policy (
transport_insecure, with the check inreason), or the link does not redeem: unknown, used, expired, revoked, or enrollment is off (enrollment_refused). A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:NodeRefusal(application/json) -
404The node API is not mounted on this listener (
node_api_unmounted). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
413The body is larger than 16 KiB. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
415The request is not
application/json. Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
503The enrollment could not be read or recorded; try again (
enrollment_unavailable). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/node/v1/enroll' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"link_id": "9f2c7b1e4a8d3c6f0b5e2a7d4c1f8e3b", "secret": "kQ3nUj9Z2vY4xW8pT6rS1aB5cD7eF0gH2iJ4kL6mN8o", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/node/v1/enroll' `
-Method Post `
-ContentType 'application/json' `
-Body '{"link_id": "9f2c7b1e4a8d3c6f0b5e2a7d4c1f8e3b", "secret": "kQ3nUj9Z2vY4xW8pT6rS1aB5cD7eF0gH2iJ4kL6mN8o", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}'
import requests
response = requests.post(
"http://127.0.0.1:8787/api/node/v1/enroll",
json={"link_id": "9f2c7b1e4a8d3c6f0b5e2a7d4c1f8e3b", "secret": "kQ3nUj9Z2vY4xW8pT6rS1aB5cD7eF0gH2iJ4kL6mN8o", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/node/v1/enroll", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({"link_id": "9f2c7b1e4a8d3c6f0b5e2a7d4c1f8e3b", "secret": "kQ3nUj9Z2vY4xW8pT6rS1aB5cD7eF0gH2iJ4kL6mN8o", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/node/v1/enroll")
.json(&serde_json::json!({"link_id": "9f2c7b1e4a8d3c6f0b5e2a7d4c1f8e3b", "secret": "kQ3nUj9Z2vY4xW8pT6rS1aB5cD7eF0gH2iJ4kL6mN8o", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The host is enrolled; its node credential.
{
"library_id": "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"node_id": "7d2b9e4c-1f3a-4b8d-9c6e-2a5f8b1d4e7c"
}
Schema:
{
"type": "object",
"description": "JSON body after an enrollment link or branch sign-in was redeemed.",
"required": [
"library_id",
"node_id"
],
"properties": {
"library_id": {
"type": "string",
"description": "The library the node joined.",
"example": "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
},
"node_id": {
"type": "string",
"description": "The node id minted for it.",
"example": "7d2b9e4c-1f3a-4b8d-9c6e-2a5f8b1d4e7c"
}
}
}
Status 400: The body is not an enroll request, or its keys are not base64url.
{
"error": "sign_pk and box_pk must be base64url"
}
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 connection failed the transport policy (transport_insecure, with the check in reason), or the link does not redeem: unknown, used, expired, revoked, or enrollment is off (enrollment_refused). A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "enrollment_refused"
}
Schema:
{
"anyOf": [
{
"type": "object",
"description": "The connection failed the transport policy.",
"required": [
"error",
"reason"
],
"properties": {
"error": {
"type": "string",
"description": "Always `transport_insecure`.",
"example": "transport_insecure"
},
"reason": {
"type": "string",
"description": "The transport check that refused the connection (`plain_http`,\n`unknown_peer`, `untrusted_forwarding`, `proxy_proto_missing`,\n`proxy_proto_ambiguous`, `proxy_proto_not_https`,\n`public_origin_not_https`, `listener_mode_mismatch`,\n`node_api_misconfigured`).",
"example": "plain_http"
}
}
},
{
"type": "object",
"description": "The session middleware's standard body (`error`, `message`, `status`).",
"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": "The handler refused with a slug in `error`.",
"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": "The handler refused with a slug in `error` and a sentence in `detail`.",
"required": [
"error",
"detail"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug clients branch on.",
"example": "invalid_request"
},
"detail": {
"type": "string",
"description": "What went wrong, for the person reading the answer.",
"example": "the redirect URI must be loopback or https"
}
}
}
],
"description": "A `403` from a node API route: the transport policy's refusal, the standard body, or the handler's own error; the route's examples name each."
}
Status 404: The node API is not mounted on this listener (node_api_unmounted).
{
"error": "node_api_unmounted"
}
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 larger than 16 KiB.
{
"error": "request too large"
}
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 is not application/json.
{
"error": "expected application/json"
}
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 enrollment could not be read or recorded; try again (enrollment_unavailable).
{
"error": "enrollment_unavailable"
}
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 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
GET /api/node/v1/info.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
-
200What this library says about itself to a joining install. Body:
OwnerInfo(application/json)8 fieldslibrary_idstringrequiredThe library id.library_namestringrequiredA name to show for the library.originstringrequiredThe library's canonical origin: the one the node handshake signs and the authorize endpoint lives under.transportstringrequiredThe node API transport mode (acme,proxy,self_signed,loopback).enrollmentbooleanrequiredWhether the library lets new branches join (core.branch_enrollment).spki_fingerprintstring or nullInself_signedmode: base64url SHA-256 of the certificate's SubjectPublicKeyInfo, which the joining operator confirms against the owner's Settings → Branches page.software_versionstringThe library's Bookclerk version.ancestryarray of stringThe library's ancestry: its own library id first, then the library id of every library above it up to the root. A joining library refuses a parent whose ancestry names its own library id, so a tree of libraries never becomes a cycle.
-
403The connection failed the transport policy (
transport_insecure, with the check inreason). Body:TransportRefused(application/json)2 fieldserrorstringrequiredAlwaystransport_insecure.reasonstringrequiredThe transport check that refused the connection (plain_http,unknown_peer,untrusted_forwarding,proxy_proto_missing,proxy_proto_ambiguous,proxy_proto_not_https,public_origin_not_https,listener_mode_mismatch,node_api_misconfigured).
-
404The node API is not mounted on this listener (
node_api_unmounted). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
503This library's identity row (
library_unavailable) or origin (origin_unavailable) is not available yet. Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/node/v1/info'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/node/v1/info'
import requests
response = requests.get("http://127.0.0.1:8787/api/node/v1/info")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/node/v1/info");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/api/node/v1/info").await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: What this library says about itself to a joining install.
{
"library_id": "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"library_name": "books.example.com",
"origin": "https://books.example.com",
"transport": "acme",
"enrollment": true,
"spki_fingerprint": "kQ3nUj9Z2vY4xW8pT6rS1aB5cD7eF0gH2iJ4kL6mN8o",
"software_version": "0.4.0",
"ancestry": [
"c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
]
}
Schema:
{
"type": "object",
"description": "`GET /api/node/v1/info` answer.",
"required": [
"library_id",
"library_name",
"origin",
"transport",
"enrollment"
],
"properties": {
"library_id": {
"type": "string",
"description": "The library id.",
"example": "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
},
"library_name": {
"type": "string",
"description": "A name to show for the library.",
"example": "books.example.com"
},
"origin": {
"type": "string",
"description": "The library's canonical origin: the one the node handshake signs and\nthe authorize endpoint lives under.",
"example": "https://books.example.com"
},
"transport": {
"type": "string",
"description": "The node API transport mode (`acme`, `proxy`, `self_signed`,\n`loopback`).",
"example": "acme"
},
"enrollment": {
"type": "boolean",
"description": "Whether the library lets new branches join (`core.branch_enrollment`).",
"example": true
},
"spki_fingerprint": {
"type": [
"string",
"null"
],
"description": "In `self_signed` mode: base64url SHA-256 of the certificate's\nSubjectPublicKeyInfo, which the joining operator confirms against\nthe owner's Settings → Branches page.",
"example": "kQ3nUj9Z2vY4xW8pT6rS1aB5cD7eF0gH2iJ4kL6mN8o"
},
"software_version": {
"type": "string",
"description": "The library's Bookclerk version.",
"example": "0.4.0"
},
"ancestry": {
"type": "array",
"items": {
"type": "string"
},
"description": "The library's ancestry: its own library id first, then the library\nid of every library above it up to the root. A joining library\nrefuses a parent whose ancestry names its own library id, so a\ntree of libraries never becomes a cycle.",
"example": [
"c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
]
}
}
}
Status 403: The connection failed the transport policy (transport_insecure, with the check in reason).
{
"error": "transport_insecure",
"reason": "plain_http"
}
Schema:
{
"type": "object",
"description": "JSON body of a `403` from the node API's transport policy: the\nconnection is plain HTTP off loopback, or arrived through a proxy the\npolicy does not trust, and `reason` names the check that refused it.",
"required": [
"error",
"reason"
],
"properties": {
"error": {
"type": "string",
"description": "Always `transport_insecure`.",
"example": "transport_insecure"
},
"reason": {
"type": "string",
"description": "The transport check that refused the connection (`plain_http`,\n`unknown_peer`, `untrusted_forwarding`, `proxy_proto_missing`,\n`proxy_proto_ambiguous`, `proxy_proto_not_https`,\n`public_origin_not_https`, `listener_mode_mismatch`,\n`node_api_misconfigured`).",
"example": "plain_http"
}
}
}
Status 404: The node API is not mounted on this listener (node_api_unmounted).
{
"error": "node_api_unmounted"
}
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 library's identity row (library_unavailable) or origin (origin_unavailable) is not available yet.
{
"error": "library_unavailable"
}
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 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
POST /api/node/v1/enroll/oauth: redeem an approved branch sign-in.
Answers {library_id, node_id} for a branch, plus connection and the
sealed bootstrap for a shared branch; 403 transport_insecure for a refused
connection, 403 enrollment_refused for a code that does not redeem
(unknown, used, expired, another client's, a wrong verifier or
redirect URI, enrollment off, or the user no longer active).
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
application/json: OAuthEnrollRequest
codestringrequiredThe authorization code from the callback.code_verifierstringrequiredThe PKCE verifier.redirect_uristringrequiredThe redirect URI the authorization was requested with.sign_pkstringrequiredEd25519 public signing key.box_pkstringrequiredX25519 public box key.branch_namestringThe name this branch joins as (the node's label).software_versionstringThe joining install's Bookclerk version.connectionConnectionTypeThe connection type the code was approved for. It must match the one bound to the code at consent; left out for a branch.
-
200The install is enrolled: its library and node ids for a branch, and for a shared branch join also
connectionand the bootstrap sealed to its box key. Body:OAuthEnrollAnswer(application/json)5 fieldslibrary_idstringrequiredThe library id.node_idstringrequiredThe node id recorded for the joining install.connectionConnectionTypeThe connection type recorded (branchwhen left out).bootstrapstring or nullFor a shared branch: the [crate::SharedBranchBootstrap] sealed to the node's box key ([crate::seal_shared_branch_bootstrap]), as base64url without padding.accountsstring or nullFor a branch whose user chose "Bring my store connections to this branch": the user's own store accounts as a [crate::AccountBundle] sealed to the node's box key ([crate::seal_account_bundle]), as base64url without padding. Left out when the user did not choose it or had none to bring.
-
400The body is not an enroll request, or its keys are not base64url. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 403The connection failed the transport policy (
transport_insecure, with the check inreason), or the code does not redeem: blank, unknown, used, expired, wrong verifier, or the user may no longer let a shared branch join (enrollment_refused). A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:NodeRefusal(application/json) -
404The node API is not mounted on this listener (
node_api_unmounted). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
409This library's database cannot be shared with another server (
database_not_shareable). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
413The body is larger than 16 KiB. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
415The request is not
application/json. Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
503The enrollment could not be read or recorded; try again (
enrollment_unavailable). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/node/v1/enroll/oauth' \
-X POST \
-H 'Content-Type: application/json' \
-d '{"code": "BhD5jGe21A8WEIm7SrdBZ-KXhs5B9HkeUSEc58grX94", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "http://127.0.0.1:41923/enroll/callback", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/node/v1/enroll/oauth' `
-Method Post `
-ContentType 'application/json' `
-Body '{"code": "BhD5jGe21A8WEIm7SrdBZ-KXhs5B9HkeUSEc58grX94", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "http://127.0.0.1:41923/enroll/callback", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}'
import requests
response = requests.post(
"http://127.0.0.1:8787/api/node/v1/enroll/oauth",
json={"code": "BhD5jGe21A8WEIm7SrdBZ-KXhs5B9HkeUSEc58grX94", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "http://127.0.0.1:41923/enroll/callback", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/node/v1/enroll/oauth", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({"code": "BhD5jGe21A8WEIm7SrdBZ-KXhs5B9HkeUSEc58grX94", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "http://127.0.0.1:41923/enroll/callback", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/node/v1/enroll/oauth")
.json(&serde_json::json!({"code": "BhD5jGe21A8WEIm7SrdBZ-KXhs5B9HkeUSEc58grX94", "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk", "redirect_uri": "http://127.0.0.1:41923/enroll/callback", "sign_pk": "Nflg3bNZ7h6Q7aePwVccVzry1BxzaqtguKtJlkfPE0M", "box_pk": "hSDwCYkwp1R0i33ctD73Wg2_Og0mOBr066SpjqqbTmo"}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The install is enrolled: its library and node ids for a branch, and for a shared branch join also connection and the bootstrap sealed to its box key.
{
"library_id": "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"node_id": "7d2b9e4c-1f3a-4b8d-9c6e-2a5f8b1d4e7c"
}
Schema:
{
"type": "object",
"description": "`POST /api/node/v1/enroll/oauth` answer.",
"required": [
"library_id",
"node_id"
],
"properties": {
"library_id": {
"type": "string",
"description": "The library id.",
"example": "c1f2e3d4-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
},
"node_id": {
"type": "string",
"description": "The node id recorded for the joining install.",
"example": "7d2b9e4c-1f3a-4b8d-9c6e-2a5f8b1d4e7c"
},
"connection": {
"type": "string",
"description": "The connection type recorded (`branch` when left out).",
"enum": [
"branch",
"shared_branch"
]
},
"bootstrap": {
"type": [
"string",
"null"
],
"description": "For a shared branch: the [`crate::SharedBranchBootstrap`] sealed to the node's box\nkey ([`crate::seal_shared_branch_bootstrap`]), as base64url without padding.",
"example": "Qm9va2NsZXJrIHNlYWxlZCBjbGVyayBib290c3RyYXA6IGVwaGVtZXJhbCBrZXkgKyBjaXBoZXJ0ZXh0"
},
"accounts": {
"type": [
"string",
"null"
],
"description": "For a branch whose user chose \"Bring my store connections to this\nbranch\": the user's own store accounts as a\n[`crate::AccountBundle`] sealed to the node's box key\n([`crate::seal_account_bundle`]), as base64url without padding.\nLeft out when the user did not choose it or had none to bring.",
"example": "Qm9va2NsZXJrIHNlYWxlZCBhY2NvdW50IGJ1bmRsZTogZXBoZW1lcmFsIGtleSArIGNpcGhlcnRleHQ"
}
}
}
Status 400: The body is not an enroll request, or its keys are not base64url.
{
"error": "sign_pk and box_pk must be base64url"
}
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 connection failed the transport policy (transport_insecure, with the check in reason), or the code does not redeem: blank, unknown, used, expired, wrong verifier, or the user may no longer let a shared branch join (enrollment_refused). A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "enrollment_refused"
}
Schema:
{
"anyOf": [
{
"type": "object",
"description": "The connection failed the transport policy.",
"required": [
"error",
"reason"
],
"properties": {
"error": {
"type": "string",
"description": "Always `transport_insecure`.",
"example": "transport_insecure"
},
"reason": {
"type": "string",
"description": "The transport check that refused the connection (`plain_http`,\n`unknown_peer`, `untrusted_forwarding`, `proxy_proto_missing`,\n`proxy_proto_ambiguous`, `proxy_proto_not_https`,\n`public_origin_not_https`, `listener_mode_mismatch`,\n`node_api_misconfigured`).",
"example": "plain_http"
}
}
},
{
"type": "object",
"description": "The session middleware's standard body (`error`, `message`, `status`).",
"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": "The handler refused with a slug in `error`.",
"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": "The handler refused with a slug in `error` and a sentence in `detail`.",
"required": [
"error",
"detail"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug clients branch on.",
"example": "invalid_request"
},
"detail": {
"type": "string",
"description": "What went wrong, for the person reading the answer.",
"example": "the redirect URI must be loopback or https"
}
}
}
],
"description": "A `403` from a node API route: the transport policy's refusal, the standard body, or the handler's own error; the route's examples name each."
}
Status 404: The node API is not mounted on this listener (node_api_unmounted).
{
"error": "node_api_unmounted"
}
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: This library's database cannot be shared with another server (database_not_shareable).
{
"error": "database_not_shareable"
}
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 larger than 16 KiB.
{
"error": "request too large"
}
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 is not application/json.
{
"error": "expected application/json"
}
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 enrollment could not be read or recorded; try again (enrollment_unavailable).
{
"error": "enrollment_unavailable"
}
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 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
GET /api/node/v1/connect: upgrade to the branch-node socket after the
transport check. 403 transport_insecure for a refused connection,
400 subprotocol_required without [SUBPROTOCOL].
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: none
- 101Switching to the branch-node WebSocket. The node's signature is checked in the first frames; a wrong one closes the socket. No body.
-
400The request does not offer the node subprotocol (
subprotocol_required). Body:ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The transport is not allowed. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
404The node API is not mounted. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
503Too many handshakes are in flight (
handshakes_busy); retry afterRetry-Afterseconds. 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/node/v1/connect'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/node/v1/connect'
import requests
response = requests.get("http://127.0.0.1:8787/api/node/v1/connect")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/node/v1/connect");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/api/node/v1/connect").await?;
println!("{} {}", response.status(), response.text().await?);
Status 101: Switching to the branch-node WebSocket. The node's signature is checked in the first frames; a wrong one closes the socket. No body.
Status 400: The request does not offer the node subprotocol (subprotocol_required).
{
"error": "bad_request",
"message": "The request could not be understood.",
"status": 400
}
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 transport is not allowed.
{
"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 404: The node API is not mounted.
{
"error": "not_found",
"message": "That page or resource was not found.",
"status": 404
}
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: Too many handshakes are in flight (handshakes_busy); retry after Retry-After seconds.
{
"error": "service_unavailable",
"message": "The Bookclerk daemon is not ready to handle this request.",
"status": 503
}
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.
GET /api/node/v1/artifacts/{sha256}.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: nodeSignature
sha256pathstringrequiredArchive digest, lowercase hex.
- 200The plugin archive. Body:
BinaryBody(application/octet-stream) -
401The node signature is missing or wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
404No such archive, or the node API is not mounted. 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/node/v1/artifacts/<sha256>' \
-H 'Authorization: Bookclerk-Node <node_id> <issued_at> <signature>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/node/v1/artifacts/<sha256>' `
-Headers @{ Authorization = 'Bookclerk-Node <node_id> <issued_at> <signature>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/node/v1/artifacts/<sha256>",
headers={"Authorization": "Bookclerk-Node <node_id> <issued_at> <signature>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/node/v1/artifacts/<sha256>", {
headers: { Authorization: "Bookclerk-Node <node_id> <issued_at> <signature>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/api/node/v1/artifacts/<sha256>")
.header("Authorization", "Bookclerk-Node <node_id> <issued_at> <signature>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The plugin archive. The body is binary (application/octet-stream).
Schema:
A application/octet-stream body: binary bytes.
Status 401: The node signature is missing or 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 404: No such archive, or the node API is not mounted.
{
"error": "not_found",
"message": "That page or resource was not found.",
"status": 404
}
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.
PUT /api/node/v1/uploads/{upload_id}/files/{index}.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: uploadToken
upload_idpathstringrequiredUpload id.indexpathinteger (int32)requiredFile index in the upload.Content-Rangeheaderstring or nullFor a file sent in parts:bytes <first>-<last>/<size>, the part this body is, each its own request in order; orbytes */<size>with an empty body, which asks for the offset the owner needs next (to resume). A file sent whole carries no range.
application/octet-stream: BinaryBody
-
200The file was stored (
received), or a part that is not the file's last was taken, or a status query was answered, with the offset the owner needs next (partial). Body:UploadAnswer(application/json)4 fieldsstatusstringrequiredStable outcome:received,partial(a part that is not the file's last was taken),committed,lost,refused,misdirected,unauthorized,unavailable.reasonstring or nullWhy, forrefused, andresumefor anunavailablepart that does not continue the open file at [Self::offset].offsetinteger (int64) or nullForpartial, and anunavailablepart with reasonresume: the offset of the next byte of the file the owner needs. At least 0.job_completedbooleanForcommitted: the job is finished.
-
401The upload token is missing or wrong, or names no live upload (
unauthorized). Body:UploadAnswer(application/json)4 fieldsstatusstringrequiredStable outcome:received,partial(a part that is not the file's last was taken),committed,lost,refused,misdirected,unauthorized,unavailable.reasonstring or nullWhy, forrefused, andresumefor anunavailablepart that does not continue the open file at [Self::offset].offsetinteger (int64) or nullForpartial, and anunavailablepart with reasonresume: the offset of the next byte of the file the owner needs. At least 0.job_completedbooleanForcommitted: the job is finished.
-
403The connection failed the transport policy (
transport_insecure, with the check inreason). Body:TransportRefused(application/json)2 fieldserrorstringrequiredAlwaystransport_insecure.reasonstringrequiredThe transport check that refused the connection (plain_http,unknown_peer,untrusted_forwarding,proxy_proto_missing,proxy_proto_ambiguous,proxy_proto_not_https,public_origin_not_https,listener_mode_mismatch,node_api_misconfigured).
-
404The node API is not mounted on this listener (
node_api_unmounted). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
409The upload lost its fence to a newer one (
lost). Body:UploadAnswer(application/json)4 fieldsstatusstringrequiredStable outcome:received,partial(a part that is not the file's last was taken),committed,lost,refused,misdirected,unauthorized,unavailable.reasonstring or nullWhy, forrefused, andresumefor anunavailablepart that does not continue the open file at [Self::offset].offsetinteger (int64) or nullForpartial, and anunavailablepart with reasonresume: the offset of the next byte of the file the owner needs. At least 0.job_completedbooleanForcommitted: the job is finished.
-
421This node is not the upload's receiving node (
misdirected). Body:UploadAnswer(application/json)4 fieldsstatusstringrequiredStable outcome:received,partial(a part that is not the file's last was taken),committed,lost,refused,misdirected,unauthorized,unavailable.reasonstring or nullWhy, forrefused, andresumefor anunavailablepart that does not continue the open file at [Self::offset].offsetinteger (int64) or nullForpartial, and anunavailablepart with reasonresume: the offset of the next byte of the file the owner needs. At least 0.job_completedbooleanForcommitted: the job is finished.
-
422The file was refused (
refused): not in the upload (unknown_file), aContent-Rangethat is not exactly a part of the declared file (invalid_range), a size or content mismatch (size_mismatch,content_mismatch), the destinations changed (destinations_changed), or a granted storage key now belongs to another title or writer (key_taken). Body:UploadAnswer(application/json)4 fieldsstatusstringrequiredStable outcome:received,partial(a part that is not the file's last was taken),committed,lost,refused,misdirected,unauthorized,unavailable.reasonstring or nullWhy, forrefused, andresumefor anunavailablepart that does not continue the open file at [Self::offset].offsetinteger (int64) or nullForpartial, and anunavailablepart with reasonresume: the offset of the next byte of the file the owner needs. At least 0.job_completedbooleanForcommitted: the job is finished.
-
503Storage or the upload record is unavailable, or the file lock timed out; retry (
unavailable). With reasonresume, a part did not start where the open file stands, or broke part way: send the file fromoffset(0 when no write is open here). Body:UploadAnswer(application/json)4 fieldsstatusstringrequiredStable outcome:received,partial(a part that is not the file's last was taken),committed,lost,refused,misdirected,unauthorized,unavailable.reasonstring or nullWhy, forrefused, andresumefor anunavailablepart that does not continue the open file at [Self::offset].offsetinteger (int64) or nullForpartial, and anunavailablepart with reasonresume: the offset of the next byte of the file the owner needs. At least 0.job_completedbooleanForcommitted: the job is finished.
$ curl 'http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/files/<index>' \
-X PUT \
-H 'Authorization: Bookclerk-Upload <token>' \
-H 'Content-Type: application/octet-stream' \
--data-binary @file
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/files/<index>' `
-Method Put `
-Headers @{ Authorization = 'Bookclerk-Upload <token>' } `
-ContentType 'application/octet-stream' `
-InFile 'file'
import requests
response = requests.put(
"http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/files/<index>",
headers={"Authorization": "Bookclerk-Upload <token>", "Content-Type": "application/octet-stream"},
data=open("file", "rb"),
)
print(response.status_code, response.text)
import { readFile } from "node:fs/promises";
const response = await fetch("http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/files/<index>", {
method: "PUT",
headers: { Authorization: "Bookclerk-Upload <token>", "Content-Type": "application/octet-stream" },
body: await readFile("file"),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.put("http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/files/<index>")
.header("Authorization", "Bookclerk-Upload <token>")
.header("Content-Type", "application/octet-stream")
.body(std::fs::read("file")?)
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The file was stored (received), or a part that is not the file's last was taken, or a status query was answered, with the offset the owner needs next (partial).
{
"job_completed": false,
"offset": 67108864,
"status": "partial"
}
Schema:
{
"type": "object",
"description": "Answer of the upload endpoint (every status carries one).",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
"example": "received"
},
"reason": {
"type": [
"string",
"null"
],
"description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
"example": "size_mismatch"
},
"offset": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
"example": 67108864,
"minimum": 0
},
"job_completed": {
"type": "boolean",
"description": "For `committed`: the job is finished.",
"example": false
}
}
}
Status 401: The upload token is missing or wrong, or names no live upload (unauthorized).
{
"job_completed": false,
"status": "unauthorized"
}
Schema:
{
"type": "object",
"description": "Answer of the upload endpoint (every status carries one).",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
"example": "received"
},
"reason": {
"type": [
"string",
"null"
],
"description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
"example": "size_mismatch"
},
"offset": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
"example": 67108864,
"minimum": 0
},
"job_completed": {
"type": "boolean",
"description": "For `committed`: the job is finished.",
"example": false
}
}
}
Status 403: The connection failed the transport policy (transport_insecure, with the check in reason).
{
"error": "transport_insecure",
"reason": "plain_http"
}
Schema:
{
"type": "object",
"description": "JSON body of a `403` from the node API's transport policy: the\nconnection is plain HTTP off loopback, or arrived through a proxy the\npolicy does not trust, and `reason` names the check that refused it.",
"required": [
"error",
"reason"
],
"properties": {
"error": {
"type": "string",
"description": "Always `transport_insecure`.",
"example": "transport_insecure"
},
"reason": {
"type": "string",
"description": "The transport check that refused the connection (`plain_http`,\n`unknown_peer`, `untrusted_forwarding`, `proxy_proto_missing`,\n`proxy_proto_ambiguous`, `proxy_proto_not_https`,\n`public_origin_not_https`, `listener_mode_mismatch`,\n`node_api_misconfigured`).",
"example": "plain_http"
}
}
}
Status 404: The node API is not mounted on this listener (node_api_unmounted).
{
"error": "node_api_unmounted"
}
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 upload lost its fence to a newer one (lost).
{
"job_completed": false,
"status": "lost"
}
Schema:
{
"type": "object",
"description": "Answer of the upload endpoint (every status carries one).",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
"example": "received"
},
"reason": {
"type": [
"string",
"null"
],
"description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
"example": "size_mismatch"
},
"offset": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
"example": 67108864,
"minimum": 0
},
"job_completed": {
"type": "boolean",
"description": "For `committed`: the job is finished.",
"example": false
}
}
}
Status 421: This node is not the upload's receiving node (misdirected).
{
"job_completed": false,
"status": "misdirected"
}
Schema:
{
"type": "object",
"description": "Answer of the upload endpoint (every status carries one).",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
"example": "received"
},
"reason": {
"type": [
"string",
"null"
],
"description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
"example": "size_mismatch"
},
"offset": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
"example": 67108864,
"minimum": 0
},
"job_completed": {
"type": "boolean",
"description": "For `committed`: the job is finished.",
"example": false
}
}
}
Status 422: The file was refused (refused): not in the upload (unknown_file), a Content-Range that is not exactly a part of the declared file (invalid_range), a size or content mismatch (size_mismatch, content_mismatch), the destinations changed (destinations_changed), or a granted storage key now belongs to another title or writer (key_taken).
{
"job_completed": false,
"reason": "content_mismatch",
"status": "refused"
}
Schema:
{
"type": "object",
"description": "Answer of the upload endpoint (every status carries one).",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
"example": "received"
},
"reason": {
"type": [
"string",
"null"
],
"description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
"example": "size_mismatch"
},
"offset": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
"example": 67108864,
"minimum": 0
},
"job_completed": {
"type": "boolean",
"description": "For `committed`: the job is finished.",
"example": false
}
}
}
Status 503: Storage or the upload record is unavailable, or the file lock timed out; retry (unavailable). With reason resume, a part did not start where the open file stands, or broke part way: send the file from offset (0 when no write is open here).
{
"job_completed": false,
"offset": 67108864,
"reason": "resume",
"status": "unavailable"
}
Schema:
{
"type": "object",
"description": "Answer of the upload endpoint (every status carries one).",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
"example": "received"
},
"reason": {
"type": [
"string",
"null"
],
"description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
"example": "size_mismatch"
},
"offset": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
"example": 67108864,
"minimum": 0
},
"job_completed": {
"type": "boolean",
"description": "For `committed`: the job is finished.",
"example": false
}
}
}
POST /api/node/v1/uploads/{upload_id}/commit.
Access: No auth layer. Routes that need a caller say so in security; the handler checks it.
Credentials: uploadToken
upload_idpathstringrequiredUpload id.
application/json: UploadCommitRequest
finishbooleanComplete the job with this commit (the job's closing upload).detailstring or nullOutcome text recorded as the job's progress whenfinishis set.
-
200The upload was committed to the destinations (
committed). Body:UploadAnswer(application/json)4 fieldsstatusstringrequiredStable outcome:received,partial(a part that is not the file's last was taken),committed,lost,refused,misdirected,unauthorized,unavailable.reasonstring or nullWhy, forrefused, andresumefor anunavailablepart that does not continue the open file at [Self::offset].offsetinteger (int64) or nullForpartial, and anunavailablepart with reasonresume: the offset of the next byte of the file the owner needs. At least 0.job_completedbooleanForcommitted: the job is finished.
-
401The upload token is missing or wrong, or names no live upload (
unauthorized). Body:UploadAnswer(application/json)4 fieldsstatusstringrequiredStable outcome:received,partial(a part that is not the file's last was taken),committed,lost,refused,misdirected,unauthorized,unavailable.reasonstring or nullWhy, forrefused, andresumefor anunavailablepart that does not continue the open file at [Self::offset].offsetinteger (int64) or nullForpartial, and anunavailablepart with reasonresume: the offset of the next byte of the file the owner needs. At least 0.job_completedbooleanForcommitted: the job is finished.
-
403The connection failed the transport policy (
transport_insecure, with the check inreason). Body:TransportRefused(application/json)2 fieldserrorstringrequiredAlwaystransport_insecure.reasonstringrequiredThe transport check that refused the connection (plain_http,unknown_peer,untrusted_forwarding,proxy_proto_missing,proxy_proto_ambiguous,proxy_proto_not_https,public_origin_not_https,listener_mode_mismatch,node_api_misconfigured).
-
404The node API is not mounted on this listener (
node_api_unmounted). Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
409The upload lost its fence to a newer one (
lost). Body:UploadAnswer(application/json)4 fieldsstatusstringrequiredStable outcome:received,partial(a part that is not the file's last was taken),committed,lost,refused,misdirected,unauthorized,unavailable.reasonstring or nullWhy, forrefused, andresumefor anunavailablepart that does not continue the open file at [Self::offset].offsetinteger (int64) or nullForpartial, and anunavailablepart with reasonresume: the offset of the next byte of the file the owner needs. At least 0.job_completedbooleanForcommitted: the job is finished.
-
421This node is not the upload's receiving node (
misdirected). Body:UploadAnswer(application/json)4 fieldsstatusstringrequiredStable outcome:received,partial(a part that is not the file's last was taken),committed,lost,refused,misdirected,unauthorized,unavailable.reasonstring or nullWhy, forrefused, andresumefor anunavailablepart that does not continue the open file at [Self::offset].offsetinteger (int64) or nullForpartial, and anunavailablepart with reasonresume: the offset of the next byte of the file the owner needs. At least 0.job_completedbooleanForcommitted: the job is finished.
-
422The commit was refused (
refused), with the cause inreason: the body does not parse (invalid_body); the upload is unknown, aborted, or its job was cancelled (unknown_upload,upload_aborted,job_cancelled); not every granted file arrived (files_missing); the destinations changed since the grant (destinations_changed); a storage key now belongs to another title or writer, or the title's holding is gone (key_taken,unknown_title); or the closing upload is mismatched: an ordinary upload claims to finish the job (not_a_closing_upload), the closing upload does not (closing_upload_must_finish), or it arrives while titles are still pending (titles_remaining). Body:UploadAnswer(application/json)4 fieldsstatusstringrequiredStable outcome:received,partial(a part that is not the file's last was taken),committed,lost,refused,misdirected,unauthorized,unavailable.reasonstring or nullWhy, forrefused, andresumefor anunavailablepart that does not continue the open file at [Self::offset].offsetinteger (int64) or nullForpartial, and anunavailablepart with reasonresume: the offset of the next byte of the file the owner needs. At least 0.job_completedbooleanForcommitted: the job is finished.
-
503Storage or the upload record is unavailable; retry (
unavailable). Body:UploadAnswer(application/json)4 fieldsstatusstringrequiredStable outcome:received,partial(a part that is not the file's last was taken),committed,lost,refused,misdirected,unauthorized,unavailable.reasonstring or nullWhy, forrefused, andresumefor anunavailablepart that does not continue the open file at [Self::offset].offsetinteger (int64) or nullForpartial, and anunavailablepart with reasonresume: the offset of the next byte of the file the owner needs. At least 0.job_completedbooleanForcommitted: the job is finished.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/commit' \
-X POST \
-H 'Authorization: Bookclerk-Upload <token>' \
-H 'Content-Type: application/json' \
-d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/commit' `
-Method Post `
-Headers @{ Authorization = 'Bookclerk-Upload <token>' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.post(
"http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/commit",
headers={"Authorization": "Bookclerk-Upload <token>"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/node/v1/uploads/<upload_id>/commit", {
method: "POST",
headers: { Authorization: "Bookclerk-Upload <token>", "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/node/v1/uploads/<upload_id>/commit")
.header("Authorization", "Bookclerk-Upload <token>")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The upload was committed to the destinations (committed).
{
"job_completed": true,
"status": "committed"
}
Schema:
{
"type": "object",
"description": "Answer of the upload endpoint (every status carries one).",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
"example": "received"
},
"reason": {
"type": [
"string",
"null"
],
"description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
"example": "size_mismatch"
},
"offset": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
"example": 67108864,
"minimum": 0
},
"job_completed": {
"type": "boolean",
"description": "For `committed`: the job is finished.",
"example": false
}
}
}
Status 401: The upload token is missing or wrong, or names no live upload (unauthorized).
{
"job_completed": false,
"status": "unauthorized"
}
Schema:
{
"type": "object",
"description": "Answer of the upload endpoint (every status carries one).",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
"example": "received"
},
"reason": {
"type": [
"string",
"null"
],
"description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
"example": "size_mismatch"
},
"offset": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
"example": 67108864,
"minimum": 0
},
"job_completed": {
"type": "boolean",
"description": "For `committed`: the job is finished.",
"example": false
}
}
}
Status 403: The connection failed the transport policy (transport_insecure, with the check in reason).
{
"error": "transport_insecure",
"reason": "plain_http"
}
Schema:
{
"type": "object",
"description": "JSON body of a `403` from the node API's transport policy: the\nconnection is plain HTTP off loopback, or arrived through a proxy the\npolicy does not trust, and `reason` names the check that refused it.",
"required": [
"error",
"reason"
],
"properties": {
"error": {
"type": "string",
"description": "Always `transport_insecure`.",
"example": "transport_insecure"
},
"reason": {
"type": "string",
"description": "The transport check that refused the connection (`plain_http`,\n`unknown_peer`, `untrusted_forwarding`, `proxy_proto_missing`,\n`proxy_proto_ambiguous`, `proxy_proto_not_https`,\n`public_origin_not_https`, `listener_mode_mismatch`,\n`node_api_misconfigured`).",
"example": "plain_http"
}
}
}
Status 404: The node API is not mounted on this listener (node_api_unmounted).
{
"error": "node_api_unmounted"
}
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 upload lost its fence to a newer one (lost).
{
"job_completed": false,
"status": "lost"
}
Schema:
{
"type": "object",
"description": "Answer of the upload endpoint (every status carries one).",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
"example": "received"
},
"reason": {
"type": [
"string",
"null"
],
"description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
"example": "size_mismatch"
},
"offset": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
"example": 67108864,
"minimum": 0
},
"job_completed": {
"type": "boolean",
"description": "For `committed`: the job is finished.",
"example": false
}
}
}
Status 421: This node is not the upload's receiving node (misdirected).
{
"job_completed": false,
"status": "misdirected"
}
Schema:
{
"type": "object",
"description": "Answer of the upload endpoint (every status carries one).",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
"example": "received"
},
"reason": {
"type": [
"string",
"null"
],
"description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
"example": "size_mismatch"
},
"offset": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
"example": 67108864,
"minimum": 0
},
"job_completed": {
"type": "boolean",
"description": "For `committed`: the job is finished.",
"example": false
}
}
}
Status 422: The commit was refused (refused), with the cause in reason: the body does not parse (invalid_body); the upload is unknown, aborted, or its job was cancelled (unknown_upload, upload_aborted, job_cancelled); not every granted file arrived (files_missing); the destinations changed since the grant (destinations_changed); a storage key now belongs to another title or writer, or the title's holding is gone (key_taken, unknown_title); or the closing upload is mismatched: an ordinary upload claims to finish the job (not_a_closing_upload), the closing upload does not (closing_upload_must_finish), or it arrives while titles are still pending (titles_remaining).
{
"job_completed": false,
"reason": "closing_upload_must_finish",
"status": "refused"
}
Schema:
{
"type": "object",
"description": "Answer of the upload endpoint (every status carries one).",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
"example": "received"
},
"reason": {
"type": [
"string",
"null"
],
"description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
"example": "size_mismatch"
},
"offset": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
"example": 67108864,
"minimum": 0
},
"job_completed": {
"type": "boolean",
"description": "For `committed`: the job is finished.",
"example": false
}
}
}
Status 503: Storage or the upload record is unavailable; retry (unavailable).
{
"job_completed": false,
"status": "unavailable"
}
Schema:
{
"type": "object",
"description": "Answer of the upload endpoint (every status carries one).",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "Stable outcome: `received`, `partial` (a part that is not the\nfile's last was taken), `committed`, `lost`, `refused`,\n`misdirected`, `unauthorized`, `unavailable`.",
"example": "received"
},
"reason": {
"type": [
"string",
"null"
],
"description": "Why, for `refused`, and `resume` for an `unavailable` part that\ndoes not continue the open file at [`Self::offset`].",
"example": "size_mismatch"
},
"offset": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "For `partial`, and an `unavailable` part with reason `resume`: the\noffset of the next byte of the file the owner needs.",
"example": 67108864,
"minimum": 0
},
"job_completed": {
"type": "boolean",
"description": "For `committed`: the job is finished.",
"example": false
}
}
}
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