Plugins

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

Last updated View as Markdown

Plugin packages, instances, consent and deployment.

Back to the web API reference.

GET /api/config/plugin-instances

GET /api/config/plugin-instances.

Access: The operator (token or session) only.

Credentials: operatorToken or operatorSession

Responses

  • 200Every plugin instance with its deployments. Body: PluginInstancesResponse (application/json)2 fields
    • node_idstringrequiredId of the node that answered; its deployments carry its own observations.
    • instancesarray of PluginInstanceViewrequiredEvery plugin instance in the library.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The configuration could not be read. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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

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

Request body

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.

Responses

  • 200The new instance. Body: PluginInstanceCreated (application/json)4 fields
    • plugin_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; null for 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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such plugin, or it has no pinned schema. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat 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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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}

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

Parameters

  • idpathstringrequiredPlugin instance id.

Responses

  • 200The instance was removed. Body: PluginInstanceDeleted (application/json)2 fields
    • plugin_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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such instance. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 409The instance is a default or still deployed. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 500The configuration could not be read or written. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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

GET /api/config/plugin-instances/{id}/config.

Access: The operator (token or session) only.

Credentials: operatorToken or operatorSession

Parameters

  • idpathstringrequiredPlugin instance id.

Responses

  • 200The instance's settings document (secrets as names only). Body: PluginInstanceConfigResponse (application/json)7 fields
    • plugin_instance_idstringrequiredInstance id.
    • plugin_keystringrequiredCanonical plugin key.
    • revisioninteger (int64)requiredCompare-and-swap revision of the document.
    • settingsmap of string to SettingValuerequiredScalar settings the operator wrote.
    • secret_refsarray of InstanceSecretRefV1requiredSecret refs; ciphertext stays in encrypted_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 of SettingSpecrequiredDeclared settings from the pinned schema; empty when there is none.
  • 400The id is not a plugin instance id. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such instance, or it has no document yet. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 500The configuration could not be read. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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

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

Parameters

  • idpathstringrequiredPlugin instance id.

Request body

application/json: PutPluginInstanceConfig

  • expected_revisioninteger (int64)requiredRevision the caller last observed.
  • settingsmap of string to SettingValueScalar 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 declared secret setting. Each is sealed into encrypted_secrets and referenced from the document; the plaintext is never stored in the document or echoed back.

Responses

  • 200The document after the change. Body: PluginInstanceConfigChanged (application/json)4 fields
    • plugin_instance_idstringrequiredInstance id.
    • revisioninteger (int64)requiredRevision after the write; unchanged when the same write was replayed.
    • settingsmap of string to SettingValuerequiredScalar settings now stored.
    • secret_refsarray of InstanceSecretRefV1requiredSecret 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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such instance, or its plugin has no pinned schema. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 409expected_revision is not the current revision. Body: RevisionConflict (application/json)2 fields
    • errorstringrequiredAlways revision_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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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

GET /api/config/plugin-instances/{id}/filter: which books the storage destination takes.

Access: The operator (token or session) only.

Credentials: operatorToken or operatorSession

Parameters

  • idpathstringrequiredPlugin instance id of the destination.

Responses

  • 200The destination's filter. Body: DestinationFilterResponse (application/json)3 fields
    • plugin_instance_idstringrequiredThe destination's plugin instance id.
    • revisioninteger (int64)requiredRevision of the destination's core.destination document; 0 when 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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such instance. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 500The filter could not be read. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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

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

Parameters

  • idpathstringrequiredPlugin instance id of the destination.

Request body

application/json: DestinationFilter

  • rulesarray of FilterRuleFilter rules, at most 64. Empty means the destination takes every book. At most 64 items.

Responses

  • 200The filter after the change. Body: DestinationFilterResponse (application/json)3 fields
    • plugin_instance_idstringrequiredThe destination's plugin instance id.
    • revisioninteger (int64)requiredRevision of the destination's core.destination document; 0 when 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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such instance. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 409The filter kept changing underneath the write. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat 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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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

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

Parameters

  • idpathstringrequiredPlugin instance id of the storage instance.

Responses

  • 200The instance's drop folder settings, or null for a destination. Body: IntakeResponse (application/json)3 fields
    • plugin_instance_idstringrequiredThe storage instance's plugin instance id.
    • revisioninteger (int64)requiredRevision of the instance's core.intake document; 0 when none was written, so the instance is a destination.
    • intakeIntakeSettings or nullThe drop folder's settings; null when the instance is a destination.
  • 400The id is not a plugin instance id. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such instance. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 500The settings could not be read. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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

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

Parameters

  • idpathstringrequiredPlugin instance id of the storage instance.

Request body

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 (default move).
  • attribute_toIntakeAttributionWho holds the ingested books (default owner).
  • patroninteger (int64) or nullThe user id that holds every book in owner mode; required there and refused in subfolder mode. 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 nullWith after_ingest = move, delete _imported day folders older than this many days, 1 to 3,650; absent keeps them. At least 1; at most 3650.

Responses

  • 200The settings after the change. Body: IntakeResponse (application/json)3 fields
    • plugin_instance_idstringrequiredThe storage instance's plugin instance id.
    • revisioninteger (int64)requiredRevision of the instance's core.intake document; 0 when none was written, so the instance is a destination.
    • intakeIntakeSettings or nullThe drop folder's settings; null when 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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such instance. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 409The instance is deployed, or the document kept changing. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 413The body is over 16 KiB. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 415The body is not sent as application/json. As text/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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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

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

Parameters

  • idpathstringrequiredPlugin instance id of the storage instance.

Responses

  • 200The instance is a destination. Body: IntakeResponse (application/json)3 fields
    • plugin_instance_idstringrequiredThe storage instance's plugin instance id.
    • revisioninteger (int64)requiredRevision of the instance's core.intake document; 0 when none was written, so the instance is a destination.
    • intakeIntakeSettings or nullThe drop folder's settings; null when the instance is a destination.
  • 400The id is not a plugin instance id. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such instance. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 409The instance is deployed, or the document kept changing. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 500The document could not be read or written. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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}

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

Parameters

  • idpathstringrequiredPlugin instance id.
  • node_idpathstringrequiredNode id.

Request body

application/json: PutPluginDeployment

  • desiredDesiredStaterequiredWhat the node should do: present or absent (the scheduler's placed / unplaced are 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".

Responses

  • 200The deployment after the change. Body: PluginDeploymentChanged (application/json)5 fields
    • deployment_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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such instance or node. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 409The instance is placed by the scheduler (an error message), or expected_revision is stale (revision_conflict with current_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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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

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

Parameters

  • idpathstringrequiredPlugin instance id.

Request body

application/json: PutPluginPlacement

  • replicasinteger or allrequiredA 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.

Responses

  • 200The scheduler now places the instance. Body: PluginPlacementChanged (application/json)2 fields
    • plugin_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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such instance. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 409expected_revision is not the current revision. Body: RevisionConflict (application/json)2 fields
    • errorstringrequiredAlways revision_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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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

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

Parameters

  • idpathstringrequiredPlugin instance id.

Responses

  • 200The instance is back to manual deployment. Body: PluginPlacementDeleted (application/json)2 fields
    • plugin_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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such instance. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 500The configuration could not be read or written. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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

GET /api/config/plugins: every installed plugin.

Access: The operator (token or session) only.

Credentials: operatorToken or operatorSession

Responses

  • 200Every installed plugin. Body: InstalledPluginsResponse (application/json)1 field
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 500The configuration could not be read. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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

POST /api/config/plugins: install (and maybe activate) a version.

Access: The operator (token or session) only.

Credentials: operatorToken or operatorSession

Request body

application/json: PostPluginInstall

  • coordinatestring or nullRegistry coordinate (cargo:…@v, registry:…#name@v).
  • packagestring or nullOperator-placed package directory under plugin-packages/.
  • activatebooleanMake the new version active even when another is.
  • approvebooleanRecord the requested consent as approved.
  • allow_unverified_publisherbooleanAccept a publisher without independent authenticity.

Responses

  • 200The installed version. Body: PluginInstalled (application/json)3 fields
    • createdbooleanrequiredTrue 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 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. Body: ErrorMessage (application/json); string (text/plain)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The 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. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 404A local package is missing its package.json or archive.tar.gz. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 409The version is already installed with different artifacts. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat 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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 502The package registry could not be reached or answered badly. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 503The database plugin is unavailable; retry. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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}

GET /api/config/plugins/{key}: one installed plugin with its pinned settings schema.

Access: The operator (token or session) only.

Credentials: operatorToken or operatorSession

Parameters

  • keypathstringrequiredPlugin key.

Responses

  • 200The plugin with its installed versions and pinned schema. Body: InstalledPluginDetail (application/json)1 field
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such plugin. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 500The configuration could not be read. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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}

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

Parameters

  • keypathstringrequiredPlugin key.

Responses

  • 200The plugin was uninstalled; uninstalled is false when no version was active, so the request is idempotent. Body: PluginUninstalled (application/json)3 fields
    • plugin_keystringrequiredCanonical plugin key.
    • uninstalledbooleanrequiredTrue when an active-version pointer existed and was cleared.
    • deployments_undeployedintegerrequiredDeployment rows switched to absent across the plugin's instances. At least 0.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable 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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 500The configuration could not be read or written. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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

PUT /api/config/plugins/{key}/active: activate, update, or roll back.

Access: The operator (token or session) only.

Credentials: operatorToken or operatorSession

Parameters

  • keypathstringrequiredPlugin key.

Request body

application/json: PutActiveVersion

  • versionstringrequiredInstalled version to activate.

Responses

  • 200The active version after the change. Body: ActiveVersionChanged (application/json)3 fields
    • plugin_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 fields
    • errorstringrequiredStable 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 Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such plugin or version. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat 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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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

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

Parameters

  • keypathstringrequiredPlugin key.
  • versionpathstringrequiredSemver version.

Responses

  • 200The version's grant was approved. Body: PluginVersionApproved (application/json)4 fields
    • plugin_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 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such plugin or version. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 500The configuration could not be read or written. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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.

GET /api/plugins/{id}/consent

Loads the consent dialog for one plugin, including coverage against the stored grant.

Access: The operator (token or session) only.

Credentials: operatorToken or operatorSession

Parameters

  • idpathstringrequiredPlugin id.
  • plugin_keyquerystringCanonical PluginKey; when set, wins over the path alias.

Responses

  • 200What the plugin asks for and what is granted. Body: PluginConsentResponse (application/json)13 fields
    • plugin_idstringrequiredPlugin id whose grant is being reviewed.
    • plugin_keystringrequiredCanonical PluginKey for this install (empty when unknown).
    • provenancestringrequiredHost-evaluated provenance label.
    • runtimestringrequiredGuest runtime (native or workerd) — 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.
    • existingPluginGrantView or nullPreviously approved grant, when one is stored.
    • pendingPluginConsentPending or 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.
    • brandPluginConsentBrand or nullOptional portal or manifest branding for the dialog.
    • limitsPluginConsentLimitsrequiredHost-capped resource defaults (workerd budgets + shared disk). Always set.
    • host_user_agentstringrequiredThe User-Agent this host sends for the plugin's requests, except to the request's ownUserAgentHosts.
    • setting_destinationsarray of PluginSettingDestinationViewrequiredThe 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. A pending row is not reachable until it is approved; covered is false while one is.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such plugin. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 500The grant could not be read. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

$ 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?);

Example response

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.

POST /api/plugins/{id}/consent

Persists an approved plugin grant after validating operator overrides.

Access: The operator (token or session) only.

Credentials: operatorToken or operatorSession

Parameters

  • idpathstringrequiredPlugin id.
  • plugin_keyquerystringCanonical PluginKey; when set, wins over the path alias.

Request body

application/json: PluginConsentApproveRequest

  • approvebooleanrequiredMust be true; a false value is rejected with 400.
  • grantPluginGrantOverride or nullOptional operator overrides applied on top of the manifest request.
  • setting_destinationsarray of PluginSettingDestinationApprovalSetting destinations to approve, from the response's setting_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.

Responses

  • 200The grant was stored. Body: PluginConsentResponse (application/json)13 fields
    • plugin_idstringrequiredPlugin id whose grant is being reviewed.
    • plugin_keystringrequiredCanonical PluginKey for this install (empty when unknown).
    • provenancestringrequiredHost-evaluated provenance label.
    • runtimestringrequiredGuest runtime (native or workerd) — 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.
    • existingPluginGrantView or nullPreviously approved grant, when one is stored.
    • pendingPluginConsentPending or 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.
    • brandPluginConsentBrand or nullOptional portal or manifest branding for the dialog.
    • limitsPluginConsentLimitsrequiredHost-capped resource defaults (workerd budgets + shared disk). Always set.
    • host_user_agentstringrequiredThe User-Agent this host sends for the plugin's requests, except to the request's ownUserAgentHosts.
    • setting_destinationsarray of PluginSettingDestinationViewrequiredThe 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. A pending row is not reachable until it is approved; covered is 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 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 401The caller is not signed in, or the credential is wrong. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. A write sent with a session cookie but without a matching Origin or Referer is refused. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404No such plugin. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 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 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

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

Example response

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

Parameters

  • kindpathstringrequiredPlugin kind (source, destination, integration, …).
  • idpathstringrequiredPlugin id.

Responses

  • 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 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 403The caller's role does not allow this route. Body: ApiError (application/json)3 fields
    • errorstringrequiredStable machine slug.
    • messagestringExplanation for people.
    • statusintegerThe HTTP status, repeated.
  • 404The plugin has no logo. Body: ErrorJson (application/json)3 fields
    • errorstringrequiredMachine slug (same as [ErrorBody::code]).
    • messagestringrequiredOperator-facing explanation.
    • statusinteger (int32)requiredNumeric HTTP status (duplicates the response status for clients). At least 0.
  • 504The request ran past the API's time budget. Body: string (text/plain)

Example request

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

Example response

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