Plugins
Plugin packages, instances, consent and deployment.
Back to the web API reference.
GET /api/config/plugin-instances.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
-
200Every plugin instance with its deployments. Body:
PluginInstancesResponse(application/json)2 fieldsnode_idstringrequiredId of the node that answered; its deployments carry its own observations.instancesarray ofPluginInstanceViewrequiredEvery plugin instance in the library.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
500The configuration could not be read. 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/config/plugin-instances' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugin-instances' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/config/plugin-instances",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugin-instances", {
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/api/config/plugin-instances")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Every plugin instance with its deployments.
{
"node_id": "node-7f3a9c",
"instances": [
{
"plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"plugin_key": "local",
"alias": "local",
"display_name": "",
"is_default": true,
"created_at": "2026-10-01T08:00:00Z",
"schema": [
{
"key": "root",
"type": "string"
}
],
"config": {
"revision": 5,
"settings": {
"multi_destination": "sync_missing",
"root": "/srv/audiobooks"
},
"secret_refs": []
},
"deployments": [
{
"deployment_id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"node_id": "node-7f3a9c",
"desired": "present",
"revision": 3
}
],
"placement": {
"replicas": 0,
"constraints": [
"target=linux-x64-gnu",
"!drain"
],
"revision": 2,
"placed": 1,
"detail": "",
"scheduled_at": "2026-10-28T19:07:00Z",
"updated_at": "2026-10-28T19:05:00Z"
},
"storage_sync": {
"feed_state": "off",
"feed_error": "the notification queue refused the request: access denied",
"feed_checked_at": "2026-11-20T21:00:00Z",
"listed_at": "2026-11-20T18:00:00Z",
"next_listing_at": "2026-11-21T00:00:00Z",
"listing_in_progress": false,
"listing_error": "the listing missed 412 of 1832 known files; removals were not applied",
"objects": 1832
}
}
]
}
Schema:
{
"type": "object",
"description": "`GET /api/config/plugin-instances` body: every instance as this node\nsees it.",
"required": [
"node_id",
"instances"
],
"properties": {
"node_id": {
"type": "string",
"description": "Id of the node that answered; its deployments carry its own\nobservations.",
"example": "node-7f3a9c"
},
"instances": {
"type": "array",
"items": {
"type": "object",
"description": "One plugin instance with its schema, document, and deployments.",
"required": [
"plugin_instance_id",
"plugin_key",
"alias",
"display_name",
"is_default",
"created_at",
"schema",
"deployments"
],
"properties": {
"plugin_instance_id": {
"type": "string",
"description": "Instance id.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"plugin_key": {
"type": "string",
"description": "Canonical plugin key.",
"example": "local"
},
"alias": {
"type": "string",
"description": "Manifest id recorded with the pinned schema (display alias).",
"example": "local"
},
"display_name": {
"type": "string",
"description": "Operator-facing name; empty for the default instance.",
"example": ""
},
"is_default": {
"type": "boolean",
"description": "True when a bare plugin key or alias routes to this instance.",
"example": true
},
"created_at": {
"type": "string",
"description": "RFC 3339 creation time.",
"example": "2026-10-01T08:00:00Z"
},
"schema": {
"type": "array",
"items": {
"type": "object",
"description": "One setting a plugin declares in its `plugin.toml` `[[settings]]`:\nits key, value type, default and help text.",
"required": [
"key",
"type"
],
"properties": {
"key": {
"type": "string",
"description": "Setting key (`[a-z][a-z0-9_]*`, at most 64 bytes).",
"example": "root"
},
"label": {
"type": [
"string",
"null"
],
"description": "Operator-facing label; omitted when the key is shown.",
"example": "Library root"
},
"type": {
"type": "string",
"description": "Value type: `string`, `bool`, `integer`, `enum`, `secret` or\n`table`.",
"enum": [
"string",
"bool",
"integer",
"enum",
"secret",
"table"
],
"example": "string"
},
"values": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "One allowed value of an `enum` setting: the stored id and its label.",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Stored value.",
"example": "sync_missing"
},
"label": {
"type": [
"string",
"null"
],
"description": "Operator-facing label; omitted when the id is shown.",
"example": "Sync missing"
}
}
},
"description": "Allowed values of an `enum` setting; omitted for other kinds."
},
"default": {
"description": "Default applied when the instance document has no value; omitted when there is none. A string, boolean or integer, or for a `table` an array of row objects, as the setting's `type` says.",
"examples": [
"/srv/audiobooks"
]
},
"required": {
"type": [
"boolean",
"null"
],
"description": "True when the instance cannot run without a value; omitted when\nfalse.",
"example": true
},
"description": {
"type": [
"string",
"null"
],
"description": "Help text shown beside the setting; omitted when there is none.",
"example": "Directory the finished audiobooks are written to."
},
"columns": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/SettingSpec"
},
"description": "Columns of a `table` setting, in display order: each a scalar entry\nnaming one field of every row. Omitted for other kinds."
}
}
},
"description": "Declared settings from the pinned schema."
},
"config": {
"oneOf": [
{
"type": "object",
"description": "Current document, when the instance has one.",
"required": [
"revision",
"settings",
"secret_refs"
],
"properties": {
"revision": {
"type": "integer",
"format": "int64",
"description": "Compare-and-swap revision.",
"example": 5
},
"settings": {
"type": "object",
"description": "Scalar settings the operator wrote.",
"additionalProperties": {
"oneOf": [
{
"type": "boolean",
"description": "JSON boolean."
},
{
"type": "number",
"description": "Finite JSON number: an integer kind stores an `i64`, so the schema\nis an unformatted `number` rather than a `double`.",
"examples": [
8
]
},
{
"type": "string",
"description": "JSON string, at most 1024 bytes."
},
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "boolean",
"description": "JSON boolean."
},
{
"type": "number",
"description": "Finite JSON number; an integer for integer columns.",
"examples": [
8
]
},
{
"type": "string",
"description": "JSON string, at most 1024 bytes."
}
],
"description": "One cell of a table setting row: the scalar kinds only."
},
"propertyNames": {
"type": "string"
}
},
"description": "Rows of a table setting: each row maps a column key to a scalar cell.\nRows are records rather than positional lists, so a column added to\nthe declaration later keeps existing rows valid."
}
],
"description": "One setting value: a scalar, or the rows of a table setting.",
"example": "/srv/audiobooks"
},
"propertyNames": {
"type": "string"
},
"example": {
"multi_destination": "sync_missing",
"root": "/srv/audiobooks"
}
},
"secret_refs": {
"type": "array",
"items": {
"type": "object",
"description": "A name in `encrypted_secrets`. The ciphertext is not part of the document.",
"required": [
"key",
"name"
],
"properties": {
"key": {
"type": "string",
"description": "Key in the `SECRETS` object delivered to the guest.",
"example": "api_token"
},
"name": {
"type": "string",
"description": "`encrypted_secrets.name` for this instance.",
"example": "api_token"
}
}
},
"description": "Secret refs; ciphertext stays in `encrypted_secrets`."
}
}
},
{
"type": "null"
}
]
},
"deployments": {
"type": "array",
"items": {
"type": "object",
"description": "This node's view of one deployment row, with its latest observation.",
"required": [
"deployment_id",
"node_id",
"desired",
"revision"
],
"properties": {
"deployment_id": {
"type": "string",
"description": "Deployment row id.",
"example": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
},
"node_id": {
"type": "string",
"description": "Node the row targets.",
"example": "node-7f3a9c"
},
"desired": {
"type": "string",
"description": "What the row asks the node to do: `present` / `absent` from an\noperator, `placed` / `unplaced` from the scheduler.",
"enum": [
"present",
"absent",
"placed",
"unplaced"
]
},
"revision": {
"type": "integer",
"format": "int64",
"description": "Compare-and-swap revision of the desired row.",
"example": 3
},
"status": {
"type": [
"string",
"null"
],
"description": "Latest observation status from that node, when it reported one.",
"example": "healthy"
},
"detail": {
"type": [
"string",
"null"
],
"description": "Observation detail (error text, redacted).",
"example": ""
},
"applied_config_revision": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Document revision the running guest applied.",
"example": 5
},
"observed_at": {
"type": [
"string",
"null"
],
"description": "RFC 3339 time of the observation.",
"example": "2026-10-28T19:07:00Z"
}
}
},
"description": "Deployment rows across nodes."
},
"placement": {
"oneOf": [
{
"type": "object",
"description": "Scheduler placement; absent when the instance is hand-managed.",
"required": [
"replicas",
"constraints",
"revision",
"placed",
"detail",
"scheduled_at",
"updated_at"
],
"properties": {
"replicas": {
"oneOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "string",
"enum": [
"all"
]
}
],
"description": "A replica count (0 stops every replica) or `\"all\"`."
},
"constraints": {
"type": "array",
"items": {
"type": "string"
},
"description": "Label constraints every chosen node must satisfy.",
"example": [
"target=linux-x64-gnu",
"!drain"
]
},
"revision": {
"type": "integer",
"format": "int64",
"description": "Compare-and-swap revision of the intent.",
"example": 2
},
"placed": {
"type": "integer",
"format": "int32",
"description": "Replicas the last scheduler pass placed.",
"example": 1,
"minimum": 0
},
"detail": {
"type": "string",
"description": "Why fewer than requested are placed; empty when satisfied.",
"example": ""
},
"scheduled_at": {
"type": "string",
"description": "RFC 3339 time the scheduler last changed the status.",
"example": "2026-10-28T19:07:00Z"
},
"updated_at": {
"type": "string",
"description": "RFC 3339 time of the last intent write.",
"example": "2026-10-28T19:05:00Z"
}
}
},
{
"type": "null"
}
]
},
"storage_sync": {
"oneOf": [
{
"type": "object",
"description": "How outside changes at this destination are followed; absent until\na storage instance's first sync pass.",
"required": [
"feed_state",
"listing_in_progress",
"objects"
],
"properties": {
"feed_state": {
"type": "string",
"description": "The change feed's state: `off` (no feed; listings alone), `healthy`,\n`gap` (the feed may have missed changes; a listing runs at once) or\n`failing` (reading the feed failed; listings cover it).",
"enum": [
"off",
"healthy",
"gap",
"failing"
]
},
"feed_error": {
"type": [
"string",
"null"
],
"description": "The last feed failure.",
"example": "the notification queue refused the request: access denied"
},
"feed_checked_at": {
"type": [
"string",
"null"
],
"description": "RFC 3339 time the feed was last read.",
"example": "2026-11-20T21:00:00Z"
},
"listed_at": {
"type": [
"string",
"null"
],
"description": "RFC 3339 time the last listing finished.",
"example": "2026-11-20T18:00:00Z"
},
"next_listing_at": {
"type": [
"string",
"null"
],
"description": "RFC 3339 time the next scheduled listing is due.",
"example": "2026-11-21T00:00:00Z"
},
"listing_in_progress": {
"type": "boolean",
"description": "True while a listing is in progress (it continues on the next\npass).",
"example": false
},
"listing_error": {
"type": [
"string",
"null"
],
"description": "Why the last listing failed or its removals were held back.",
"example": "the listing missed 412 of 1832 known files; removals were not applied"
},
"objects": {
"type": "integer",
"format": "int64",
"description": "Files the destination held after the last listing or feed page.",
"example": 1832,
"minimum": 0
}
}
},
{
"type": "null"
}
]
}
}
},
"description": "Every plugin instance in the library."
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route.
{
"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 500: The configuration could not be read.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
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/config/plugin-instances: a second (non-default) instance of
a plugin, with an empty document so schema defaults apply. With
node_id, the instance is local to that node.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
application/json: CreatePluginInstance
plugin_keystringrequiredCanonical plugin key; the plugin must have a pinned schema.display_namestringOperator-facing name.node_idstring or nullMake the instance local to this node (H-2): it deploys only there and is never placed by the scheduler.
-
200The new instance. Body:
PluginInstanceCreated(application/json)4 fieldsplugin_instance_idstringrequiredId of the new instance.plugin_keystringrequiredCanonical plugin key the instance belongs to.display_namestringrequiredOperator-facing name, trimmed.owner_node_idstring or nullNode the instance is local to;nullfor a library-wide instance.
-
400The body is invalid. As
text/plain, when the body is not syntactically valid JSON. Body:ErrorMessage(application/json); string (text/plain)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. A 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.
-
404No such plugin, or it has no pinned schema. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
500The configuration could not be read or written. 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/config/plugin-instances' \
-X POST \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{"plugin_key": "platform:bookclerk/bookclerk-plugin-source-libro#libro"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugin-instances' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{"plugin_key": "platform:bookclerk/bookclerk-plugin-source-libro#libro"}'
import requests
response = requests.post(
"http://127.0.0.1:8787/api/config/plugin-instances",
headers={"Authorization": "Bearer <operatorToken>"},
json={"plugin_key": "platform:bookclerk/bookclerk-plugin-source-libro#libro"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugin-instances", {
method: "POST",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({"plugin_key": "platform:bookclerk/bookclerk-plugin-source-libro#libro"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/config/plugin-instances")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({"plugin_key": "platform:bookclerk/bookclerk-plugin-source-libro#libro"}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The new instance.
{
"plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"plugin_key": "s3",
"display_name": "Archive bucket",
"owner_node_id": "node-7f3a9c"
}
Schema:
{
"type": "object",
"description": "`POST /api/config/plugin-instances` body: the instance that was created.",
"required": [
"plugin_instance_id",
"plugin_key",
"display_name"
],
"properties": {
"plugin_instance_id": {
"type": "string",
"description": "Id of the new instance.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"plugin_key": {
"type": "string",
"description": "Canonical plugin key the instance belongs to.",
"example": "s3"
},
"display_name": {
"type": "string",
"description": "Operator-facing name, trimmed.",
"example": "Archive bucket"
},
"owner_node_id": {
"type": [
"string",
"null"
],
"description": "Node the instance is local to; `null` for a library-wide instance.",
"example": "node-7f3a9c"
}
}
}
Status 400: The body is invalid. As text/plain, when the body is not syntactically valid JSON.
{
"error": "invalid plugin instance: display_name must be at most 64 bytes without control characters"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route. 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 404: No such plugin, or it has no pinned schema.
{
"error": "settings schema of plugin source-libro not found"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 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 `plugin_key` at line 1 column 2
Schema:
A text/plain body: a string.
Status 500: The configuration could not be read or written.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
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.
DELETE /api/config/plugin-instances/{id}: removes an instance that has
no deployment left.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
idpathstringrequiredPlugin instance id.
-
200The instance was removed. Body:
PluginInstanceDeleted(application/json)2 fieldsplugin_instance_idstringrequiredId of the instance that was removed.deletedbooleanrequiredAlways true: removing an instance that is already gone answers the same way.
-
400The id is not a plugin instance id. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. A 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.
-
404No such instance. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
409The instance is a default or still deployed. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
500The configuration could not be read or written. 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/config/plugin-instances/<id>' \
-X DELETE \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugin-instances/<id>' `
-Method Delete `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.delete(
"http://127.0.0.1:8787/api/config/plugin-instances/<id>",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugin-instances/<id>", {
method: "DELETE",
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.delete("http://127.0.0.1:8787/api/config/plugin-instances/<id>")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The instance was removed.
{
"plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"deleted": true
}
Schema:
{
"type": "object",
"description": "`DELETE /api/config/plugin-instances/{id}` body.",
"required": [
"plugin_instance_id",
"deleted"
],
"properties": {
"plugin_instance_id": {
"type": "string",
"description": "Id of the instance that was removed.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"deleted": {
"type": "boolean",
"description": "Always true: removing an instance that is already gone answers the\nsame way.",
"example": true
}
}
}
Status 400: The id is not a plugin instance id.
{
"error": "invalid plugin instance id: expected a UUID"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route. 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 404: No such instance.
{
"error": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 409: The instance is a default or still deployed.
{
"error": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b still has deployments; set them absent and remove them first"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 500: The configuration could not be read or written.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
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/config/plugin-instances/{id}/config.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
idpathstringrequiredPlugin instance id.
-
200The instance's settings document (secrets as names only). Body:
PluginInstanceConfigResponse(application/json)7 fieldsplugin_instance_idstringrequiredInstance id.plugin_keystringrequiredCanonical plugin key.revisioninteger (int64)requiredCompare-and-swap revision of the document.settingsmap of string toSettingValuerequiredScalar settings the operator wrote.secret_refsarray ofInstanceSecretRefV1requiredSecret refs; ciphertext stays inencrypted_secrets.effectivemap of string to any JSONrequiredSettings as the guest sees them: schema defaults overlaid with the stored values. Empty when the plugin has no pinned schema.schemaarray ofSettingSpecrequiredDeclared settings from the pinned schema; empty when there is none.
-
400The id is not a plugin instance id. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
404No such instance, or it has no document yet. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
500The configuration could not be read. 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/config/plugin-instances/<id>/config' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugin-instances/<id>/config' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/config/plugin-instances/<id>/config",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugin-instances/<id>/config", {
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/api/config/plugin-instances/<id>/config")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The instance's settings document (secrets as names only).
{
"plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"plugin_key": "local",
"revision": 5,
"settings": {
"root": "/srv/audiobooks"
},
"secret_refs": [
{
"key": "api_token",
"name": "api_token"
}
],
"effective": {
"multi_destination": "sync_missing",
"root": "/srv/audiobooks"
},
"schema": [
{
"key": "root",
"label": "Library root",
"type": "string",
"values": [
{
"id": "sync_missing"
}
],
"default": "/srv/audiobooks",
"required": true,
"description": "Directory the finished audiobooks are written to.",
"columns": [
{}
]
}
]
}
Schema:
{
"type": "object",
"description": "`GET /api/config/plugin-instances/{id}/config` body: the stored document\nand the configuration the guest receives.",
"required": [
"plugin_instance_id",
"plugin_key",
"revision",
"settings",
"secret_refs",
"effective",
"schema"
],
"properties": {
"plugin_instance_id": {
"type": "string",
"description": "Instance id.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"plugin_key": {
"type": "string",
"description": "Canonical plugin key.",
"example": "local"
},
"revision": {
"type": "integer",
"format": "int64",
"description": "Compare-and-swap revision of the document.",
"example": 5
},
"settings": {
"type": "object",
"description": "Scalar settings the operator wrote.",
"additionalProperties": {
"oneOf": [
{
"type": "boolean",
"description": "JSON boolean."
},
{
"type": "number",
"description": "Finite JSON number: an integer kind stores an `i64`, so the schema\nis an unformatted `number` rather than a `double`.",
"examples": [
8
]
},
{
"type": "string",
"description": "JSON string, at most 1024 bytes."
},
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "boolean",
"description": "JSON boolean."
},
{
"type": "number",
"description": "Finite JSON number; an integer for integer columns.",
"examples": [
8
]
},
{
"type": "string",
"description": "JSON string, at most 1024 bytes."
}
],
"description": "One cell of a table setting row: the scalar kinds only."
},
"propertyNames": {
"type": "string"
}
},
"description": "Rows of a table setting: each row maps a column key to a scalar cell.\nRows are records rather than positional lists, so a column added to\nthe declaration later keeps existing rows valid."
}
],
"description": "One setting value: a scalar, or the rows of a table setting.",
"example": "/srv/audiobooks"
},
"propertyNames": {
"type": "string"
},
"example": {
"root": "/srv/audiobooks"
}
},
"secret_refs": {
"type": "array",
"items": {
"type": "object",
"description": "A name in `encrypted_secrets`. The ciphertext is not part of the document.",
"required": [
"key",
"name"
],
"properties": {
"key": {
"type": "string",
"description": "Key in the `SECRETS` object delivered to the guest.",
"example": "api_token"
},
"name": {
"type": "string",
"description": "`encrypted_secrets.name` for this instance.",
"example": "api_token"
}
}
},
"description": "Secret refs; ciphertext stays in `encrypted_secrets`."
},
"effective": {
"type": "object",
"description": "Settings as the guest sees them: schema defaults overlaid with the\nstored values. Empty when the plugin has no pinned schema.",
"additionalProperties": {},
"propertyNames": {
"type": "string"
},
"example": {
"multi_destination": "sync_missing",
"root": "/srv/audiobooks"
}
},
"schema": {
"type": "array",
"items": {
"type": "object",
"description": "One setting a plugin declares in its `plugin.toml` `[[settings]]`:\nits key, value type, default and help text.",
"required": [
"key",
"type"
],
"properties": {
"key": {
"type": "string",
"description": "Setting key (`[a-z][a-z0-9_]*`, at most 64 bytes).",
"example": "root"
},
"label": {
"type": [
"string",
"null"
],
"description": "Operator-facing label; omitted when the key is shown.",
"example": "Library root"
},
"type": {
"type": "string",
"description": "Value type: `string`, `bool`, `integer`, `enum`, `secret` or\n`table`.",
"enum": [
"string",
"bool",
"integer",
"enum",
"secret",
"table"
],
"example": "string"
},
"values": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "One allowed value of an `enum` setting: the stored id and its label.",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Stored value.",
"example": "sync_missing"
},
"label": {
"type": [
"string",
"null"
],
"description": "Operator-facing label; omitted when the id is shown.",
"example": "Sync missing"
}
}
},
"description": "Allowed values of an `enum` setting; omitted for other kinds."
},
"default": {
"description": "Default applied when the instance document has no value; omitted when there is none. A string, boolean or integer, or for a `table` an array of row objects, as the setting's `type` says.",
"examples": [
"/srv/audiobooks"
]
},
"required": {
"type": [
"boolean",
"null"
],
"description": "True when the instance cannot run without a value; omitted when\nfalse.",
"example": true
},
"description": {
"type": [
"string",
"null"
],
"description": "Help text shown beside the setting; omitted when there is none.",
"example": "Directory the finished audiobooks are written to."
},
"columns": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/SettingSpec"
},
"description": "Columns of a `table` setting, in display order: each a scalar entry\nnaming one field of every row. Omitted for other kinds."
}
}
},
"description": "Declared settings from the pinned schema; empty when there is none."
}
}
}
Status 400: The id is not a plugin instance id.
{
"error": "invalid plugin instance id: expected a UUID"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route.
{
"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: No such instance, or it has no document yet.
{
"error": "configuration of plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 500: The configuration could not be read.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
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.
PUT /api/config/plugin-instances/{id}/config.
Operator principal only. The route is mounted on the operator router. The document is validated against the plugin's pinned schema, so this node does not need the guest installed.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
idpathstringrequiredPlugin instance id.
application/json: PutPluginInstanceConfig
expected_revisioninteger (int64)requiredRevision the caller last observed.settingsmap of string toSettingValueScalar settings. Secret values are not accepted here.secret_refsarray of objectSecret refs to keep. Omitted refs are dropped from the document; the ciphertext stays sealed until the secret is overwritten.secretsmap of string to stringSecret values to seal, keyed by the declaredsecretsetting. Each is sealed intoencrypted_secretsand referenced from the document; the plaintext is never stored in the document or echoed back.
-
200The document after the change. Body:
PluginInstanceConfigChanged(application/json)4 fieldsplugin_instance_idstringrequiredInstance id.revisioninteger (int64)requiredRevision after the write; unchanged when the same write was replayed.settingsmap of string toSettingValuerequiredScalar settings now stored.secret_refsarray ofInstanceSecretRefV1requiredSecret refs now stored, the newly sealed secrets included.
-
400The body is invalid, or a value does not fit the pinned schema. As
text/plain, when the body is not syntactically valid JSON. Body:ErrorMessage(application/json); string (text/plain)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. A 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.
-
404No such instance, or its plugin has no pinned schema. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
409
expected_revisionis not the current revision. Body:RevisionConflict(application/json)2 fieldserrorstringrequiredAlwaysrevision_conflict.current_revisioninteger (int64)requiredThe revision to read and retry against.
- 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
500The configuration could not be read or written, or a secret was not stored. 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/config/plugin-instances/<id>/config' \
-X PUT \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{"expected_revision": 4}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugin-instances/<id>/config' `
-Method Put `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{"expected_revision": 4}'
import requests
response = requests.put(
"http://127.0.0.1:8787/api/config/plugin-instances/<id>/config",
headers={"Authorization": "Bearer <operatorToken>"},
json={"expected_revision": 4},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugin-instances/<id>/config", {
method: "PUT",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({"expected_revision": 4}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.put("http://127.0.0.1:8787/api/config/plugin-instances/<id>/config")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({"expected_revision": 4}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The document after the change.
{
"plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"revision": 6,
"settings": {
"root": "/srv/audiobooks"
},
"secret_refs": [
{
"key": "api_token",
"name": "api_token"
}
]
}
Schema:
{
"type": "object",
"description": "`PUT /api/config/plugin-instances/{id}/config` body: the document after\nthe write.",
"required": [
"plugin_instance_id",
"revision",
"settings",
"secret_refs"
],
"properties": {
"plugin_instance_id": {
"type": "string",
"description": "Instance id.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"revision": {
"type": "integer",
"format": "int64",
"description": "Revision after the write; unchanged when the same write was\nreplayed.",
"example": 6
},
"settings": {
"type": "object",
"description": "Scalar settings now stored.",
"additionalProperties": {
"oneOf": [
{
"type": "boolean",
"description": "JSON boolean."
},
{
"type": "number",
"description": "Finite JSON number: an integer kind stores an `i64`, so the schema\nis an unformatted `number` rather than a `double`.",
"examples": [
8
]
},
{
"type": "string",
"description": "JSON string, at most 1024 bytes."
},
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "boolean",
"description": "JSON boolean."
},
{
"type": "number",
"description": "Finite JSON number; an integer for integer columns.",
"examples": [
8
]
},
{
"type": "string",
"description": "JSON string, at most 1024 bytes."
}
],
"description": "One cell of a table setting row: the scalar kinds only."
},
"propertyNames": {
"type": "string"
}
},
"description": "Rows of a table setting: each row maps a column key to a scalar cell.\nRows are records rather than positional lists, so a column added to\nthe declaration later keeps existing rows valid."
}
],
"description": "One setting value: a scalar, or the rows of a table setting.",
"example": "/srv/audiobooks"
},
"propertyNames": {
"type": "string"
},
"example": {
"root": "/srv/audiobooks"
}
},
"secret_refs": {
"type": "array",
"items": {
"type": "object",
"description": "A name in `encrypted_secrets`. The ciphertext is not part of the document.",
"required": [
"key",
"name"
],
"properties": {
"key": {
"type": "string",
"description": "Key in the `SECRETS` object delivered to the guest.",
"example": "api_token"
},
"name": {
"type": "string",
"description": "`encrypted_secrets.name` for this instance.",
"example": "api_token"
}
}
},
"description": "Secret refs now stored, the newly sealed secrets included."
}
}
}
Status 400: The body is invalid, or a value does not fit the pinned schema. As text/plain, when the body is not syntactically valid JSON.
{
"error": "invalid configuration: secret `api_token` is empty"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route. 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 404: No such instance, or its plugin has no pinned schema.
{
"error": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 409: expected_revision is not the current revision.
{
"current_revision": 7,
"error": "revision_conflict"
}
Schema:
{
"type": "object",
"description": "Body of a `409 Conflict` from a compare-and-swap write whose\n`expected_revision` lost to a newer revision.",
"required": [
"error",
"current_revision"
],
"properties": {
"error": {
"type": "string",
"description": "Always `revision_conflict`.",
"example": "revision_conflict"
},
"current_revision": {
"type": "integer",
"format": "int64",
"description": "The revision to read and retry against.",
"example": 13
}
}
}
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 `expected_revision` at line 1 column 2
Schema:
A text/plain body: a string.
Status 500: The configuration could not be read or written, or a secret was not stored.
{
"error": "document revision 8 was saved but secret `api_token` was not stored (the secret store refused the write); submit the secret again"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
GET /api/config/plugin-instances/{id}/filter: which books the storage
destination takes.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
idpathstringrequiredPlugin instance id of the destination.
-
200The destination's filter. Body:
DestinationFilterResponse(application/json)3 fieldsplugin_instance_idstringrequiredThe destination's plugin instance id.revisioninteger (int64)requiredRevision of the destination'score.destinationdocument;0when none was written, so the destination takes every book.filterDestinationFilterrequiredThe filter; no rules take every book.
-
400The id is not a plugin instance id. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
404No such instance. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
500The filter could not be read. 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/config/plugin-instances/<id>/filter' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugin-instances/<id>/filter' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/config/plugin-instances/<id>/filter",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugin-instances/<id>/filter", {
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/api/config/plugin-instances/<id>/filter")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The destination's filter.
{
"plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"revision": 2,
"filter": {
"rules": [
{
"field": "patron",
"value": "audible",
"effect": "include"
}
]
}
}
Schema:
{
"type": "object",
"description": "`GET` and `PUT /api/config/plugin-instances/{id}/filter` body: which\nbooks a storage destination takes.",
"required": [
"plugin_instance_id",
"revision",
"filter"
],
"properties": {
"plugin_instance_id": {
"type": "string",
"description": "The destination's plugin instance id.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"revision": {
"type": "integer",
"format": "int64",
"description": "Revision of the destination's `core.destination` document; `0` when\nnone was written, so the destination takes every book.",
"example": 2
},
"filter": {
"type": "object",
"description": "The filter; no rules take every book.",
"properties": {
"rules": {
"type": "array",
"items": {
"type": "object",
"description": "One rule of a destination filter: a field, one value of it, and its\neffect.",
"required": [
"field",
"value",
"effect"
],
"properties": {
"field": {
"type": "string",
"description": "The field the rule matches.",
"enum": [
"patron",
"storefront",
"account",
"media_kind",
"format",
"quality"
]
},
"value": {
"type": "string",
"description": "The value: a user id for `patron`, `book` or `podcast` for\n`media_kind`, a copy format for `format`, a copy quality for\n`quality`, otherwise 1 to 128 bytes of text.",
"example": "audible"
},
"effect": {
"type": "string",
"description": "Include or exclude.",
"enum": [
"include",
"exclude"
]
}
},
"additionalProperties": false
},
"description": "Filter rules, at most 64. Empty means the destination takes every\nbook.",
"maxItems": 64
}
},
"additionalProperties": false
}
}
}
Status 400: The id is not a plugin instance id.
{
"error": "invalid plugin instance id: expected a UUID"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route.
{
"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: No such instance.
{
"error": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 500: The filter could not be read.
{
"error": "invalid core.destination: destination filter: unknown field `genre`"
}
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.
PUT /api/config/plugin-instances/{id}/filter: replaces which books the
storage destination takes. Acquires that start afterwards use it; files
already stored stay where they are.
Operator principal only. The route is mounted on the operator router.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
idpathstringrequiredPlugin instance id of the destination.
application/json: DestinationFilter
rulesarray ofFilterRuleFilter rules, at most 64. Empty means the destination takes every book. At most 64 items.
-
200The filter after the change. Body:
DestinationFilterResponse(application/json)3 fieldsplugin_instance_idstringrequiredThe destination's plugin instance id.revisioninteger (int64)requiredRevision of the destination'score.destinationdocument;0when none was written, so the destination takes every book.filterDestinationFilterrequiredThe filter; no rules take every book.
-
400The filter is invalid. As
text/plain, when the body is not syntactically valid JSON. Body:ErrorMessage(application/json); string (text/plain)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. A 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.
-
404No such instance. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
409The filter kept changing underneath the write. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
500The filter could not be read or written. 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/config/plugin-instances/<id>/filter' \
-X PUT \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugin-instances/<id>/filter' `
-Method Put `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.put(
"http://127.0.0.1:8787/api/config/plugin-instances/<id>/filter",
headers={"Authorization": "Bearer <operatorToken>"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugin-instances/<id>/filter", {
method: "PUT",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.put("http://127.0.0.1:8787/api/config/plugin-instances/<id>/filter")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The filter after the change.
{
"plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"revision": 2,
"filter": {
"rules": [
{
"field": "patron",
"value": "audible",
"effect": "include"
}
]
}
}
Schema:
{
"type": "object",
"description": "`GET` and `PUT /api/config/plugin-instances/{id}/filter` body: which\nbooks a storage destination takes.",
"required": [
"plugin_instance_id",
"revision",
"filter"
],
"properties": {
"plugin_instance_id": {
"type": "string",
"description": "The destination's plugin instance id.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"revision": {
"type": "integer",
"format": "int64",
"description": "Revision of the destination's `core.destination` document; `0` when\nnone was written, so the destination takes every book.",
"example": 2
},
"filter": {
"type": "object",
"description": "The filter; no rules take every book.",
"properties": {
"rules": {
"type": "array",
"items": {
"type": "object",
"description": "One rule of a destination filter: a field, one value of it, and its\neffect.",
"required": [
"field",
"value",
"effect"
],
"properties": {
"field": {
"type": "string",
"description": "The field the rule matches.",
"enum": [
"patron",
"storefront",
"account",
"media_kind",
"format",
"quality"
]
},
"value": {
"type": "string",
"description": "The value: a user id for `patron`, `book` or `podcast` for\n`media_kind`, a copy format for `format`, a copy quality for\n`quality`, otherwise 1 to 128 bytes of text.",
"example": "audible"
},
"effect": {
"type": "string",
"description": "Include or exclude.",
"enum": [
"include",
"exclude"
]
}
},
"additionalProperties": false
},
"description": "Filter rules, at most 64. Empty means the destination takes every\nbook.",
"maxItems": 64
}
},
"additionalProperties": false
}
}
}
Status 400: The filter is invalid. As text/plain, when the body is not syntactically valid JSON.
{
"error": "invalid: a patron rule takes a user id, not `me`"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route. 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 404: No such instance.
{
"error": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 409: The filter kept changing underneath the write.
{
"error": "the filter of destination 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b kept changing; retry"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: rules: invalid type: integer `1`, expected a sequence at line 1 column 10
Schema:
A text/plain body: a string.
Status 500: The filter could not be read or written.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
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/config/plugin-instances/{id}/intake: whether the storage
instance is a drop folder, and its settings.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
idpathstringrequiredPlugin instance id of the storage instance.
-
200The instance's drop folder settings, or
nullfor a destination. Body:IntakeResponse(application/json)3 fieldsplugin_instance_idstringrequiredThe storage instance's plugin instance id.revisioninteger (int64)requiredRevision of the instance'score.intakedocument;0when none was written, so the instance is a destination.intakeIntakeSettingsor nullThe drop folder's settings;nullwhen the instance is a destination.
-
400The id is not a plugin instance id. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
404No such instance. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
500The settings could not be read. 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/config/plugin-instances/<id>/intake' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugin-instances/<id>/intake' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/config/plugin-instances/<id>/intake",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugin-instances/<id>/intake", {
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/api/config/plugin-instances/<id>/intake")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The instance's drop folder settings, or null for a destination.
{
"plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"revision": 1,
"intake": {
"settle_seconds": 60,
"scan_interval_seconds": 300,
"after_ingest": "move",
"attribute_to": "owner",
"patron": 2,
"ignore": [
"*.nzb"
],
"prune_imported_days": 30
}
}
Schema:
{
"type": "object",
"description": "`GET`, `PUT` and `DELETE /api/config/plugin-instances/{id}/intake` body:\nwhether a storage instance is a drop folder, and its settings.",
"required": [
"plugin_instance_id",
"revision"
],
"properties": {
"plugin_instance_id": {
"type": "string",
"description": "The storage instance's plugin instance id.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"revision": {
"type": "integer",
"format": "int64",
"description": "Revision of the instance's `core.intake` document; `0` when none was\nwritten, so the instance is a destination.",
"example": 1
},
"intake": {
"oneOf": [
{
"type": "object",
"description": "The drop folder's settings; `null` when the instance is a\ndestination.",
"required": [
"settle_seconds",
"scan_interval_seconds",
"after_ingest",
"attribute_to",
"ignore"
],
"properties": {
"settle_seconds": {
"type": "integer",
"format": "int32",
"description": "Seconds an item's files must stay unchanged before it is ingested,\n5 to 86,400 (default 60).",
"example": 60,
"maximum": 86400,
"minimum": 5
},
"scan_interval_seconds": {
"type": "integer",
"format": "int32",
"description": "Seconds between two full listings of the folder, 30 to 86,400\n(default 300). A change feed starts a listing sooner.",
"example": 300,
"maximum": 86400,
"minimum": 30
},
"after_ingest": {
"type": "string",
"description": "What happens to an item once it is ingested (default `move`).",
"enum": [
"move",
"delete",
"leave"
]
},
"attribute_to": {
"type": "string",
"description": "Who holds the ingested books (default `owner`).",
"enum": [
"owner",
"subfolder"
]
},
"patron": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The user id that holds every book in `owner` mode; required there\nand refused in `subfolder` mode.",
"example": 2,
"minimum": 1
},
"ignore": {
"type": "array",
"items": {
"type": "string"
},
"description": "Extra file name patterns to ignore, at most 64, each 1 to 128 bytes\nwith no `/`: `*` matches any run of characters and `?` one\ncharacter, compared without ASCII case. The built-in list always\napplies too ([`BUILTIN_IGNORE_PATTERNS`]).",
"example": [
"*.nzb"
],
"maxItems": 64
},
"prune_imported_days": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "With `after_ingest = move`, delete `_imported` day folders older than\nthis many days, 1 to 3,650; absent keeps them.",
"example": 30,
"maximum": 3650,
"minimum": 1
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
}
}
Status 400: The id is not a plugin instance id.
{
"error": "invalid plugin instance id: expected a UUID"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route.
{
"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: No such instance.
{
"error": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 500: The settings could not be read.
{
"error": "invalid core.intake: intake settings: unknown field `colour`"
}
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.
PUT /api/config/plugin-instances/{id}/intake: makes the storage
instance a drop folder with these settings, or changes a drop folder's
settings. Turning a destination into a drop folder is refused while the
instance is deployed on any node.
Operator principal only. The route is mounted on the operator router.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
idpathstringrequiredPlugin instance id of the storage instance.
application/json: IntakeSettingsRequest
settle_secondsinteger (int32)Seconds an item's files must stay unchanged before it is ingested, 5 to 86,400 (default 60). At least 5; at most 86400.scan_interval_secondsinteger (int32)Seconds between two full listings of the folder, 30 to 86,400 (default 300). At least 30; at most 86400.after_ingestAfterIngestWhat happens to an item once it is ingested (defaultmove).attribute_toIntakeAttributionWho holds the ingested books (defaultowner).patroninteger (int64) or nullThe user id that holds every book inownermode; required there and refused insubfoldermode. It must name an active user. At least 1.ignorearray of stringExtra file name patterns to ignore, at most 64, each 1 to 128 bytes with no/(default none). At most 64 items.prune_imported_daysinteger (int32) or nullWithafter_ingest = move, delete_importedday folders older than this many days, 1 to 3,650; absent keeps them. At least 1; at most 3650.
-
200The settings after the change. Body:
IntakeResponse(application/json)3 fieldsplugin_instance_idstringrequiredThe storage instance's plugin instance id.revisioninteger (int64)requiredRevision of the instance'score.intakedocument;0when none was written, so the instance is a destination.intakeIntakeSettingsor nullThe drop folder's settings;nullwhen the instance is a destination.
-
400The body is not JSON (text), or the patron is not an active user (JSON). As
text/plain, when the body is not syntactically valid JSON. Body:ErrorMessage(application/json); string (text/plain)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. A 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.
-
404No such instance. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
409The instance is deployed, or the document kept changing. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
413The body is over 16 KiB. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 415The body is not sent as
application/json. Astext/plain, when the request did not declare a JSON body. Body: string (text/plain) - 422The settings are invalid: an unknown or repeated key, a value of the wrong type or out of range, or settings over 12 KiB written out. Body: string (
text/plain) -
500The settings could not be read or written. 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/config/plugin-instances/<id>/intake' \
-X PUT \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugin-instances/<id>/intake' `
-Method Put `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.put(
"http://127.0.0.1:8787/api/config/plugin-instances/<id>/intake",
headers={"Authorization": "Bearer <operatorToken>"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugin-instances/<id>/intake", {
method: "PUT",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.put("http://127.0.0.1:8787/api/config/plugin-instances/<id>/intake")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The settings after the change.
{
"plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"revision": 1,
"intake": {
"settle_seconds": 60,
"scan_interval_seconds": 300,
"after_ingest": "move",
"attribute_to": "owner",
"patron": 2,
"ignore": [
"*.nzb"
],
"prune_imported_days": 30
}
}
Schema:
{
"type": "object",
"description": "`GET`, `PUT` and `DELETE /api/config/plugin-instances/{id}/intake` body:\nwhether a storage instance is a drop folder, and its settings.",
"required": [
"plugin_instance_id",
"revision"
],
"properties": {
"plugin_instance_id": {
"type": "string",
"description": "The storage instance's plugin instance id.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"revision": {
"type": "integer",
"format": "int64",
"description": "Revision of the instance's `core.intake` document; `0` when none was\nwritten, so the instance is a destination.",
"example": 1
},
"intake": {
"oneOf": [
{
"type": "object",
"description": "The drop folder's settings; `null` when the instance is a\ndestination.",
"required": [
"settle_seconds",
"scan_interval_seconds",
"after_ingest",
"attribute_to",
"ignore"
],
"properties": {
"settle_seconds": {
"type": "integer",
"format": "int32",
"description": "Seconds an item's files must stay unchanged before it is ingested,\n5 to 86,400 (default 60).",
"example": 60,
"maximum": 86400,
"minimum": 5
},
"scan_interval_seconds": {
"type": "integer",
"format": "int32",
"description": "Seconds between two full listings of the folder, 30 to 86,400\n(default 300). A change feed starts a listing sooner.",
"example": 300,
"maximum": 86400,
"minimum": 30
},
"after_ingest": {
"type": "string",
"description": "What happens to an item once it is ingested (default `move`).",
"enum": [
"move",
"delete",
"leave"
]
},
"attribute_to": {
"type": "string",
"description": "Who holds the ingested books (default `owner`).",
"enum": [
"owner",
"subfolder"
]
},
"patron": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The user id that holds every book in `owner` mode; required there\nand refused in `subfolder` mode.",
"example": 2,
"minimum": 1
},
"ignore": {
"type": "array",
"items": {
"type": "string"
},
"description": "Extra file name patterns to ignore, at most 64, each 1 to 128 bytes\nwith no `/`: `*` matches any run of characters and `?` one\ncharacter, compared without ASCII case. The built-in list always\napplies too ([`BUILTIN_IGNORE_PATTERNS`]).",
"example": [
"*.nzb"
],
"maxItems": 64
},
"prune_imported_days": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "With `after_ingest = move`, delete `_imported` day folders older than\nthis many days, 1 to 3,650; absent keeps them.",
"example": 30,
"maximum": 3650,
"minimum": 1
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
}
}
Status 400: The body is not JSON (text), or the patron is not an active user (JSON). As text/plain, when the body is not syntactically valid JSON.
{
"error": "intake settings: patron 4242 is not an active user"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route. 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 404: No such instance.
{
"error": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 409: The instance is deployed, or the document kept changing.
{
"error": "storage instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b is deployed on node-a; undeploy it before changing whether it is a drop folder"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 413: The body is over 16 KiB.
{
"error": "the body is at most 16384 bytes"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 415: The body is not sent as application/json. As text/plain, when 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 settings are invalid: an unknown or repeated key, a value of the wrong type or out of range, or settings over 12 KiB written out.
Failed to deserialize the JSON body into the target type: intake settings: attribute_to = owner needs a patron user id at line 1 column 2
Schema:
A text/plain body: a string.
Status 500: The settings could not be read or written.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
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.
DELETE /api/config/plugin-instances/{id}/intake: makes a drop folder a
destination again. Refused while the instance is deployed on any node.
Operator principal only. The route is mounted on the operator router.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
idpathstringrequiredPlugin instance id of the storage instance.
-
200The instance is a destination. Body:
IntakeResponse(application/json)3 fieldsplugin_instance_idstringrequiredThe storage instance's plugin instance id.revisioninteger (int64)requiredRevision of the instance'score.intakedocument;0when none was written, so the instance is a destination.intakeIntakeSettingsor nullThe drop folder's settings;nullwhen the instance is a destination.
-
400The id is not a plugin instance id. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. A 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.
-
404No such instance. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
409The instance is deployed, or the document kept changing. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
500The document could not be read or written. 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/config/plugin-instances/<id>/intake' \
-X DELETE \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugin-instances/<id>/intake' `
-Method Delete `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.delete(
"http://127.0.0.1:8787/api/config/plugin-instances/<id>/intake",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugin-instances/<id>/intake", {
method: "DELETE",
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.delete("http://127.0.0.1:8787/api/config/plugin-instances/<id>/intake")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The instance is a destination.
{
"plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"revision": 1,
"intake": {
"settle_seconds": 60,
"scan_interval_seconds": 300,
"after_ingest": "move",
"attribute_to": "owner",
"patron": 2,
"ignore": [
"*.nzb"
],
"prune_imported_days": 30
}
}
Schema:
{
"type": "object",
"description": "`GET`, `PUT` and `DELETE /api/config/plugin-instances/{id}/intake` body:\nwhether a storage instance is a drop folder, and its settings.",
"required": [
"plugin_instance_id",
"revision"
],
"properties": {
"plugin_instance_id": {
"type": "string",
"description": "The storage instance's plugin instance id.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"revision": {
"type": "integer",
"format": "int64",
"description": "Revision of the instance's `core.intake` document; `0` when none was\nwritten, so the instance is a destination.",
"example": 1
},
"intake": {
"oneOf": [
{
"type": "object",
"description": "The drop folder's settings; `null` when the instance is a\ndestination.",
"required": [
"settle_seconds",
"scan_interval_seconds",
"after_ingest",
"attribute_to",
"ignore"
],
"properties": {
"settle_seconds": {
"type": "integer",
"format": "int32",
"description": "Seconds an item's files must stay unchanged before it is ingested,\n5 to 86,400 (default 60).",
"example": 60,
"maximum": 86400,
"minimum": 5
},
"scan_interval_seconds": {
"type": "integer",
"format": "int32",
"description": "Seconds between two full listings of the folder, 30 to 86,400\n(default 300). A change feed starts a listing sooner.",
"example": 300,
"maximum": 86400,
"minimum": 30
},
"after_ingest": {
"type": "string",
"description": "What happens to an item once it is ingested (default `move`).",
"enum": [
"move",
"delete",
"leave"
]
},
"attribute_to": {
"type": "string",
"description": "Who holds the ingested books (default `owner`).",
"enum": [
"owner",
"subfolder"
]
},
"patron": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "The user id that holds every book in `owner` mode; required there\nand refused in `subfolder` mode.",
"example": 2,
"minimum": 1
},
"ignore": {
"type": "array",
"items": {
"type": "string"
},
"description": "Extra file name patterns to ignore, at most 64, each 1 to 128 bytes\nwith no `/`: `*` matches any run of characters and `?` one\ncharacter, compared without ASCII case. The built-in list always\napplies too ([`BUILTIN_IGNORE_PATTERNS`]).",
"example": [
"*.nzb"
],
"maxItems": 64
},
"prune_imported_days": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "With `after_ingest = move`, delete `_imported` day folders older than\nthis many days, 1 to 3,650; absent keeps them.",
"example": 30,
"maximum": 3650,
"minimum": 1
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
}
}
Status 400: The id is not a plugin instance id.
{
"error": "invalid plugin instance id: expected a UUID"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route. 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 404: No such instance.
{
"error": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 409: The instance is deployed, or the document kept changing.
{
"error": "storage instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b is deployed on node-a; undeploy it before changing whether it is a drop folder"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 500: The document could not be read or written.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
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.
PUT /api/config/plugin-instances/{id}/deployments/{node_id}: the
Deployed switch. Creates the row when the node has none.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
idpathstringrequiredPlugin instance id.node_idpathstringrequiredNode id.
application/json: PutPluginDeployment
desiredDesiredStaterequiredWhat the node should do:presentorabsent(the scheduler'splaced/unplacedare accepted too).expected_revisioninteger (int64) or nullRevision the caller last observed; required when the row exists and the caller wants compare-and-swap. Omitted means "replace whatever is current".
-
200The deployment after the change. Body:
PluginDeploymentChanged(application/json)5 fieldsdeployment_idstringrequiredDeployment row id.plugin_instance_idstringrequiredInstance the row belongs to.node_idstringrequiredNode the row targets.desiredDesiredStaterequiredDesired state now stored.revisioninteger (int64)requiredCompare-and-swap revision after the write.
-
400The body is invalid. As
text/plain, when the body is not syntactically valid JSON. Body:ErrorMessage(application/json); string (text/plain)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. A 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.
-
404No such instance or node. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 409The instance is placed by the scheduler (an
errormessage), orexpected_revisionis stale (revision_conflictwithcurrent_revision). Body:DeploymentConflict(application/json) - 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
500The configuration could not be read or written. 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/config/plugin-instances/<id>/deployments/<node_id>' \
-X PUT \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{"desired": "present"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugin-instances/<id>/deployments/<node_id>' `
-Method Put `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{"desired": "present"}'
import requests
response = requests.put(
"http://127.0.0.1:8787/api/config/plugin-instances/<id>/deployments/<node_id>",
headers={"Authorization": "Bearer <operatorToken>"},
json={"desired": "present"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugin-instances/<id>/deployments/<node_id>", {
method: "PUT",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({"desired": "present"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.put("http://127.0.0.1:8787/api/config/plugin-instances/<id>/deployments/<node_id>")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({"desired": "present"}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The deployment after the change.
{
"deployment_id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"node_id": "node-7f3a9c",
"desired": "present",
"revision": 4
}
Schema:
{
"type": "object",
"description": "`PUT /api/config/plugin-instances/{id}/deployments/{node_id}` body: the\ndeployment row after the write.",
"required": [
"deployment_id",
"plugin_instance_id",
"node_id",
"desired",
"revision"
],
"properties": {
"deployment_id": {
"type": "string",
"description": "Deployment row id.",
"example": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
},
"plugin_instance_id": {
"type": "string",
"description": "Instance the row belongs to.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"node_id": {
"type": "string",
"description": "Node the row targets.",
"example": "node-7f3a9c"
},
"desired": {
"type": "string",
"description": "Desired state now stored.",
"enum": [
"present",
"absent",
"placed",
"unplaced"
]
},
"revision": {
"type": "integer",
"format": "int64",
"description": "Compare-and-swap revision after the write.",
"example": 4
}
}
}
Status 400: The body is invalid. As text/plain, when the body is not syntactically valid JSON.
{
"error": "invalid configuration: desired must be `present`, `absent`, `placed`, or `unplaced`"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route. 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 404: No such instance or node.
{
"error": "node 9b1c7d2e-4f3a-4b6c-8d1e-2f3a4b5c6d7e not found"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 409: The instance is placed by the scheduler (an error message), or expected_revision is stale (revision_conflict with current_revision).
{
"error": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b is placed by the scheduler (2 replica(s) on region=eu); change it with `bookclerk plugins deploy`, or drop the placement with `bookclerk plugins deploy --manual` first"
}
Schema:
{
"anyOf": [
{
"type": "object",
"description": "`expected_revision` lost to a newer revision of the row.",
"required": [
"error",
"current_revision"
],
"properties": {
"error": {
"type": "string",
"description": "Always `revision_conflict`.",
"example": "revision_conflict"
},
"current_revision": {
"type": "integer",
"format": "int64",
"description": "The revision to read and retry against.",
"example": 13
}
}
},
{
"type": "object",
"description": "The scheduler places the instance, so its deployments are not hand-managed; `error` says so and names the way out.",
"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"
}
}
}
],
"description": "`PUT /api/config/plugin-instances/{id}/deployments/{node_id}` `409` body: the two conflicts a deployment write can hit."
}
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 `desired` at line 1 column 2
Schema:
A text/plain body: a string.
Status 500: The configuration could not be read or written.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
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.
PUT /api/config/plugin-instances/{id}/placement: hand the instance's
deployments to the scheduler with a replica count and constraints.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
idpathstringrequiredPlugin instance id.
application/json: PutPluginPlacement
replicasinteger orallrequiredA replica count (0 stops every replica) or"all".constraintsarray of stringLabel constraints (name,name=value,!name).expected_revisioninteger (int64) or nullCurrent revision to replace; omit (or 0) to create.
-
200The scheduler now places the instance. Body:
PluginPlacementChanged(application/json)2 fieldsplugin_instance_idstringrequiredInstance the scheduler now places.placementPlacementViewrequiredThe stored intent and the last scheduler pass's result.
-
400The body is invalid. As
text/plain, when the body is not syntactically valid JSON. Body:ErrorMessage(application/json); string (text/plain)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. A 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.
-
404No such instance. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
409
expected_revisionis not the current revision. Body:RevisionConflict(application/json)2 fieldserrorstringrequiredAlwaysrevision_conflict.current_revisioninteger (int64)requiredThe revision to read and retry against.
- 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
500The configuration could not be read or written. 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/config/plugin-instances/<id>/placement' \
-X PUT \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{"replicas": 0}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugin-instances/<id>/placement' `
-Method Put `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{"replicas": 0}'
import requests
response = requests.put(
"http://127.0.0.1:8787/api/config/plugin-instances/<id>/placement",
headers={"Authorization": "Bearer <operatorToken>"},
json={"replicas": 0},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugin-instances/<id>/placement", {
method: "PUT",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({"replicas": 0}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.put("http://127.0.0.1:8787/api/config/plugin-instances/<id>/placement")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({"replicas": 0}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The scheduler now places the instance.
{
"plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"placement": {
"replicas": 0,
"constraints": [
"target=linux-x64-gnu",
"!drain"
],
"revision": 2,
"placed": 1,
"detail": "",
"scheduled_at": "2026-10-28T19:07:00Z",
"updated_at": "2026-10-28T19:05:00Z"
}
}
Schema:
{
"type": "object",
"description": "`PUT /api/config/plugin-instances/{id}/placement` body: the placement\nafter the write.",
"required": [
"plugin_instance_id",
"placement"
],
"properties": {
"plugin_instance_id": {
"type": "string",
"description": "Instance the scheduler now places.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"placement": {
"type": "object",
"description": "The stored intent and the last scheduler pass's result.",
"required": [
"replicas",
"constraints",
"revision",
"placed",
"detail",
"scheduled_at",
"updated_at"
],
"properties": {
"replicas": {
"oneOf": [
{
"type": "integer",
"minimum": 0
},
{
"type": "string",
"enum": [
"all"
]
}
],
"description": "A replica count (0 stops every replica) or `\"all\"`."
},
"constraints": {
"type": "array",
"items": {
"type": "string"
},
"description": "Label constraints every chosen node must satisfy.",
"example": [
"target=linux-x64-gnu",
"!drain"
]
},
"revision": {
"type": "integer",
"format": "int64",
"description": "Compare-and-swap revision of the intent.",
"example": 2
},
"placed": {
"type": "integer",
"format": "int32",
"description": "Replicas the last scheduler pass placed.",
"example": 1,
"minimum": 0
},
"detail": {
"type": "string",
"description": "Why fewer than requested are placed; empty when satisfied.",
"example": ""
},
"scheduled_at": {
"type": "string",
"description": "RFC 3339 time the scheduler last changed the status.",
"example": "2026-10-28T19:07:00Z"
},
"updated_at": {
"type": "string",
"description": "RFC 3339 time of the last intent write.",
"example": "2026-10-28T19:05:00Z"
}
}
}
}
}
Status 400: The body is invalid. As text/plain, when the body is not syntactically valid JSON.
{
"error": "invalid configuration: replicas must be at most 64"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route. 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 404: No such instance.
{
"error": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 409: expected_revision is not the current revision.
{
"current_revision": 7,
"error": "revision_conflict"
}
Schema:
{
"type": "object",
"description": "Body of a `409 Conflict` from a compare-and-swap write whose\n`expected_revision` lost to a newer revision.",
"required": [
"error",
"current_revision"
],
"properties": {
"error": {
"type": "string",
"description": "Always `revision_conflict`.",
"example": "revision_conflict"
},
"current_revision": {
"type": "integer",
"format": "int64",
"description": "The revision to read and retry against.",
"example": 13
}
}
}
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 `replicas` at line 1 column 2
Schema:
A text/plain body: a string.
Status 500: The configuration could not be read or written.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
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.
DELETE /api/config/plugin-instances/{id}/placement: return the
instance to hand-managed deployments; its deployments stay as they
are.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
idpathstringrequiredPlugin instance id.
-
200The instance is back to manual deployment. Body:
PluginPlacementDeleted(application/json)2 fieldsplugin_instance_idstringrequiredInstance that is hand-managed again.deletedbooleanrequiredTrue when a placement existed and was removed; false when the instance was hand-managed already.
-
400The id is not a plugin instance id. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. A 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.
-
404No such instance. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
500The configuration could not be read or written. 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/config/plugin-instances/<id>/placement' \
-X DELETE \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugin-instances/<id>/placement' `
-Method Delete `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.delete(
"http://127.0.0.1:8787/api/config/plugin-instances/<id>/placement",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugin-instances/<id>/placement", {
method: "DELETE",
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.delete("http://127.0.0.1:8787/api/config/plugin-instances/<id>/placement")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The instance is back to manual deployment.
{
"plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"deleted": true
}
Schema:
{
"type": "object",
"description": "`DELETE /api/config/plugin-instances/{id}/placement` body.",
"required": [
"plugin_instance_id",
"deleted"
],
"properties": {
"plugin_instance_id": {
"type": "string",
"description": "Instance that is hand-managed again.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"deleted": {
"type": "boolean",
"description": "True when a placement existed and was removed; false when the\ninstance was hand-managed already.",
"example": true
}
}
}
Status 400: The id is not a plugin instance id.
{
"error": "invalid plugin instance id: expected a UUID"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route. 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 404: No such instance.
{
"error": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 500: The configuration could not be read or written.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
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/config/plugins: every installed plugin.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
-
200Every installed plugin. Body:
InstalledPluginsResponse(application/json)1 fieldpluginsarray ofInstalledPluginSummaryrequiredEvery plugin with at least one installed version, by key.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
500The configuration could not be read. 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/config/plugins' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugins' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/config/plugins",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugins", {
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/api/config/plugins")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: Every installed plugin.
{
"plugins": [
{
"plugin_key": "libro",
"id": "libro",
"active_version": "0.4.2",
"revision": 3,
"versions": [
{
"plugin_key": "libro",
"id": "libro",
"version": "0.4.2",
"active": true,
"approved": true,
"publisher_verified": true,
"coordinate": "registry:plugins.example#source-libro@0.4.2",
"installed_at": "2026-10-20T10:15:00Z",
"installed_by": "operator",
"artifacts": []
}
]
}
]
}
Schema:
{
"type": "object",
"description": "`GET /api/config/plugins` body.",
"required": [
"plugins"
],
"properties": {
"plugins": {
"type": "array",
"items": {
"type": "object",
"description": "One installed plugin: its active version and every installed version,\nnewest first.",
"required": [
"plugin_key",
"versions"
],
"properties": {
"plugin_key": {
"type": "string",
"description": "Canonical plugin key.",
"example": "libro"
},
"id": {
"type": [
"string",
"null"
],
"description": "Manifest id (display alias) of the active version, or of the newest\none when none is active; `null` without versions.",
"example": "libro"
},
"active_version": {
"type": [
"string",
"null"
],
"description": "Active version; `null` when the plugin is installed but not\nactivated.",
"example": "0.4.2"
},
"revision": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Compare-and-swap revision of the active-version pointer; `null`\nwhen nothing is active.",
"example": 3
},
"versions": {
"type": "array",
"items": {
"type": "object",
"description": "One installed version of a plugin, as the API renders it.",
"required": [
"plugin_key",
"id",
"version",
"active",
"approved",
"publisher_verified",
"coordinate",
"installed_at",
"installed_by",
"artifacts"
],
"properties": {
"plugin_key": {
"type": "string",
"description": "Canonical plugin key.",
"example": "libro"
},
"id": {
"type": "string",
"description": "Manifest id (display alias).",
"example": "libro"
},
"version": {
"type": "string",
"description": "Semver package version.",
"example": "0.4.2"
},
"active": {
"type": "boolean",
"description": "True when this is the plugin's active version.",
"example": true
},
"approved": {
"type": "boolean",
"description": "True once an operator approved the version's consent request.",
"example": true
},
"publisher_verified": {
"type": "boolean",
"description": "True when the publisher was verified at install time.",
"example": true
},
"coordinate": {
"type": "string",
"description": "Package coordinate the version was resolved from; empty for a local\narchive.",
"example": "registry:plugins.example#source-libro@0.4.2"
},
"installed_at": {
"type": "string",
"description": "RFC 3339 install time.",
"example": "2026-10-20T10:15:00Z"
},
"installed_by": {
"type": "string",
"description": "Audit identity of the installer.",
"example": "operator"
},
"host_payload_root_sha256": {
"type": [
"string",
"null"
],
"description": "Payload-root digest of the artifact this host would run; `null` when\nno artifact fits the host's target.",
"example": "1f2e3d4c5b6a79880970a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5"
},
"artifacts": {
"type": "array",
"items": {
"type": "object",
"description": "One downloadable artifact of an installed version, as the API renders\nit.",
"required": [
"target",
"url",
"archive_sha256",
"payload_root_sha256"
],
"properties": {
"target": {
"type": "string",
"description": "Bookclerk target (`linux-x64-gnu`, …; `any` for workerd packages).",
"example": "linux-x64-gnu"
},
"url": {
"type": "string",
"description": "Where nodes fetch the archive: `https:`, `file:`, or\n`blob:sha256:<hex>`.",
"example": "https://plugins.example/source-libro-0.4.2-linux-x64-gnu.tar.gz"
},
"archive_sha256": {
"type": "string",
"description": "Lowercase hex SHA-256 of the archive bytes.",
"example": "9b74c9897bac770ffc029102a200c5de3f4b2b1a0b5e6c7d8e9f0a1b2c3d4e5f"
},
"payload_root_sha256": {
"type": "string",
"description": "Payload-root digest of the extracted plugin tree.",
"example": "1f2e3d4c5b6a79880970a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5"
}
}
},
"description": "Per-target artifacts."
}
}
},
"description": "Every installed version, newest first."
}
}
},
"description": "Every plugin with at least one installed version, by key."
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route.
{
"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 500: The configuration could not be read.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
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/config/plugins: install (and maybe activate) a version.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
application/json: PostPluginInstall
coordinatestring or nullRegistry coordinate (cargo:…@v,registry:…#name@v).packagestring or nullOperator-placed package directory underplugin-packages/.activatebooleanMake the new version active even when another is.approvebooleanRecord the requested consent as approved.allow_unverified_publisherbooleanAccept a publisher without independent authenticity.
-
200The installed version. Body:
PluginInstalled(application/json)3 fieldscreatedbooleanrequiredTrue when the version row was written now; false when the same version with the same artifacts was installed already.plugin_instance_idstringrequiredId of the plugin's default instance.versionPluginVersionSummaryrequiredThe installed version.
-
400The body is invalid: neither or both of
coordinateandpackage, a malformed coordinate or package name, or a manifest the host rejects. Astext/plain, when the body is not syntactically valid JSON. Body:ErrorMessage(application/json); string (text/plain)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The publisher is unverified and
allow_unverified_publisheris off. A write sent with a session cookie but without a matchingOriginorRefereris refused. Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
404A local package is missing its
package.jsonorarchive.tar.gz. Body:ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
409The version is already installed with different artifacts. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
500The node identity could not be read or created, or the catalog lookup task failed. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
502The package registry could not be reached or answered badly. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
503The database plugin is unavailable; retry. 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/config/plugins' \
-X POST \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugins' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{}'
import requests
response = requests.post(
"http://127.0.0.1:8787/api/config/plugins",
headers={"Authorization": "Bearer <operatorToken>"},
json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugins", {
method: "POST",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/config/plugins")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The installed version.
{
"created": true,
"plugin_instance_id": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"version": {
"plugin_key": "libro",
"id": "libro",
"version": "0.4.2",
"active": true,
"approved": true,
"publisher_verified": true,
"coordinate": "registry:plugins.example#source-libro@0.4.2",
"installed_at": "2026-10-20T10:15:00Z",
"installed_by": "operator",
"host_payload_root_sha256": "1f2e3d4c5b6a79880970a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5",
"artifacts": [
{
"target": "linux-x64-gnu",
"url": "https://plugins.example/source-libro-0.4.2-linux-x64-gnu.tar.gz",
"archive_sha256": "9b74c9897bac770ffc029102a200c5de3f4b2b1a0b5e6c7d8e9f0a1b2c3d4e5f",
"payload_root_sha256": "1f2e3d4c5b6a79880970a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5"
}
]
}
}
Schema:
{
"type": "object",
"description": "`POST /api/config/plugins` body: what the install did.",
"required": [
"created",
"plugin_instance_id",
"version"
],
"properties": {
"created": {
"type": "boolean",
"description": "True when the version row was written now; false when the same\nversion with the same artifacts was installed already.",
"example": true
},
"plugin_instance_id": {
"type": "string",
"description": "Id of the plugin's default instance.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"version": {
"type": "object",
"description": "The installed version.",
"required": [
"plugin_key",
"id",
"version",
"active",
"approved",
"publisher_verified",
"coordinate",
"installed_at",
"installed_by",
"artifacts"
],
"properties": {
"plugin_key": {
"type": "string",
"description": "Canonical plugin key.",
"example": "libro"
},
"id": {
"type": "string",
"description": "Manifest id (display alias).",
"example": "libro"
},
"version": {
"type": "string",
"description": "Semver package version.",
"example": "0.4.2"
},
"active": {
"type": "boolean",
"description": "True when this is the plugin's active version.",
"example": true
},
"approved": {
"type": "boolean",
"description": "True once an operator approved the version's consent request.",
"example": true
},
"publisher_verified": {
"type": "boolean",
"description": "True when the publisher was verified at install time.",
"example": true
},
"coordinate": {
"type": "string",
"description": "Package coordinate the version was resolved from; empty for a local\narchive.",
"example": "registry:plugins.example#source-libro@0.4.2"
},
"installed_at": {
"type": "string",
"description": "RFC 3339 install time.",
"example": "2026-10-20T10:15:00Z"
},
"installed_by": {
"type": "string",
"description": "Audit identity of the installer.",
"example": "operator"
},
"host_payload_root_sha256": {
"type": [
"string",
"null"
],
"description": "Payload-root digest of the artifact this host would run; `null` when\nno artifact fits the host's target.",
"example": "1f2e3d4c5b6a79880970a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5"
},
"artifacts": {
"type": "array",
"items": {
"type": "object",
"description": "One downloadable artifact of an installed version, as the API renders\nit.",
"required": [
"target",
"url",
"archive_sha256",
"payload_root_sha256"
],
"properties": {
"target": {
"type": "string",
"description": "Bookclerk target (`linux-x64-gnu`, …; `any` for workerd packages).",
"example": "linux-x64-gnu"
},
"url": {
"type": "string",
"description": "Where nodes fetch the archive: `https:`, `file:`, or\n`blob:sha256:<hex>`.",
"example": "https://plugins.example/source-libro-0.4.2-linux-x64-gnu.tar.gz"
},
"archive_sha256": {
"type": "string",
"description": "Lowercase hex SHA-256 of the archive bytes.",
"example": "9b74c9897bac770ffc029102a200c5de3f4b2b1a0b5e6c7d8e9f0a1b2c3d4e5f"
},
"payload_root_sha256": {
"type": "string",
"description": "Payload-root digest of the extracted plugin tree.",
"example": "1f2e3d4c5b6a79880970a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5"
}
}
},
"description": "Per-target artifacts."
}
}
}
}
}
Status 400: The body is invalid: neither or both of coordinate and package, a malformed coordinate or package name, or a manifest the host rejects. As text/plain, when the body is not syntactically valid JSON.
{
"error": "pass exactly one of `coordinate` or `package`"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The publisher is unverified and allow_unverified_publisher is off. A write sent with a session cookie but without a matching Origin or Referer is refused.
{
"error": "refusing community plugin without an explicit operator override; pass --allow-unverified-publisher after verifying the digest (API: set `allow_unverified_publisher: true` in the request body)"
}
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 404: A local package is missing its package.json or archive.tar.gz.
{
"error": "archive.tar.gz is missing"
}
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 version is already installed with different artifacts.
{
"error": "version source-libro 0.4.2 is already installed with different content; install a new version"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 415: The request did not declare a JSON body.
Expected request with `Content-Type: application/json`
Schema:
A text/plain body: a string.
Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.
Failed to deserialize the JSON body into the target type: coordinate: invalid type: integer `1`, expected a string at line 1 column 15
Schema:
A text/plain body: a string.
Status 500: The node identity could not be read or created, or the catalog lookup task failed.
{
"error": "I/O error: Permission denied (os error 13)"
}
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 502: The package registry could not be reached or answered badly.
{
"error": "download failed: http status: 404"
}
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 database plugin is unavailable; retry.
{
"error": "unavailable: D1 ambiguous commit"
}
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/config/plugins/{key}: one installed plugin with its pinned
settings schema.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
keypathstringrequiredPlugin key.
-
200The plugin with its installed versions and pinned schema. Body:
InstalledPluginDetail(application/json)1 fieldschemaPinnedSchemaSummaryor nullThe pinned settings schema;nulluntil a node pins one.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
404No such plugin. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
500The configuration could not be read. 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/config/plugins/<key>' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugins/<key>' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/config/plugins/<key>",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugins/<key>", {
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/api/config/plugins/<key>")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The plugin with its installed versions and pinned schema.
{
"plugin_key": "libro",
"id": "libro",
"active_version": "0.4.2",
"revision": 3,
"versions": [
{
"plugin_key": "libro",
"id": "libro",
"version": "0.4.2",
"active": true,
"approved": true,
"publisher_verified": true,
"coordinate": "registry:plugins.example#source-libro@0.4.2",
"installed_at": "2026-10-20T10:15:00Z",
"installed_by": "operator",
"host_payload_root_sha256": "1f2e3d4c5b6a79880970a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5",
"artifacts": [
{
"target": "linux-x64-gnu",
"url": "https://plugins.example/source-libro-0.4.2-linux-x64-gnu.tar.gz",
"archive_sha256": "9b74c9897bac770ffc029102a200c5de3f4b2b1a0b5e6c7d8e9f0a1b2c3d4e5f",
"payload_root_sha256": "1f2e3d4c5b6a79880970a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5"
}
]
}
],
"schema": {
"manifest_id": "libro",
"schema_sha256": "4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8091",
"package_version": "0.4.2",
"recorded_at": "2026-10-20T10:15:05Z",
"recorded_by_node": "node-7f3a9c",
"settings": [
{
"key": "root",
"label": "Library root",
"type": "string",
"values": [],
"default": "/srv/audiobooks",
"required": true,
"description": "Directory the finished audiobooks are written to.",
"columns": []
}
]
}
}
Schema:
{
"allOf": [
{
"type": "object",
"description": "The plugin with its versions.",
"required": [
"plugin_key",
"versions"
],
"properties": {
"plugin_key": {
"type": "string",
"description": "Canonical plugin key.",
"example": "libro"
},
"id": {
"type": [
"string",
"null"
],
"description": "Manifest id (display alias) of the active version, or of the newest\none when none is active; `null` without versions.",
"example": "libro"
},
"active_version": {
"type": [
"string",
"null"
],
"description": "Active version; `null` when the plugin is installed but not\nactivated.",
"example": "0.4.2"
},
"revision": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Compare-and-swap revision of the active-version pointer; `null`\nwhen nothing is active.",
"example": 3
},
"versions": {
"type": "array",
"items": {
"type": "object",
"description": "One installed version of a plugin, as the API renders it.",
"required": [
"plugin_key",
"id",
"version",
"active",
"approved",
"publisher_verified",
"coordinate",
"installed_at",
"installed_by",
"artifacts"
],
"properties": {
"plugin_key": {
"type": "string",
"description": "Canonical plugin key.",
"example": "libro"
},
"id": {
"type": "string",
"description": "Manifest id (display alias).",
"example": "libro"
},
"version": {
"type": "string",
"description": "Semver package version.",
"example": "0.4.2"
},
"active": {
"type": "boolean",
"description": "True when this is the plugin's active version.",
"example": true
},
"approved": {
"type": "boolean",
"description": "True once an operator approved the version's consent request.",
"example": true
},
"publisher_verified": {
"type": "boolean",
"description": "True when the publisher was verified at install time.",
"example": true
},
"coordinate": {
"type": "string",
"description": "Package coordinate the version was resolved from; empty for a local\narchive.",
"example": "registry:plugins.example#source-libro@0.4.2"
},
"installed_at": {
"type": "string",
"description": "RFC 3339 install time.",
"example": "2026-10-20T10:15:00Z"
},
"installed_by": {
"type": "string",
"description": "Audit identity of the installer.",
"example": "operator"
},
"host_payload_root_sha256": {
"type": [
"string",
"null"
],
"description": "Payload-root digest of the artifact this host would run; `null` when\nno artifact fits the host's target.",
"example": "1f2e3d4c5b6a79880970a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5"
},
"artifacts": {
"type": "array",
"items": {
"type": "object",
"description": "One downloadable artifact of an installed version, as the API renders\nit.",
"required": [
"target",
"url",
"archive_sha256",
"payload_root_sha256"
],
"properties": {
"target": {
"type": "string",
"description": "Bookclerk target (`linux-x64-gnu`, …; `any` for workerd packages).",
"example": "linux-x64-gnu"
},
"url": {
"type": "string",
"description": "Where nodes fetch the archive: `https:`, `file:`, or\n`blob:sha256:<hex>`.",
"example": "https://plugins.example/source-libro-0.4.2-linux-x64-gnu.tar.gz"
},
"archive_sha256": {
"type": "string",
"description": "Lowercase hex SHA-256 of the archive bytes.",
"example": "9b74c9897bac770ffc029102a200c5de3f4b2b1a0b5e6c7d8e9f0a1b2c3d4e5f"
},
"payload_root_sha256": {
"type": "string",
"description": "Payload-root digest of the extracted plugin tree.",
"example": "1f2e3d4c5b6a79880970a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5"
}
}
},
"description": "Per-target artifacts."
}
}
},
"description": "Every installed version, newest first."
}
}
},
{
"type": "object",
"properties": {
"schema": {
"oneOf": [
{
"type": "object",
"description": "The pinned settings schema; `null` until a node pins one.",
"required": [
"manifest_id",
"schema_sha256",
"package_version",
"recorded_at",
"recorded_by_node",
"settings"
],
"properties": {
"manifest_id": {
"type": "string",
"description": "Manifest id (display alias) at pin time.",
"example": "libro"
},
"schema_sha256": {
"type": "string",
"description": "Fingerprint of the normalized schema.",
"example": "4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8091"
},
"package_version": {
"type": "string",
"description": "Semver package version that produced the pinned schema.",
"example": "0.4.2"
},
"recorded_at": {
"type": "string",
"description": "RFC 3339 time of the last pin.",
"example": "2026-10-20T10:15:05Z"
},
"recorded_by_node": {
"type": "string",
"description": "Node that recorded the last pin.",
"example": "node-7f3a9c"
},
"settings": {
"type": "array",
"items": {
"type": "object",
"description": "One setting a plugin declares in its `plugin.toml` `[[settings]]`:\nits key, value type, default and help text.",
"required": [
"key",
"type"
],
"properties": {
"key": {
"type": "string",
"description": "Setting key (`[a-z][a-z0-9_]*`, at most 64 bytes).",
"example": "root"
},
"label": {
"type": [
"string",
"null"
],
"description": "Operator-facing label; omitted when the key is shown.",
"example": "Library root"
},
"type": {
"type": "string",
"description": "Value type: `string`, `bool`, `integer`, `enum`, `secret` or\n`table`.",
"enum": [
"string",
"bool",
"integer",
"enum",
"secret",
"table"
],
"example": "string"
},
"values": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"description": "One allowed value of an `enum` setting: the stored id and its label.",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Stored value.",
"example": "sync_missing"
},
"label": {
"type": [
"string",
"null"
],
"description": "Operator-facing label; omitted when the id is shown.",
"example": "Sync missing"
}
}
},
"description": "Allowed values of an `enum` setting; omitted for other kinds."
},
"default": {
"description": "Default applied when the instance document has no value; omitted when there is none. A string, boolean or integer, or for a `table` an array of row objects, as the setting's `type` says.",
"examples": [
"/srv/audiobooks"
]
},
"required": {
"type": [
"boolean",
"null"
],
"description": "True when the instance cannot run without a value; omitted when\nfalse.",
"example": true
},
"description": {
"type": [
"string",
"null"
],
"description": "Help text shown beside the setting; omitted when there is none.",
"example": "Directory the finished audiobooks are written to."
},
"columns": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/components/schemas/SettingSpec"
},
"description": "Columns of a `table` setting, in display order: each a scalar entry\nnaming one field of every row. Omitted for other kinds."
}
}
},
"description": "Declared settings."
}
}
},
{
"type": "null"
}
]
}
}
}
],
"description": "`GET /api/config/plugins/{key}` body: the plugin and its pinned schema."
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route.
{
"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: No such plugin.
{
"error": "plugin source-libro is not installed"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 500: The configuration could not be read.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
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.
DELETE /api/config/plugins/{key}: uninstall the plugin (active version
cleared, placements dropped, every deployment absent).
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
keypathstringrequiredPlugin key.
-
200The plugin was uninstalled;
uninstalledis false when no version was active, so the request is idempotent. Body:PluginUninstalled(application/json)3 fieldsplugin_keystringrequiredCanonical plugin key.uninstalledbooleanrequiredTrue when an active-version pointer existed and was cleared.deployments_undeployedintegerrequiredDeployment rows switched toabsentacross the plugin's instances. At least 0.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. A 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.
-
409A deployment changed under the request. The install was not cleared, but deployments of earlier instances may already be stopped; retry the request. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
500The configuration could not be read or written. 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/config/plugins/<key>' \
-X DELETE \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugins/<key>' `
-Method Delete `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.delete(
"http://127.0.0.1:8787/api/config/plugins/<key>",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugins/<key>", {
method: "DELETE",
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.delete("http://127.0.0.1:8787/api/config/plugins/<key>")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The plugin was uninstalled; uninstalled is false when no version was active, so the request is idempotent.
{
"plugin_key": "libro",
"uninstalled": true,
"deployments_undeployed": 2
}
Schema:
{
"type": "object",
"description": "`DELETE /api/config/plugins/{key}` body.",
"required": [
"plugin_key",
"uninstalled",
"deployments_undeployed"
],
"properties": {
"plugin_key": {
"type": "string",
"description": "Canonical plugin key.",
"example": "libro"
},
"uninstalled": {
"type": "boolean",
"description": "True when an active-version pointer existed and was cleared.",
"example": true
},
"deployments_undeployed": {
"type": "integer",
"description": "Deployment rows switched to `absent` across the plugin's instances.",
"example": 2,
"minimum": 0
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route. A 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 409: A deployment changed under the request. The install was not cleared, but deployments of earlier instances may already be stopped; retry the request.
{
"error": "deployments of instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b kept changing during undeploy; retry"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 500: The configuration could not be read or written.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
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.
PUT /api/config/plugins/{key}/active: activate, update, or roll back.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
keypathstringrequiredPlugin key.
application/json: PutActiveVersion
versionstringrequiredInstalled version to activate.
-
200The active version after the change. Body:
ActiveVersionChanged(application/json)3 fieldsplugin_keystringrequiredCanonical plugin key.versionstringrequiredVersion now active.revisioninteger (int64)requiredCompare-and-swap revision of the pointer after the move.
- 400The body is not syntactically valid JSON. Body: string (
text/plain) -
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. A 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.
-
404No such plugin or version. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
- 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
500The configuration could not be read or written. 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/config/plugins/<key>/active' \
-X PUT \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{"version": "0.4.1"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugins/<key>/active' `
-Method Put `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{"version": "0.4.1"}'
import requests
response = requests.put(
"http://127.0.0.1:8787/api/config/plugins/<key>/active",
headers={"Authorization": "Bearer <operatorToken>"},
json={"version": "0.4.1"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugins/<key>/active", {
method: "PUT",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({"version": "0.4.1"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.put("http://127.0.0.1:8787/api/config/plugins/<key>/active")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({"version": "0.4.1"}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The active version after the change.
{
"plugin_key": "libro",
"version": "0.4.2",
"revision": 4
}
Schema:
{
"type": "object",
"description": "`PUT /api/config/plugins/{key}/active` body: the pointer after the move.",
"required": [
"plugin_key",
"version",
"revision"
],
"properties": {
"plugin_key": {
"type": "string",
"description": "Canonical plugin key.",
"example": "libro"
},
"version": {
"type": "string",
"description": "Version now active.",
"example": "0.4.2"
},
"revision": {
"type": "integer",
"format": "int64",
"description": "Compare-and-swap revision of the pointer after the move.",
"example": 4
}
}
}
Status 400: The body is not syntactically valid JSON.
Failed to parse the request body as JSON: expected value at line 1 column 1
Schema:
A text/plain body: a string.
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route. A 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 404: No such plugin or version.
{
"error": "plugin version source-libro 0.4.2 not found"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 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 `version` at line 1 column 2
Schema:
A text/plain body: a string.
Status 500: The configuration could not be read or written.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
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/config/plugins/{key}/versions/{version}/approve: record the
version's requested consent as approved for every node.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
keypathstringrequiredPlugin key.versionpathstringrequiredSemver version.
-
200The version's grant was approved. Body:
PluginVersionApproved(application/json)4 fieldsplugin_keystringrequiredCanonical plugin key.versionstringrequiredSemver version whose grant was approved.approvedbooleanrequiredAlways true: a version that cannot be approved is an error instead.grantobjectrequiredThe grant document, as the consent store keeps it: approved entrypoints, event producers and consumers, jobs, the network mode with the effective, manifest, operator-added and operator-denied domains, TCP targets and CIDRs, host bindings, compatibility flags, resource budgets and the approval time.
-
400The version's manifest does not parse. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. A 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.
-
404No such plugin or version. Body:
ErrorMessage(application/json)1 fielderrorstringrequiredWhat went wrong, as the handler describes it.
-
500The configuration could not be read or written. 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/config/plugins/<key>/versions/<version>/approve' \
-X POST \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/config/plugins/<key>/versions/<version>/approve' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.post(
"http://127.0.0.1:8787/api/config/plugins/<key>/versions/<version>/approve",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/config/plugins/<key>/versions/<version>/approve", {
method: "POST",
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/config/plugins/<key>/versions/<version>/approve")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The version's grant was approved.
{
"plugin_key": "libro",
"version": "0.4.2",
"approved": true,
"grant": {
"addressCidrs": [],
"allowUndeclaredPublicRedirects": false,
"approvedAt": "2026-11-02T14:03:27.481920311+00:00",
"bindings": [
"config",
"secrets"
],
"compatibilityFlags": [],
"consumers": [],
"cpuRatePercent": 80,
"diskMib": 512,
"domains": [],
"entrypoints": [
"storefront"
],
"extraProcesses": 2,
"jobs": [],
"manifestCidrs": [],
"manifestDomains": [],
"manifestTcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"memoryMib": 512,
"networkMode": "outbound",
"operatorAddedCidrs": [],
"operatorAddedDomains": [],
"operatorAddedTcp": [],
"operatorDeniedCidrs": [],
"operatorDeniedDomains": [],
"operatorDeniedTcp": [],
"ownUserAgentHosts": [],
"pluginId": "libro",
"pluginKey": "cargo:https://crates.io#bookclerk-plugin-source-libro",
"producers": [],
"schemaVersion": 2,
"tcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
]
}
}
Schema:
{
"type": "object",
"description": "`POST /api/config/plugins/{key}/versions/{version}/approve` body.",
"required": [
"plugin_key",
"version",
"approved",
"grant"
],
"properties": {
"plugin_key": {
"type": "string",
"description": "Canonical plugin key.",
"example": "libro"
},
"version": {
"type": "string",
"description": "Semver version whose grant was approved.",
"example": "0.4.2"
},
"approved": {
"type": "boolean",
"description": "Always true: a version that cannot be approved is an error instead.",
"example": true
},
"grant": {
"type": "object",
"description": "The grant document, as the consent store keeps it: approved entrypoints, event producers and consumers, jobs, the network mode with the effective, manifest, operator-added and operator-denied domains, TCP targets and CIDRs, host bindings, compatibility flags, resource budgets and the approval time.",
"examples": [
{
"addressCidrs": [],
"allowUndeclaredPublicRedirects": false,
"approvedAt": "2026-11-02T14:03:27.481920311+00:00",
"bindings": [
"config",
"secrets"
],
"compatibilityFlags": [],
"consumers": [],
"cpuRatePercent": 80,
"diskMib": 512,
"domains": [],
"entrypoints": [
"storefront"
],
"extraProcesses": 2,
"jobs": [],
"manifestCidrs": [],
"manifestDomains": [],
"manifestTcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"memoryMib": 512,
"networkMode": "outbound",
"operatorAddedCidrs": [],
"operatorAddedDomains": [],
"operatorAddedTcp": [],
"operatorDeniedCidrs": [],
"operatorDeniedDomains": [],
"operatorDeniedTcp": [],
"ownUserAgentHosts": [],
"pluginId": "libro",
"pluginKey": "cargo:https://crates.io#bookclerk-plugin-source-libro",
"producers": [],
"schemaVersion": 2,
"tcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
]
}
]
}
}
}
Status 400: The version's manifest does not parse.
{
"error": "version plugin.toml: missing field `id`"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route. 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 404: No such plugin or version.
{
"error": "version source-libro 0.4.2"
}
Schema:
{
"type": "object",
"description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "What went wrong, as the handler describes it.",
"example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
}
}
}
Status 500: The configuration could not be read or written.
{
"error": "ORM / database plugin error: Connection Error: pool timed out while waiting for an open connection"
}
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.
Loads the consent dialog for one plugin, including coverage against the stored grant.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
idpathstringrequiredPlugin id.plugin_keyquerystringCanonical PluginKey; when set, wins over the path alias.
-
200What the plugin asks for and what is granted. Body:
PluginConsentResponse(application/json)13 fieldsplugin_idstringrequiredPlugin id whose grant is being reviewed.plugin_keystringrequiredCanonical PluginKey for this install (empty when unknown).provenancestringrequiredHost-evaluated provenance label.runtimestringrequiredGuest runtime (nativeorworkerd) — drives which controls are enforceable.requestPluginGrantViewrequiredManifest-derived grant the plugin is asking for.coveredbooleanrequiredTrue when an existing on-disk grant already satisfies the request.summaryarray of stringrequiredOperator-facing bullet list of requested capabilities.existingPluginGrantViewor nullPreviously approved grant, when one is stored.pendingPluginConsentPendingor nullWhat the request asks for beyond the stored grant (a plugin upgrade that widened its capabilities); absent when no grant is stored. The plugin keeps running under the stored grant until these are approved.brandPluginConsentBrandor nullOptional portal or manifest branding for the dialog.limitsPluginConsentLimitsrequiredHost-capped resource defaults (workerd budgets + shared disk). Always set.host_user_agentstringrequiredTheUser-Agentthis host sends for the plugin's requests, except to the request'sownUserAgentHosts.setting_destinationsarray ofPluginSettingDestinationViewrequiredThe destination each network setting (network = "fetch"or"tcp") names on each instance, and whether it is approved. Empty when the plugin declares no network setting. Apendingrow is not reachable until it is approved;coveredis false while one is.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
404No such plugin. Body:
ErrorJson(application/json)3 fieldserrorstringrequiredMachine slug (same as [ErrorBody::code]).messagestringrequiredOperator-facing explanation.statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
-
500The grant could not be read. Body:
ErrorJson(application/json)3 fieldserrorstringrequiredMachine slug (same as [ErrorBody::code]).messagestringrequiredOperator-facing explanation.statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/plugins/<id>/consent' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/plugins/<id>/consent' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/plugins/<id>/consent",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/plugins/<id>/consent", {
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/api/plugins/<id>/consent")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: What the plugin asks for and what is granted.
{
"plugin_id": "libro",
"plugin_key": "platform:bookclerk/bookclerk-plugin-source-libro#libro",
"provenance": "platform_bundled",
"runtime": "native",
"request": {
"pluginKey": "platform:bookclerk/bookclerk-plugin-source-libro#libro",
"pluginId": "libro",
"entrypoints": [
"storefront"
],
"producers": [
"book_acquired"
],
"consumers": [
{
"eventType": "book_acquired",
"schemaVersions": [
1
],
"supportsSuspend": false
}
],
"jobs": [
"stream_copy"
],
"networkMode": "outbound",
"domains": [
"*.libro.fm",
"api.libro.fm"
],
"manifestDomains": [
"*.libro.fm"
],
"operatorAddedDomains": [
"api.libro.fm"
],
"operatorDeniedDomains": [],
"tcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"operatorAddedTcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"operatorDeniedTcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"addressCidrs": [
"203.0.113.0/24"
],
"operatorAddedCidrs": [
"203.0.113.0/24"
],
"operatorDeniedCidrs": [],
"allowUndeclaredPublicRedirects": false,
"ownUserAgentHosts": [
"*.libro.fm"
],
"ownUserAgentReason": "Libro.fm's sign-in, library and download API answers the HTTP client of the Libro.fm Android app.",
"grantRevision": "9b74c9897bac770ffc029102a200c5de3a9c4a1d6c2f1e0b5a7d8c9e0f1a2b3c",
"authorityRevision": "1f3870be274f6c49b3e31a0c6728957f4e1d5b2c7a8d9e0f1a2b3c4d5e6f7a8b",
"bindings": [
"config",
"secrets"
],
"compatibilityFlags": [
"nodejs_compat"
],
"approvedAt": "2026-10-29T10:12:00Z",
"cpuMs": 50,
"subrequests": 50,
"diskMib": 256,
"memoryMib": 512,
"cpuCores": 1.0,
"extraProcesses": 4
},
"covered": false,
"summary": [
"Plugin: libro (entrypoints: storefront)",
"Network: outbound",
"Raw TCP connect: *.libro.fm:[443]",
"Host bindings: config, secrets"
],
"existing": {
"pluginKey": "platform:bookclerk/bookclerk-plugin-source-libro#libro",
"pluginId": "libro",
"entrypoints": [
"storefront"
],
"producers": [
"book_acquired"
],
"consumers": [
{
"eventType": "book_acquired",
"schemaVersions": [
1
],
"supportsSuspend": false
}
],
"jobs": [
"stream_copy"
],
"networkMode": "outbound",
"domains": [
"*.libro.fm",
"api.libro.fm"
],
"manifestDomains": [
"*.libro.fm"
],
"operatorAddedDomains": [
"api.libro.fm"
],
"operatorDeniedDomains": [],
"tcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"operatorAddedTcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"operatorDeniedTcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"addressCidrs": [
"203.0.113.0/24"
],
"operatorAddedCidrs": [
"203.0.113.0/24"
],
"operatorDeniedCidrs": [],
"allowUndeclaredPublicRedirects": false,
"ownUserAgentHosts": [
"*.libro.fm"
],
"ownUserAgentReason": "Libro.fm's sign-in, library and download API answers the HTTP client of the Libro.fm Android app.",
"grantRevision": "9b74c9897bac770ffc029102a200c5de3a9c4a1d6c2f1e0b5a7d8c9e0f1a2b3c",
"authorityRevision": "1f3870be274f6c49b3e31a0c6728957f4e1d5b2c7a8d9e0f1a2b3c4d5e6f7a8b",
"bindings": [
"config",
"secrets"
],
"compatibilityFlags": [
"nodejs_compat"
],
"approvedAt": "2026-10-29T10:12:00Z",
"cpuMs": 50,
"subrequests": 50,
"diskMib": 256,
"memoryMib": 512,
"cpuCores": 1.0,
"extraProcesses": 4
},
"pending": {
"lines": [
"Awaiting consent (not automatically approved):",
" fetch hosts: any public website (*)"
],
"domains": [
"*"
],
"tcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"addressCidrs": [
"192.168.1.0/24"
],
"allowUndeclaredPublicRedirects": false
},
"brand": {
"name": "Libro.fm",
"bg": "#0f2a3f",
"fg": "#ffffff",
"accent": "#f4b400",
"logo": "/api/plugins/source/libro/logo"
},
"limits": {
"cpu_ms": 30000,
"subrequests": 50,
"max_cpu_ms": 120000,
"max_subrequests": 1000,
"disk_mib": 512,
"max_disk_mib": 4096,
"memory_mib": 512,
"max_memory_mib": 4096,
"cpu_cores": 0.8,
"max_cpu_cores": 8.0,
"jail_cpu_cores": 2.0,
"extra_processes": 2,
"max_extra_processes": 62,
"known_bindings": [
"config",
"secrets",
"plugin_kv",
"work_fs",
"oauth",
"sockets",
"webhooks"
]
},
"host_user_agent": "bookclerk/0.1.0 (+https://bookclerk.app)",
"setting_destinations": [
{
"instanceId": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"setting": "server_url",
"label": "Server URL",
"network": "fetch",
"destination": "http://abs.home.lan:13378",
"scope": "name",
"tls": false,
"state": "pending",
"error": "the URL must start with http:// or https://"
}
]
}
Schema:
{
"type": "object",
"description": "Consent dialog payload for one plugin.",
"required": [
"plugin_id",
"plugin_key",
"provenance",
"runtime",
"request",
"covered",
"summary",
"limits",
"host_user_agent",
"setting_destinations"
],
"properties": {
"plugin_id": {
"type": "string",
"description": "Plugin id whose grant is being reviewed.",
"example": "libro"
},
"plugin_key": {
"type": "string",
"description": "Canonical PluginKey for this install (empty when unknown).",
"example": "platform:bookclerk/bookclerk-plugin-source-libro#libro"
},
"provenance": {
"type": "string",
"description": "Host-evaluated provenance label.",
"example": "platform_bundled"
},
"runtime": {
"type": "string",
"description": "Guest runtime (`native` or `workerd`) — drives which controls are enforceable.",
"example": "native"
},
"request": {
"type": "object",
"description": "Manifest-derived grant the plugin is asking for.",
"required": [
"pluginKey",
"pluginId",
"entrypoints",
"producers",
"consumers",
"jobs",
"networkMode",
"domains",
"manifestDomains",
"operatorAddedDomains",
"operatorDeniedDomains",
"tcp",
"operatorAddedTcp",
"operatorDeniedTcp",
"addressCidrs",
"operatorAddedCidrs",
"operatorDeniedCidrs",
"allowUndeclaredPublicRedirects",
"grantRevision",
"authorityRevision",
"bindings",
"compatibilityFlags",
"approvedAt"
],
"properties": {
"pluginKey": {
"type": "string",
"description": "Canonical provenance-qualified PluginKey.",
"example": "platform:bookclerk/bookclerk-plugin-source-libro#libro"
},
"pluginId": {
"type": "string",
"description": "Plugin id this grant applies to.",
"example": "libro"
},
"entrypoints": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exported entrypoints the operator approved (`storefront`, `cli`, …).",
"example": [
"storefront"
]
},
"producers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Event types the operator approved the plugin to publish.",
"example": [
"book_acquired"
]
},
"consumers": {
"type": "array",
"items": {
"type": "object"
},
"description": "Approved event-consumer subscriptions.",
"example": [
{
"eventType": "book_acquired",
"schemaVersions": [
1
],
"supportsSuspend": false
}
]
},
"jobs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Approved job trigger types.",
"example": [
"stream_copy"
]
},
"networkMode": {
"type": "string",
"description": "Approved egress mode (`deny` or `outbound`).",
"example": "outbound"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Hostnames the operator approved for egress.",
"example": [
"*.libro.fm",
"api.libro.fm"
]
},
"manifestDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Destinations requested by the current manifest.",
"example": [
"*.libro.fm"
]
},
"operatorAddedDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-added destinations beyond the manifest.",
"example": [
"api.libro.fm"
]
},
"operatorDeniedDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-denied destinations still listed by the manifest.",
"example": []
},
"tcp": {
"type": "array",
"items": {
"type": "object",
"description": "Operator-facing TCP grant (`host` + `ports`).",
"required": [
"host",
"ports"
],
"properties": {
"host": {
"type": "string",
"description": "Hostname or `*.` wildcard.",
"example": "*.libro.fm"
},
"ports": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Destination ports.",
"example": [
443
]
}
}
},
"description": "Effective raw TCP grants."
},
"operatorAddedTcp": {
"type": "array",
"items": {
"type": "object",
"description": "Operator-facing TCP grant (`host` + `ports`).",
"required": [
"host",
"ports"
],
"properties": {
"host": {
"type": "string",
"description": "Hostname or `*.` wildcard.",
"example": "*.libro.fm"
},
"ports": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Destination ports.",
"example": [
443
]
}
}
},
"description": "Operator-added TCP grants."
},
"operatorDeniedTcp": {
"type": "array",
"items": {
"type": "object",
"description": "Operator-facing TCP grant (`host` + `ports`).",
"required": [
"host",
"ports"
],
"properties": {
"host": {
"type": "string",
"description": "Hostname or `*.` wildcard.",
"example": "*.libro.fm"
},
"ports": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Destination ports.",
"example": [
443
]
}
}
},
"description": "Operator-denied TCP grants still listed by the manifest."
},
"addressCidrs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Effective address-space CIDRs.",
"example": [
"203.0.113.0/24"
]
},
"operatorAddedCidrs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-added CIDRs.",
"example": [
"203.0.113.0/24"
]
},
"operatorDeniedCidrs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-denied CIDRs still listed by the manifest.",
"example": []
},
"allowUndeclaredPublicRedirects": {
"type": "boolean",
"description": "Undeclared public redirect permission.",
"example": false
},
"ownUserAgentHosts": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Hosts (exact or `*.` wildcard) that receive the plugin's own\n`User-Agent`; every other request carries the host's agent. Absent on\na grant approved before this permission existed, which keeps the hosts\nthe plugin's manifest declares.",
"example": [
"*.libro.fm"
]
},
"ownUserAgentReason": {
"type": [
"string",
"null"
],
"description": "The plugin's reason for [`Self::own_user_agent_hosts`], from\n`plugin.toml`.",
"example": "Libro.fm's sign-in, library and download API answers the HTTP client of the Libro.fm Android app."
},
"grantRevision": {
"type": "string",
"description": "SHA-256 of persisted operator consent (no host overlays).",
"example": "9b74c9897bac770ffc029102a200c5de3a9c4a1d6c2f1e0b5a7d8c9e0f1a2b3c"
},
"authorityRevision": {
"type": "string",
"description": "SHA-256 of the canonical effective authority.",
"example": "1f3870be274f6c49b3e31a0c6728957f4e1d5b2c7a8d9e0f1a2b3c4d5e6f7a8b"
},
"bindings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Host bindings the operator approved.",
"example": [
"config",
"secrets"
]
},
"compatibilityFlags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Extra compatibility flags stored on the grant.",
"example": [
"nodejs_compat"
]
},
"approvedAt": {
"type": "string",
"description": "RFC 3339 timestamp when the grant was last approved.",
"example": "2026-10-29T10:12:00Z"
},
"cpuMs": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional workerd CPU budget in milliseconds.",
"example": 50,
"minimum": 0
},
"subrequests": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional workerd subrequest budget.",
"example": 50,
"minimum": 0
},
"diskMib": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional plugin state disk budget in mebibytes.",
"example": 256,
"minimum": 0
},
"memoryMib": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional jail memory in mebibytes.",
"example": 512,
"minimum": 0
},
"cpuCores": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Jail CPU in cores (2 d.p.); absent for workerd.",
"example": 1.0
},
"extraProcesses": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Extra process/thread budget beyond launcher overhead; native only.",
"example": 4,
"minimum": 0
}
}
},
"covered": {
"type": "boolean",
"description": "True when an existing on-disk grant already satisfies the request.",
"example": false
},
"summary": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-facing bullet list of requested capabilities.",
"example": [
"Plugin: libro (entrypoints: storefront)",
"Network: outbound",
"Raw TCP connect: *.libro.fm:[443]",
"Host bindings: config, secrets"
]
},
"existing": {
"oneOf": [
{
"type": "object",
"description": "Previously approved grant, when one is stored.",
"required": [
"pluginKey",
"pluginId",
"entrypoints",
"producers",
"consumers",
"jobs",
"networkMode",
"domains",
"manifestDomains",
"operatorAddedDomains",
"operatorDeniedDomains",
"tcp",
"operatorAddedTcp",
"operatorDeniedTcp",
"addressCidrs",
"operatorAddedCidrs",
"operatorDeniedCidrs",
"allowUndeclaredPublicRedirects",
"grantRevision",
"authorityRevision",
"bindings",
"compatibilityFlags",
"approvedAt"
],
"properties": {
"pluginKey": {
"type": "string",
"description": "Canonical provenance-qualified PluginKey.",
"example": "platform:bookclerk/bookclerk-plugin-source-libro#libro"
},
"pluginId": {
"type": "string",
"description": "Plugin id this grant applies to.",
"example": "libro"
},
"entrypoints": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exported entrypoints the operator approved (`storefront`, `cli`, …).",
"example": [
"storefront"
]
},
"producers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Event types the operator approved the plugin to publish.",
"example": [
"book_acquired"
]
},
"consumers": {
"type": "array",
"items": {
"type": "object"
},
"description": "Approved event-consumer subscriptions.",
"example": [
{
"eventType": "book_acquired",
"schemaVersions": [
1
],
"supportsSuspend": false
}
]
},
"jobs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Approved job trigger types.",
"example": [
"stream_copy"
]
},
"networkMode": {
"type": "string",
"description": "Approved egress mode (`deny` or `outbound`).",
"example": "outbound"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Hostnames the operator approved for egress.",
"example": [
"*.libro.fm",
"api.libro.fm"
]
},
"manifestDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Destinations requested by the current manifest.",
"example": [
"*.libro.fm"
]
},
"operatorAddedDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-added destinations beyond the manifest.",
"example": [
"api.libro.fm"
]
},
"operatorDeniedDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-denied destinations still listed by the manifest.",
"example": []
},
"tcp": {
"type": "array",
"items": {
"type": "object",
"description": "Operator-facing TCP grant (`host` + `ports`).",
"required": [
"host",
"ports"
],
"properties": {
"host": {
"type": "string",
"description": "Hostname or `*.` wildcard.",
"example": "*.libro.fm"
},
"ports": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Destination ports.",
"example": [
443
]
}
}
},
"description": "Effective raw TCP grants."
},
"operatorAddedTcp": {
"type": "array",
"items": {
"type": "object",
"description": "Operator-facing TCP grant (`host` + `ports`).",
"required": [
"host",
"ports"
],
"properties": {
"host": {
"type": "string",
"description": "Hostname or `*.` wildcard.",
"example": "*.libro.fm"
},
"ports": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Destination ports.",
"example": [
443
]
}
}
},
"description": "Operator-added TCP grants."
},
"operatorDeniedTcp": {
"type": "array",
"items": {
"type": "object",
"description": "Operator-facing TCP grant (`host` + `ports`).",
"required": [
"host",
"ports"
],
"properties": {
"host": {
"type": "string",
"description": "Hostname or `*.` wildcard.",
"example": "*.libro.fm"
},
"ports": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Destination ports.",
"example": [
443
]
}
}
},
"description": "Operator-denied TCP grants still listed by the manifest."
},
"addressCidrs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Effective address-space CIDRs.",
"example": [
"203.0.113.0/24"
]
},
"operatorAddedCidrs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-added CIDRs.",
"example": [
"203.0.113.0/24"
]
},
"operatorDeniedCidrs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-denied CIDRs still listed by the manifest.",
"example": []
},
"allowUndeclaredPublicRedirects": {
"type": "boolean",
"description": "Undeclared public redirect permission.",
"example": false
},
"ownUserAgentHosts": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Hosts (exact or `*.` wildcard) that receive the plugin's own\n`User-Agent`; every other request carries the host's agent. Absent on\na grant approved before this permission existed, which keeps the hosts\nthe plugin's manifest declares.",
"example": [
"*.libro.fm"
]
},
"ownUserAgentReason": {
"type": [
"string",
"null"
],
"description": "The plugin's reason for [`Self::own_user_agent_hosts`], from\n`plugin.toml`.",
"example": "Libro.fm's sign-in, library and download API answers the HTTP client of the Libro.fm Android app."
},
"grantRevision": {
"type": "string",
"description": "SHA-256 of persisted operator consent (no host overlays).",
"example": "9b74c9897bac770ffc029102a200c5de3a9c4a1d6c2f1e0b5a7d8c9e0f1a2b3c"
},
"authorityRevision": {
"type": "string",
"description": "SHA-256 of the canonical effective authority.",
"example": "1f3870be274f6c49b3e31a0c6728957f4e1d5b2c7a8d9e0f1a2b3c4d5e6f7a8b"
},
"bindings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Host bindings the operator approved.",
"example": [
"config",
"secrets"
]
},
"compatibilityFlags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Extra compatibility flags stored on the grant.",
"example": [
"nodejs_compat"
]
},
"approvedAt": {
"type": "string",
"description": "RFC 3339 timestamp when the grant was last approved.",
"example": "2026-10-29T10:12:00Z"
},
"cpuMs": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional workerd CPU budget in milliseconds.",
"example": 50,
"minimum": 0
},
"subrequests": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional workerd subrequest budget.",
"example": 50,
"minimum": 0
},
"diskMib": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional plugin state disk budget in mebibytes.",
"example": 256,
"minimum": 0
},
"memoryMib": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional jail memory in mebibytes.",
"example": 512,
"minimum": 0
},
"cpuCores": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Jail CPU in cores (2 d.p.); absent for workerd.",
"example": 1.0
},
"extraProcesses": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Extra process/thread budget beyond launcher overhead; native only.",
"example": 4,
"minimum": 0
}
}
},
{
"type": "null"
}
]
},
"pending": {
"oneOf": [
{
"type": "object",
"description": "What the request asks for beyond the stored grant (a plugin upgrade\nthat widened its capabilities); absent when no grant is stored. The\nplugin keeps running under the stored grant until these are approved.",
"required": [
"lines",
"domains",
"tcp",
"addressCidrs",
"allowUndeclaredPublicRedirects"
],
"properties": {
"lines": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-facing lines naming every capability awaiting consent, the\nsame lines `bookclerk plugins info` and `bookclerk plugins approve`\nprint; empty when the stored grant covers the request.",
"example": [
"Awaiting consent (not automatically approved):",
" fetch hosts: any public website (*)"
]
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Fetch host patterns the request adds (`*` is any public host).",
"example": [
"*"
]
},
"tcp": {
"type": "array",
"items": {
"type": "object",
"description": "Operator-facing TCP grant (`host` + `ports`).",
"required": [
"host",
"ports"
],
"properties": {
"host": {
"type": "string",
"description": "Hostname or `*.` wildcard.",
"example": "*.libro.fm"
},
"ports": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Destination ports.",
"example": [
443
]
}
}
},
"description": "TCP `host:ports` the request adds, narrowed to the new ports."
},
"addressCidrs": {
"type": "array",
"items": {
"type": "string"
},
"description": "CIDRs the request adds.",
"example": [
"192.168.1.0/24"
]
},
"allowUndeclaredPublicRedirects": {
"type": "boolean",
"description": "Whether the request newly asks to follow undeclared public redirects.",
"example": false
}
}
},
{
"type": "null"
}
]
},
"brand": {
"oneOf": [
{
"type": "object",
"description": "Optional portal or manifest branding for the dialog.",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Display name from the portal brand or plugin manifest.",
"example": "Libro.fm"
},
"bg": {
"type": [
"string",
"null"
],
"description": "Background CSS color from the portal brand, when known.",
"example": "#0f2a3f"
},
"fg": {
"type": [
"string",
"null"
],
"description": "Foreground CSS color from the portal brand, when known.",
"example": "#ffffff"
},
"accent": {
"type": [
"string",
"null"
],
"description": "Accent CSS color from the portal brand, when known.",
"example": "#f4b400"
},
"logo": {
"type": [
"string",
"null"
],
"description": "Same-origin logo: the host-served embed path, or a 128 px copy of\nthe remote logo the plugin names.",
"example": "/api/plugins/source/libro/logo"
}
}
},
{
"type": "null"
}
]
},
"limits": {
"type": "object",
"description": "Host-capped resource defaults (workerd budgets + shared disk). Always set.",
"required": [
"cpu_ms",
"subrequests",
"max_cpu_ms",
"max_subrequests",
"disk_mib",
"max_disk_mib",
"memory_mib",
"max_memory_mib",
"cpu_cores",
"max_cpu_cores",
"extra_processes",
"max_extra_processes",
"known_bindings"
],
"properties": {
"cpu_ms": {
"type": "integer",
"format": "int32",
"description": "Requested workerd CPU budget in milliseconds.",
"example": 30000,
"minimum": 0
},
"subrequests": {
"type": "integer",
"format": "int32",
"description": "Requested workerd subrequest budget.",
"example": 50,
"minimum": 0
},
"max_cpu_ms": {
"type": "integer",
"format": "int32",
"description": "Host hard cap for workerd CPU milliseconds.",
"example": 120000,
"minimum": 0
},
"max_subrequests": {
"type": "integer",
"format": "int32",
"description": "Host hard cap for workerd subrequests.",
"example": 1000,
"minimum": 0
},
"disk_mib": {
"type": "integer",
"format": "int32",
"description": "Default plugin state disk budget in mebibytes.",
"example": 512,
"minimum": 0
},
"max_disk_mib": {
"type": "integer",
"format": "int32",
"description": "Host hard cap for plugin state disk in mebibytes.",
"example": 4096,
"minimum": 0
},
"memory_mib": {
"type": "integer",
"format": "int32",
"description": "Default jail memory in mebibytes.",
"example": 512,
"minimum": 0
},
"max_memory_mib": {
"type": "integer",
"format": "int32",
"description": "Host hard cap for jail memory in mebibytes.",
"example": 4096,
"minimum": 0
},
"cpu_cores": {
"type": "number",
"format": "double",
"description": "Manifest / default jail CPU in cores (2 d.p.).",
"example": 0.8
},
"max_cpu_cores": {
"type": "number",
"format": "double",
"description": "Host max jail CPU in cores (2 d.p.).",
"example": 8.0
},
"jail_cpu_cores": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Optional `[plugins.jail]` ceiling in cores.",
"example": 2.0
},
"extra_processes": {
"type": "integer",
"format": "int32",
"description": "Default extra process/thread budget (native consent).",
"example": 2,
"minimum": 0
},
"max_extra_processes": {
"type": "integer",
"format": "int32",
"description": "Host hard cap for extra process budget.",
"example": 62,
"minimum": 0
},
"known_bindings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Suggested / default host bindings operators may grant.",
"example": [
"config",
"secrets",
"plugin_kv",
"work_fs",
"oauth",
"sockets",
"webhooks"
]
}
}
},
"host_user_agent": {
"type": "string",
"description": "The `User-Agent` this host sends for the plugin's requests, except to\nthe request's `ownUserAgentHosts`.",
"example": "bookclerk/0.1.0 (+https://bookclerk.app)"
},
"setting_destinations": {
"type": "array",
"items": {
"type": "object",
"description": "One network setting's destination on one plugin instance.",
"required": [
"setting",
"label",
"network",
"state"
],
"properties": {
"instanceId": {
"type": [
"string",
"null"
],
"description": "The instance whose settings name it; absent when the plugin has no\ninstance yet and the row shows the setting's default.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"setting": {
"type": "string",
"description": "The setting key, the source the grant is stored under.",
"example": "server_url"
},
"label": {
"type": "string",
"description": "The setting's label (its key when it has none).",
"example": "Server URL"
},
"network": {
"type": "string",
"description": "`fetch` (HTTP requests) or `tcp` (a raw socket).",
"example": "fetch"
},
"destination": {
"type": [
"string",
"null"
],
"description": "The destination: `scheme://host:port` for a fetch, `host:port` for\nTCP (IPv6 in brackets); absent when the setting is unset or invalid.",
"example": "http://abs.home.lan:13378"
},
"scope": {
"type": [
"string",
"null"
],
"description": "What kind of host it is: `name` (may resolve to a local-network\naddress, for this name only), `publicAddress`, `localAddress` (this\none local-network address) or `restricted` (loopback, link-local or\na name such as `localhost`, which also needs an address grant).",
"example": "name"
},
"tls": {
"type": [
"boolean",
"null"
],
"description": "True for an `https` fetch, whose certificate is verified; false for\nplain HTTP and raw TCP, which trust the network's DNS answer.",
"example": false
},
"state": {
"type": "string",
"description": "`approved`, `pending` (awaiting consent), `unset` or `invalid`.",
"example": "pending"
},
"error": {
"type": [
"string",
"null"
],
"description": "Why the value names no destination, when `state` is `invalid`.",
"example": "the URL must start with http:// or https://"
}
}
},
"description": "The destination each network setting (`network = \"fetch\"` or\n`\"tcp\"`) names on each instance, and whether it is approved. Empty\nwhen the plugin declares no network setting. A `pending` row is not\nreachable until it is approved; `covered` is false while one is."
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route.
{
"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: No such plugin.
{
"error": "not_found",
"message": "That page or resource was not found.",
"status": 404
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Status 500: The grant could not be read.
{
"error": "internal_error",
"message": "Something went wrong on the Bookclerk daemon.",
"status": 500
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Persists an approved plugin grant after validating operator overrides.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
idpathstringrequiredPlugin id.plugin_keyquerystringCanonical PluginKey; when set, wins over the path alias.
application/json: PluginConsentApproveRequest
approvebooleanrequiredMust be true; a false value is rejected with 400.grantPluginGrantOverrideor nullOptional operator overrides applied on top of the manifest request.setting_destinationsarray ofPluginSettingDestinationApprovalSetting destinations to approve, from the response'ssetting_destinations. An approved destination stays approved while a setting still names it; one left out stays pending, and one no setting names any more is withdrawn.
-
200The grant was stored. Body:
PluginConsentResponse(application/json)13 fieldsplugin_idstringrequiredPlugin id whose grant is being reviewed.plugin_keystringrequiredCanonical PluginKey for this install (empty when unknown).provenancestringrequiredHost-evaluated provenance label.runtimestringrequiredGuest runtime (nativeorworkerd) — drives which controls are enforceable.requestPluginGrantViewrequiredManifest-derived grant the plugin is asking for.coveredbooleanrequiredTrue when an existing on-disk grant already satisfies the request.summaryarray of stringrequiredOperator-facing bullet list of requested capabilities.existingPluginGrantViewor nullPreviously approved grant, when one is stored.pendingPluginConsentPendingor nullWhat the request asks for beyond the stored grant (a plugin upgrade that widened its capabilities); absent when no grant is stored. The plugin keeps running under the stored grant until these are approved.brandPluginConsentBrandor nullOptional portal or manifest branding for the dialog.limitsPluginConsentLimitsrequiredHost-capped resource defaults (workerd budgets + shared disk). Always set.host_user_agentstringrequiredTheUser-Agentthis host sends for the plugin's requests, except to the request'sownUserAgentHosts.setting_destinationsarray ofPluginSettingDestinationViewrequiredThe destination each network setting (network = "fetch"or"tcp") names on each instance, and whether it is approved. Empty when the plugin declares no network setting. Apendingrow is not reachable until it is approved;coveredis false while one is.
-
400An override is not allowed. As
text/plain, when the body is not syntactically valid JSON. Body:ErrorJson(application/json); string (text/plain)3 fieldserrorstringrequiredMachine slug (same as [ErrorBody::code]).messagestringrequiredOperator-facing explanation.statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
-
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. A 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.
-
404No such plugin. Body:
ErrorJson(application/json)3 fieldserrorstringrequiredMachine slug (same as [ErrorBody::code]).messagestringrequiredOperator-facing explanation.statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
- 415The request did not declare a JSON body. Body: string (
text/plain) - 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (
text/plain) -
500The grant could not be stored. Body:
ErrorJson(application/json)3 fieldserrorstringrequiredMachine slug (same as [ErrorBody::code]).messagestringrequiredOperator-facing explanation.statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/plugins/<id>/consent' \
-X POST \
-H 'Authorization: Bearer <operatorToken>' \
-H 'Content-Type: application/json' \
-d '{"approve": true}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/plugins/<id>/consent' `
-Method Post `
-Headers @{ Authorization = 'Bearer <operatorToken>' } `
-ContentType 'application/json' `
-Body '{"approve": true}'
import requests
response = requests.post(
"http://127.0.0.1:8787/api/plugins/<id>/consent",
headers={"Authorization": "Bearer <operatorToken>"},
json={"approve": True},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/plugins/<id>/consent", {
method: "POST",
headers: { Authorization: "Bearer <operatorToken>", "Content-Type": "application/json" },
body: JSON.stringify({"approve": true}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.post("http://127.0.0.1:8787/api/plugins/<id>/consent")
.header("Authorization", "Bearer <operatorToken>")
.json(&serde_json::json!({"approve": true}))
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The grant was stored.
{
"plugin_id": "libro",
"plugin_key": "platform:bookclerk/bookclerk-plugin-source-libro#libro",
"provenance": "platform_bundled",
"runtime": "native",
"request": {
"pluginKey": "platform:bookclerk/bookclerk-plugin-source-libro#libro",
"pluginId": "libro",
"entrypoints": [
"storefront"
],
"producers": [
"book_acquired"
],
"consumers": [
{
"eventType": "book_acquired",
"schemaVersions": [
1
],
"supportsSuspend": false
}
],
"jobs": [
"stream_copy"
],
"networkMode": "outbound",
"domains": [
"*.libro.fm",
"api.libro.fm"
],
"manifestDomains": [
"*.libro.fm"
],
"operatorAddedDomains": [
"api.libro.fm"
],
"operatorDeniedDomains": [],
"tcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"operatorAddedTcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"operatorDeniedTcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"addressCidrs": [
"203.0.113.0/24"
],
"operatorAddedCidrs": [
"203.0.113.0/24"
],
"operatorDeniedCidrs": [],
"allowUndeclaredPublicRedirects": false,
"ownUserAgentHosts": [
"*.libro.fm"
],
"ownUserAgentReason": "Libro.fm's sign-in, library and download API answers the HTTP client of the Libro.fm Android app.",
"grantRevision": "9b74c9897bac770ffc029102a200c5de3a9c4a1d6c2f1e0b5a7d8c9e0f1a2b3c",
"authorityRevision": "1f3870be274f6c49b3e31a0c6728957f4e1d5b2c7a8d9e0f1a2b3c4d5e6f7a8b",
"bindings": [
"config",
"secrets"
],
"compatibilityFlags": [
"nodejs_compat"
],
"approvedAt": "2026-10-29T10:12:00Z",
"cpuMs": 50,
"subrequests": 50,
"diskMib": 256,
"memoryMib": 512,
"cpuCores": 1.0,
"extraProcesses": 4
},
"covered": false,
"summary": [
"Plugin: libro (entrypoints: storefront)",
"Network: outbound",
"Raw TCP connect: *.libro.fm:[443]",
"Host bindings: config, secrets"
],
"existing": {
"pluginKey": "platform:bookclerk/bookclerk-plugin-source-libro#libro",
"pluginId": "libro",
"entrypoints": [
"storefront"
],
"producers": [
"book_acquired"
],
"consumers": [
{
"eventType": "book_acquired",
"schemaVersions": [
1
],
"supportsSuspend": false
}
],
"jobs": [
"stream_copy"
],
"networkMode": "outbound",
"domains": [
"*.libro.fm",
"api.libro.fm"
],
"manifestDomains": [
"*.libro.fm"
],
"operatorAddedDomains": [
"api.libro.fm"
],
"operatorDeniedDomains": [],
"tcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"operatorAddedTcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"operatorDeniedTcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"addressCidrs": [
"203.0.113.0/24"
],
"operatorAddedCidrs": [
"203.0.113.0/24"
],
"operatorDeniedCidrs": [],
"allowUndeclaredPublicRedirects": false,
"ownUserAgentHosts": [
"*.libro.fm"
],
"ownUserAgentReason": "Libro.fm's sign-in, library and download API answers the HTTP client of the Libro.fm Android app.",
"grantRevision": "9b74c9897bac770ffc029102a200c5de3a9c4a1d6c2f1e0b5a7d8c9e0f1a2b3c",
"authorityRevision": "1f3870be274f6c49b3e31a0c6728957f4e1d5b2c7a8d9e0f1a2b3c4d5e6f7a8b",
"bindings": [
"config",
"secrets"
],
"compatibilityFlags": [
"nodejs_compat"
],
"approvedAt": "2026-10-29T10:12:00Z",
"cpuMs": 50,
"subrequests": 50,
"diskMib": 256,
"memoryMib": 512,
"cpuCores": 1.0,
"extraProcesses": 4
},
"pending": {
"lines": [
"Awaiting consent (not automatically approved):",
" fetch hosts: any public website (*)"
],
"domains": [
"*"
],
"tcp": [
{
"host": "*.libro.fm",
"ports": [
443
]
}
],
"addressCidrs": [
"192.168.1.0/24"
],
"allowUndeclaredPublicRedirects": false
},
"brand": {
"name": "Libro.fm",
"bg": "#0f2a3f",
"fg": "#ffffff",
"accent": "#f4b400",
"logo": "/api/plugins/source/libro/logo"
},
"limits": {
"cpu_ms": 30000,
"subrequests": 50,
"max_cpu_ms": 120000,
"max_subrequests": 1000,
"disk_mib": 512,
"max_disk_mib": 4096,
"memory_mib": 512,
"max_memory_mib": 4096,
"cpu_cores": 0.8,
"max_cpu_cores": 8.0,
"jail_cpu_cores": 2.0,
"extra_processes": 2,
"max_extra_processes": 62,
"known_bindings": [
"config",
"secrets",
"plugin_kv",
"work_fs",
"oauth",
"sockets",
"webhooks"
]
},
"host_user_agent": "bookclerk/0.1.0 (+https://bookclerk.app)",
"setting_destinations": [
{
"instanceId": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b",
"setting": "server_url",
"label": "Server URL",
"network": "fetch",
"destination": "http://abs.home.lan:13378",
"scope": "name",
"tls": false,
"state": "pending",
"error": "the URL must start with http:// or https://"
}
]
}
Schema:
{
"type": "object",
"description": "Consent dialog payload for one plugin.",
"required": [
"plugin_id",
"plugin_key",
"provenance",
"runtime",
"request",
"covered",
"summary",
"limits",
"host_user_agent",
"setting_destinations"
],
"properties": {
"plugin_id": {
"type": "string",
"description": "Plugin id whose grant is being reviewed.",
"example": "libro"
},
"plugin_key": {
"type": "string",
"description": "Canonical PluginKey for this install (empty when unknown).",
"example": "platform:bookclerk/bookclerk-plugin-source-libro#libro"
},
"provenance": {
"type": "string",
"description": "Host-evaluated provenance label.",
"example": "platform_bundled"
},
"runtime": {
"type": "string",
"description": "Guest runtime (`native` or `workerd`) — drives which controls are enforceable.",
"example": "native"
},
"request": {
"type": "object",
"description": "Manifest-derived grant the plugin is asking for.",
"required": [
"pluginKey",
"pluginId",
"entrypoints",
"producers",
"consumers",
"jobs",
"networkMode",
"domains",
"manifestDomains",
"operatorAddedDomains",
"operatorDeniedDomains",
"tcp",
"operatorAddedTcp",
"operatorDeniedTcp",
"addressCidrs",
"operatorAddedCidrs",
"operatorDeniedCidrs",
"allowUndeclaredPublicRedirects",
"grantRevision",
"authorityRevision",
"bindings",
"compatibilityFlags",
"approvedAt"
],
"properties": {
"pluginKey": {
"type": "string",
"description": "Canonical provenance-qualified PluginKey.",
"example": "platform:bookclerk/bookclerk-plugin-source-libro#libro"
},
"pluginId": {
"type": "string",
"description": "Plugin id this grant applies to.",
"example": "libro"
},
"entrypoints": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exported entrypoints the operator approved (`storefront`, `cli`, …).",
"example": [
"storefront"
]
},
"producers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Event types the operator approved the plugin to publish.",
"example": [
"book_acquired"
]
},
"consumers": {
"type": "array",
"items": {
"type": "object"
},
"description": "Approved event-consumer subscriptions.",
"example": [
{
"eventType": "book_acquired",
"schemaVersions": [
1
],
"supportsSuspend": false
}
]
},
"jobs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Approved job trigger types.",
"example": [
"stream_copy"
]
},
"networkMode": {
"type": "string",
"description": "Approved egress mode (`deny` or `outbound`).",
"example": "outbound"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Hostnames the operator approved for egress.",
"example": [
"*.libro.fm",
"api.libro.fm"
]
},
"manifestDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Destinations requested by the current manifest.",
"example": [
"*.libro.fm"
]
},
"operatorAddedDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-added destinations beyond the manifest.",
"example": [
"api.libro.fm"
]
},
"operatorDeniedDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-denied destinations still listed by the manifest.",
"example": []
},
"tcp": {
"type": "array",
"items": {
"type": "object",
"description": "Operator-facing TCP grant (`host` + `ports`).",
"required": [
"host",
"ports"
],
"properties": {
"host": {
"type": "string",
"description": "Hostname or `*.` wildcard.",
"example": "*.libro.fm"
},
"ports": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Destination ports.",
"example": [
443
]
}
}
},
"description": "Effective raw TCP grants."
},
"operatorAddedTcp": {
"type": "array",
"items": {
"type": "object",
"description": "Operator-facing TCP grant (`host` + `ports`).",
"required": [
"host",
"ports"
],
"properties": {
"host": {
"type": "string",
"description": "Hostname or `*.` wildcard.",
"example": "*.libro.fm"
},
"ports": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Destination ports.",
"example": [
443
]
}
}
},
"description": "Operator-added TCP grants."
},
"operatorDeniedTcp": {
"type": "array",
"items": {
"type": "object",
"description": "Operator-facing TCP grant (`host` + `ports`).",
"required": [
"host",
"ports"
],
"properties": {
"host": {
"type": "string",
"description": "Hostname or `*.` wildcard.",
"example": "*.libro.fm"
},
"ports": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Destination ports.",
"example": [
443
]
}
}
},
"description": "Operator-denied TCP grants still listed by the manifest."
},
"addressCidrs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Effective address-space CIDRs.",
"example": [
"203.0.113.0/24"
]
},
"operatorAddedCidrs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-added CIDRs.",
"example": [
"203.0.113.0/24"
]
},
"operatorDeniedCidrs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-denied CIDRs still listed by the manifest.",
"example": []
},
"allowUndeclaredPublicRedirects": {
"type": "boolean",
"description": "Undeclared public redirect permission.",
"example": false
},
"ownUserAgentHosts": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Hosts (exact or `*.` wildcard) that receive the plugin's own\n`User-Agent`; every other request carries the host's agent. Absent on\na grant approved before this permission existed, which keeps the hosts\nthe plugin's manifest declares.",
"example": [
"*.libro.fm"
]
},
"ownUserAgentReason": {
"type": [
"string",
"null"
],
"description": "The plugin's reason for [`Self::own_user_agent_hosts`], from\n`plugin.toml`.",
"example": "Libro.fm's sign-in, library and download API answers the HTTP client of the Libro.fm Android app."
},
"grantRevision": {
"type": "string",
"description": "SHA-256 of persisted operator consent (no host overlays).",
"example": "9b74c9897bac770ffc029102a200c5de3a9c4a1d6c2f1e0b5a7d8c9e0f1a2b3c"
},
"authorityRevision": {
"type": "string",
"description": "SHA-256 of the canonical effective authority.",
"example": "1f3870be274f6c49b3e31a0c6728957f4e1d5b2c7a8d9e0f1a2b3c4d5e6f7a8b"
},
"bindings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Host bindings the operator approved.",
"example": [
"config",
"secrets"
]
},
"compatibilityFlags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Extra compatibility flags stored on the grant.",
"example": [
"nodejs_compat"
]
},
"approvedAt": {
"type": "string",
"description": "RFC 3339 timestamp when the grant was last approved.",
"example": "2026-10-29T10:12:00Z"
},
"cpuMs": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional workerd CPU budget in milliseconds.",
"example": 50,
"minimum": 0
},
"subrequests": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional workerd subrequest budget.",
"example": 50,
"minimum": 0
},
"diskMib": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional plugin state disk budget in mebibytes.",
"example": 256,
"minimum": 0
},
"memoryMib": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional jail memory in mebibytes.",
"example": 512,
"minimum": 0
},
"cpuCores": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Jail CPU in cores (2 d.p.); absent for workerd.",
"example": 1.0
},
"extraProcesses": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Extra process/thread budget beyond launcher overhead; native only.",
"example": 4,
"minimum": 0
}
}
},
"covered": {
"type": "boolean",
"description": "True when an existing on-disk grant already satisfies the request.",
"example": false
},
"summary": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-facing bullet list of requested capabilities.",
"example": [
"Plugin: libro (entrypoints: storefront)",
"Network: outbound",
"Raw TCP connect: *.libro.fm:[443]",
"Host bindings: config, secrets"
]
},
"existing": {
"oneOf": [
{
"type": "object",
"description": "Previously approved grant, when one is stored.",
"required": [
"pluginKey",
"pluginId",
"entrypoints",
"producers",
"consumers",
"jobs",
"networkMode",
"domains",
"manifestDomains",
"operatorAddedDomains",
"operatorDeniedDomains",
"tcp",
"operatorAddedTcp",
"operatorDeniedTcp",
"addressCidrs",
"operatorAddedCidrs",
"operatorDeniedCidrs",
"allowUndeclaredPublicRedirects",
"grantRevision",
"authorityRevision",
"bindings",
"compatibilityFlags",
"approvedAt"
],
"properties": {
"pluginKey": {
"type": "string",
"description": "Canonical provenance-qualified PluginKey.",
"example": "platform:bookclerk/bookclerk-plugin-source-libro#libro"
},
"pluginId": {
"type": "string",
"description": "Plugin id this grant applies to.",
"example": "libro"
},
"entrypoints": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exported entrypoints the operator approved (`storefront`, `cli`, …).",
"example": [
"storefront"
]
},
"producers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Event types the operator approved the plugin to publish.",
"example": [
"book_acquired"
]
},
"consumers": {
"type": "array",
"items": {
"type": "object"
},
"description": "Approved event-consumer subscriptions.",
"example": [
{
"eventType": "book_acquired",
"schemaVersions": [
1
],
"supportsSuspend": false
}
]
},
"jobs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Approved job trigger types.",
"example": [
"stream_copy"
]
},
"networkMode": {
"type": "string",
"description": "Approved egress mode (`deny` or `outbound`).",
"example": "outbound"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Hostnames the operator approved for egress.",
"example": [
"*.libro.fm",
"api.libro.fm"
]
},
"manifestDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Destinations requested by the current manifest.",
"example": [
"*.libro.fm"
]
},
"operatorAddedDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-added destinations beyond the manifest.",
"example": [
"api.libro.fm"
]
},
"operatorDeniedDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-denied destinations still listed by the manifest.",
"example": []
},
"tcp": {
"type": "array",
"items": {
"type": "object",
"description": "Operator-facing TCP grant (`host` + `ports`).",
"required": [
"host",
"ports"
],
"properties": {
"host": {
"type": "string",
"description": "Hostname or `*.` wildcard.",
"example": "*.libro.fm"
},
"ports": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Destination ports.",
"example": [
443
]
}
}
},
"description": "Effective raw TCP grants."
},
"operatorAddedTcp": {
"type": "array",
"items": {
"type": "object",
"description": "Operator-facing TCP grant (`host` + `ports`).",
"required": [
"host",
"ports"
],
"properties": {
"host": {
"type": "string",
"description": "Hostname or `*.` wildcard.",
"example": "*.libro.fm"
},
"ports": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Destination ports.",
"example": [
443
]
}
}
},
"description": "Operator-added TCP grants."
},
"operatorDeniedTcp": {
"type": "array",
"items": {
"type": "object",
"description": "Operator-facing TCP grant (`host` + `ports`).",
"required": [
"host",
"ports"
],
"properties": {
"host": {
"type": "string",
"description": "Hostname or `*.` wildcard.",
"example": "*.libro.fm"
},
"ports": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Destination ports.",
"example": [
443
]
}
}
},
"description": "Operator-denied TCP grants still listed by the manifest."
},
"addressCidrs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Effective address-space CIDRs.",
"example": [
"203.0.113.0/24"
]
},
"operatorAddedCidrs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-added CIDRs.",
"example": [
"203.0.113.0/24"
]
},
"operatorDeniedCidrs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-denied CIDRs still listed by the manifest.",
"example": []
},
"allowUndeclaredPublicRedirects": {
"type": "boolean",
"description": "Undeclared public redirect permission.",
"example": false
},
"ownUserAgentHosts": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Hosts (exact or `*.` wildcard) that receive the plugin's own\n`User-Agent`; every other request carries the host's agent. Absent on\na grant approved before this permission existed, which keeps the hosts\nthe plugin's manifest declares.",
"example": [
"*.libro.fm"
]
},
"ownUserAgentReason": {
"type": [
"string",
"null"
],
"description": "The plugin's reason for [`Self::own_user_agent_hosts`], from\n`plugin.toml`.",
"example": "Libro.fm's sign-in, library and download API answers the HTTP client of the Libro.fm Android app."
},
"grantRevision": {
"type": "string",
"description": "SHA-256 of persisted operator consent (no host overlays).",
"example": "9b74c9897bac770ffc029102a200c5de3a9c4a1d6c2f1e0b5a7d8c9e0f1a2b3c"
},
"authorityRevision": {
"type": "string",
"description": "SHA-256 of the canonical effective authority.",
"example": "1f3870be274f6c49b3e31a0c6728957f4e1d5b2c7a8d9e0f1a2b3c4d5e6f7a8b"
},
"bindings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Host bindings the operator approved.",
"example": [
"config",
"secrets"
]
},
"compatibilityFlags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Extra compatibility flags stored on the grant.",
"example": [
"nodejs_compat"
]
},
"approvedAt": {
"type": "string",
"description": "RFC 3339 timestamp when the grant was last approved.",
"example": "2026-10-29T10:12:00Z"
},
"cpuMs": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional workerd CPU budget in milliseconds.",
"example": 50,
"minimum": 0
},
"subrequests": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional workerd subrequest budget.",
"example": 50,
"minimum": 0
},
"diskMib": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional plugin state disk budget in mebibytes.",
"example": 256,
"minimum": 0
},
"memoryMib": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Optional jail memory in mebibytes.",
"example": 512,
"minimum": 0
},
"cpuCores": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Jail CPU in cores (2 d.p.); absent for workerd.",
"example": 1.0
},
"extraProcesses": {
"type": [
"integer",
"null"
],
"format": "int32",
"description": "Extra process/thread budget beyond launcher overhead; native only.",
"example": 4,
"minimum": 0
}
}
},
{
"type": "null"
}
]
},
"pending": {
"oneOf": [
{
"type": "object",
"description": "What the request asks for beyond the stored grant (a plugin upgrade\nthat widened its capabilities); absent when no grant is stored. The\nplugin keeps running under the stored grant until these are approved.",
"required": [
"lines",
"domains",
"tcp",
"addressCidrs",
"allowUndeclaredPublicRedirects"
],
"properties": {
"lines": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operator-facing lines naming every capability awaiting consent, the\nsame lines `bookclerk plugins info` and `bookclerk plugins approve`\nprint; empty when the stored grant covers the request.",
"example": [
"Awaiting consent (not automatically approved):",
" fetch hosts: any public website (*)"
]
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Fetch host patterns the request adds (`*` is any public host).",
"example": [
"*"
]
},
"tcp": {
"type": "array",
"items": {
"type": "object",
"description": "Operator-facing TCP grant (`host` + `ports`).",
"required": [
"host",
"ports"
],
"properties": {
"host": {
"type": "string",
"description": "Hostname or `*.` wildcard.",
"example": "*.libro.fm"
},
"ports": {
"type": "array",
"items": {
"type": "integer",
"format": "int32",
"minimum": 0
},
"description": "Destination ports.",
"example": [
443
]
}
}
},
"description": "TCP `host:ports` the request adds, narrowed to the new ports."
},
"addressCidrs": {
"type": "array",
"items": {
"type": "string"
},
"description": "CIDRs the request adds.",
"example": [
"192.168.1.0/24"
]
},
"allowUndeclaredPublicRedirects": {
"type": "boolean",
"description": "Whether the request newly asks to follow undeclared public redirects.",
"example": false
}
}
},
{
"type": "null"
}
]
},
"brand": {
"oneOf": [
{
"type": "object",
"description": "Optional portal or manifest branding for the dialog.",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Display name from the portal brand or plugin manifest.",
"example": "Libro.fm"
},
"bg": {
"type": [
"string",
"null"
],
"description": "Background CSS color from the portal brand, when known.",
"example": "#0f2a3f"
},
"fg": {
"type": [
"string",
"null"
],
"description": "Foreground CSS color from the portal brand, when known.",
"example": "#ffffff"
},
"accent": {
"type": [
"string",
"null"
],
"description": "Accent CSS color from the portal brand, when known.",
"example": "#f4b400"
},
"logo": {
"type": [
"string",
"null"
],
"description": "Same-origin logo: the host-served embed path, or a 128 px copy of\nthe remote logo the plugin names.",
"example": "/api/plugins/source/libro/logo"
}
}
},
{
"type": "null"
}
]
},
"limits": {
"type": "object",
"description": "Host-capped resource defaults (workerd budgets + shared disk). Always set.",
"required": [
"cpu_ms",
"subrequests",
"max_cpu_ms",
"max_subrequests",
"disk_mib",
"max_disk_mib",
"memory_mib",
"max_memory_mib",
"cpu_cores",
"max_cpu_cores",
"extra_processes",
"max_extra_processes",
"known_bindings"
],
"properties": {
"cpu_ms": {
"type": "integer",
"format": "int32",
"description": "Requested workerd CPU budget in milliseconds.",
"example": 30000,
"minimum": 0
},
"subrequests": {
"type": "integer",
"format": "int32",
"description": "Requested workerd subrequest budget.",
"example": 50,
"minimum": 0
},
"max_cpu_ms": {
"type": "integer",
"format": "int32",
"description": "Host hard cap for workerd CPU milliseconds.",
"example": 120000,
"minimum": 0
},
"max_subrequests": {
"type": "integer",
"format": "int32",
"description": "Host hard cap for workerd subrequests.",
"example": 1000,
"minimum": 0
},
"disk_mib": {
"type": "integer",
"format": "int32",
"description": "Default plugin state disk budget in mebibytes.",
"example": 512,
"minimum": 0
},
"max_disk_mib": {
"type": "integer",
"format": "int32",
"description": "Host hard cap for plugin state disk in mebibytes.",
"example": 4096,
"minimum": 0
},
"memory_mib": {
"type": "integer",
"format": "int32",
"description": "Default jail memory in mebibytes.",
"example": 512,
"minimum": 0
},
"max_memory_mib": {
"type": "integer",
"format": "int32",
"description": "Host hard cap for jail memory in mebibytes.",
"example": 4096,
"minimum": 0
},
"cpu_cores": {
"type": "number",
"format": "double",
"description": "Manifest / default jail CPU in cores (2 d.p.).",
"example": 0.8
},
"max_cpu_cores": {
"type": "number",
"format": "double",
"description": "Host max jail CPU in cores (2 d.p.).",
"example": 8.0
},
"jail_cpu_cores": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Optional `[plugins.jail]` ceiling in cores.",
"example": 2.0
},
"extra_processes": {
"type": "integer",
"format": "int32",
"description": "Default extra process/thread budget (native consent).",
"example": 2,
"minimum": 0
},
"max_extra_processes": {
"type": "integer",
"format": "int32",
"description": "Host hard cap for extra process budget.",
"example": 62,
"minimum": 0
},
"known_bindings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Suggested / default host bindings operators may grant.",
"example": [
"config",
"secrets",
"plugin_kv",
"work_fs",
"oauth",
"sockets",
"webhooks"
]
}
}
},
"host_user_agent": {
"type": "string",
"description": "The `User-Agent` this host sends for the plugin's requests, except to\nthe request's `ownUserAgentHosts`.",
"example": "bookclerk/0.1.0 (+https://bookclerk.app)"
},
"setting_destinations": {
"type": "array",
"items": {
"type": "object",
"description": "One network setting's destination on one plugin instance.",
"required": [
"setting",
"label",
"network",
"state"
],
"properties": {
"instanceId": {
"type": [
"string",
"null"
],
"description": "The instance whose settings name it; absent when the plugin has no\ninstance yet and the row shows the setting's default.",
"example": "3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b"
},
"setting": {
"type": "string",
"description": "The setting key, the source the grant is stored under.",
"example": "server_url"
},
"label": {
"type": "string",
"description": "The setting's label (its key when it has none).",
"example": "Server URL"
},
"network": {
"type": "string",
"description": "`fetch` (HTTP requests) or `tcp` (a raw socket).",
"example": "fetch"
},
"destination": {
"type": [
"string",
"null"
],
"description": "The destination: `scheme://host:port` for a fetch, `host:port` for\nTCP (IPv6 in brackets); absent when the setting is unset or invalid.",
"example": "http://abs.home.lan:13378"
},
"scope": {
"type": [
"string",
"null"
],
"description": "What kind of host it is: `name` (may resolve to a local-network\naddress, for this name only), `publicAddress`, `localAddress` (this\none local-network address) or `restricted` (loopback, link-local or\na name such as `localhost`, which also needs an address grant).",
"example": "name"
},
"tls": {
"type": [
"boolean",
"null"
],
"description": "True for an `https` fetch, whose certificate is verified; false for\nplain HTTP and raw TCP, which trust the network's DNS answer.",
"example": false
},
"state": {
"type": "string",
"description": "`approved`, `pending` (awaiting consent), `unset` or `invalid`.",
"example": "pending"
},
"error": {
"type": [
"string",
"null"
],
"description": "Why the value names no destination, when `state` is `invalid`.",
"example": "the URL must start with http:// or https://"
}
}
},
"description": "The destination each network setting (`network = \"fetch\"` or\n`\"tcp\"`) names on each instance, and whether it is approved. Empty\nwhen the plugin declares no network setting. A `pending` row is not\nreachable until it is approved; `covered` is false while one is."
}
}
}
Status 400: An override is not allowed. As text/plain, when the body is not syntactically valid JSON.
{
"error": "bad_request",
"message": "The request could not be understood.",
"status": 400
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route. A 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 404: No such plugin.
{
"error": "not_found",
"message": "That page or resource was not found.",
"status": 404
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Status 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 `approve` at line 1 column 2
Schema:
A text/plain body: a string.
Status 500: The grant could not be stored.
{
"error": "internal_error",
"message": "Something went wrong on the Bookclerk daemon.",
"status": 500
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Status 504: The request ran past the API's time budget.
request timed out
Schema:
A text/plain body: a string.
Serve an embedded plugin.toml logo file from under the plugin install root.
Access: The operator (token or session) only.
Credentials: operatorToken or operatorSession
kindpathstringrequiredPlugin kind (source,destination,integration, …).idpathstringrequiredPlugin id.
- 200The logo (PNG, or SVG served with a restrictive CSP). Body:
BinaryBody(image/png);BinaryBody(image/svg+xml) -
401The caller is not signed in, or the credential is wrong. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
403The caller's role does not allow this route. Body:
ApiError(application/json)3 fieldserrorstringrequiredStable machine slug.messagestringExplanation for people.statusintegerThe HTTP status, repeated.
-
404The plugin has no logo. Body:
ErrorJson(application/json)3 fieldserrorstringrequiredMachine slug (same as [ErrorBody::code]).messagestringrequiredOperator-facing explanation.statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
- 504The request ran past the API's time budget. Body: string (
text/plain)
$ curl 'http://127.0.0.1:8787/api/plugins/<kind>/<id>/logo' \
-H 'Authorization: Bearer <operatorToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/api/plugins/<kind>/<id>/logo' `
-Headers @{ Authorization = 'Bearer <operatorToken>' }
import requests
response = requests.get(
"http://127.0.0.1:8787/api/plugins/<kind>/<id>/logo",
headers={"Authorization": "Bearer <operatorToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/api/plugins/<kind>/<id>/logo", {
headers: { Authorization: "Bearer <operatorToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
.get("http://127.0.0.1:8787/api/plugins/<kind>/<id>/logo")
.header("Authorization", "Bearer <operatorToken>")
.send()
.await?;
println!("{} {}", response.status(), response.text().await?);
Status 200: The logo (PNG, or SVG served with a restrictive CSP). The body is binary (image/png).
Schema:
A image/png body: binary bytes.
Status 401: The caller is not signed in, or the credential is wrong.
{
"error": "unauthorized",
"message": "Operator authentication is required. Sign in with your operator token.",
"status": 401
}
Schema:
{
"type": "object",
"description": "An error. `error` is a stable slug; bodies the error middleware writes also carry `message` and `status`, and some routes add fields of their own.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine slug.",
"examples": [
"not_found"
]
},
"message": {
"type": "string",
"description": "Explanation for people.",
"examples": [
"That page or resource was not found."
]
},
"status": {
"type": "integer",
"description": "The HTTP status, repeated.",
"examples": [
404
]
}
}
}
Status 403: The caller's role does not allow this route.
{
"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 plugin has no logo.
{
"error": "not_found",
"message": "That page or resource was not found.",
"status": 404
}
Schema:
{
"type": "object",
"description": "JSON error object (`error`, `message`, numeric `status`) for API clients.",
"required": [
"error",
"message",
"status"
],
"properties": {
"error": {
"type": "string",
"description": "Machine slug (same as [`ErrorBody::code`]).",
"example": "not_found"
},
"message": {
"type": "string",
"description": "Operator-facing explanation.",
"example": "That page or resource was not found."
},
"status": {
"type": "integer",
"format": "int32",
"description": "Numeric HTTP status (duplicates the response status for clients).",
"example": 404,
"minimum": 0
}
}
}
Status 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