Plugins

List plugins

Every folder under <config>/plugins, valid or not, with what it asks for, what it was granted, and whether its process is up.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

Install a plugin from an archive

A zip with collectoh-plugin.json at its root (or one folder down), read by the archive reader every installer of extensions shares: a zip bomb, two names a disk takes for one, a name Windows writes as another’s, or an archive that brings its own .collectoh-source.json, is refused before anything is written. Installed off: nothing runs until it is enabled with grants. The archive itself is kept, so the extension can be shared with the community (POST /plugins/:id/share). An archive of the version already installed is checked as an install is and only kept beside it — its folder, settings, secrets and grants untouched — so one installed before archives were kept can be shared.

Authorisation

Bearer token or API key · Session cookie

Body

application/zip ·

• 201Success. application/json · Plugin
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. PLUGIN_INVALID: not a zip the reader takes (details.problem says why), no manifest, a manifest the host refuses, an id a built-in provider has, an entry that would land outside the folder, or a version Collectoh withdrew (details.reason revoked) application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 409CONFLICT: a plugin with that id is already installed at another version, or from a repository application/json · ErrorEnvelope

Read a plugin

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · Plugin
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Remove a plugin

Stops it and deletes its folder, and the archive kept from its install.

Authorisation

Bearer token or API key · Session cookie

• 204Done; no body.
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Disable a plugin

Stops the process and withdraws its providers; the folder stays.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · Plugin
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Enable a plugin with the granted permissions

The install prompt’s answer. grants may be what the manifest asked for or less, never more. Starts the process; a plugin that will not start is a 502 and stays off. One whose very version Collectoh withdrew from its community repository (source.revoked, or the archive kept from its upload) goes on only with acknowledgeWithdrawn: true — the admin read why and trusts it anyway — and is then not switched off again for that archive.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 200Success. application/json · Plugin
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: a grant it did not ask for, or a setting it needs is not filled in PLUGIN_INVALID: the folder has no usable manifest, or its id is a built-in provider’s application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 409CONFLICT: Collectoh withdrew this version and acknowledgeWithdrawn is not true (details.reason revoked; details.revoked is {reason, at}, as source.revoked) application/json · ErrorEnvelope
• 502PLUGIN_ERROR: the process did not start or did not greet in time application/json · ErrorEnvelope

The plugin’s recent stderr

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

Fill in the settings a plugin declares

By key (P6-10): a string sets one, null or an empty string clears it, a key left out keeps what it had. A secret is sealed with the server’s key at rest and never read back — the plugin’s settings say only that it is set. A plugin that is on starts again and is handed them before anything else; one that refuses them goes back to the values it had and keeps running.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 200Success. application/json · Plugin
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. VALIDATION_FAILED: a key the plugin does not declare, or emptying one it needs while it is on PLUGIN_INVALID: the folder has no usable manifest application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 502PLUGIN_ERROR: the running plugin refused the new values; the old ones stand application/json · ErrorEnvelope

Share an extension with the community

Sends the archive this server installed the extension from — exactly its bytes, read again as collectoh.com reads it — with the owner’s notes, source address and licence to Collectoh’s staff, through the Collectoh account that claimed this server; so only the server’s owner may. Approved, it is listed in Collectoh’s community repository at that version, its archive pinned by checksum; GET /plugins/submissions says where it stands. Only an extension whose canShare is true: uploaded or installed from an address since archives were kept (or the same version uploaded again since), at the version installed and 10 MB at most, and neither Collectoh’s own, nor installed from a repository, nor a version Collectoh withdrew.

Authorisation

Bearer token or API key · Session cookie

Body

application/json · object

• 201Success. application/json · ExtensionSubmission
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. PLUGIN_INVALID: the folder has no usable manifest (details.reason invalid), the archive kept is not one the shared archive reader takes, or collectoh.com refused it application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. FORBIDDEN: anyone but the server’s owner (details.reason owner) application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 409CONFLICT: this server isn’t claimed by a Collectoh account, or collectoh.com no longer knows it (details.reason claim); the extension can’t be shared — Collectoh’s own (official), installed from a repository (repository), a version Collectoh withdrew (revoked), or no archive kept for the version installed (archive); or collectoh.com refused it — this version waits for review already, its id is another account’s, or a version as new is published (details.reason as collectoh.com gives it) application/json · ErrorEnvelope
• 413PAYLOAD_TOO_LARGE: the archive is larger than 10 MB (details.reason too-large) application/json · ErrorEnvelope
• 429RATE_LIMITED: collectoh.com takes no more shares from this account for now application/json · ErrorEnvelope
• 502PROVIDER_UNAVAILABLE: Collectoh accounts could not be reached application/json · ErrorEnvelope

Update an extension from the repository it came from

The newest version the repository lists, checked as an install is, unpacked beside the old and put in its place. Settings are kept; an extension that was on runs again on its grants, unless the new version asks for more, when it is left off for an admin to agree.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · Plugin
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope

List what the configured extension repositories offer

Every repository in extensions.repositories, and Collectoh’s community repository while extensions.community is on (builtIn), read (kept ten minutes, unless refresh) and checked: each extension once, at the newest version this server can run, with whether Collectoh signed it (official) or its staff reviewed it for the community (community, never both), whether this server is new enough, and whether it is newer than the one installed. From the community repository only what a key this server trusts signed is listed; a version Collectoh withdrew from it (its revoked list, believed from there alone, and remembered for good) is listed nowhere, and reading it afresh switches off any such version installed here. It is read for that first, and even while extensions.community is off when anything installed here is under its review. Those made for adults are left out, and counted, unless extensions.show_adult is on.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

Install an extension from an address or a repository

An archive at an address (its SHA-256 checked when given), or an extension a listed repository — a configured one, or Collectoh’s community repository while it is on, which offers only what a key this server trusts signed — lists, by id: the archive checked against the checksum the repository gives, and its signature, when it has one, against the keys this server trusts. Never a version Collectoh withdrew from its community repository. Installed off, as an upload is.

Authorisation

Bearer token or API key · Session cookie

Body

application/json ·

• 201Success. application/json · Plugin
• 400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. PLUGIN_INVALID: the archive is not a plugin, not the one listed, its checksum or signature is wrong, this server is too old for it, or Collectoh withdrew that version (details.reason revoked) application/json · ErrorEnvelope
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. FORBIDDEN: an extension made for adults — by the repository’s word or its own manifest — while extensions.show_adult is off application/json · ErrorEnvelope
• 502PLUGIN_ERROR: the address or repository could not be read application/json · ErrorEnvelope

List the extensions shared with the community

What the Collectoh account that claimed this server has shared, from any of its servers, newest first: pending, approved, denied (with staff’s reason), withdrawn, or unpublished — taken down after it was published. Unclaimed, claimed is false and the list empty, and collectoh.com is not asked; the same when collectoh.com no longer knows this server.

Authorisation

Bearer token or API key · Session cookie

• 200Success. application/json · object
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
• 429RATE_LIMITED: collectoh.com was asked too often from this server application/json · ErrorEnvelope
• 502PROVIDER_UNAVAILABLE: Collectoh accounts could not be reached application/json · ErrorEnvelope

Take back an extension shared with the community

One still waiting for Collectoh’s staff: it is withdrawn and never listed. The server’s owner’s alone, as sharing is.

Authorisation

Bearer token or API key · Session cookie

• 204Done; no body.
• 401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
• 403FORBIDDEN: the account lacks settings:manage, or the library, label, age or schedule scope refuses it. FORBIDDEN: anyone but the server’s owner (details.reason owner) application/json · ErrorEnvelope
• 404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
• 409CONFLICT: this server isn’t claimed, or collectoh.com no longer knows it (details.reason claim); or staff have reviewed it already application/json · ErrorEnvelope
• 502PROVIDER_UNAVAILABLE: Collectoh accounts could not be reached application/json · ErrorEnvelope