ParoiCMS API Plugin (@paroicms/api-plugin)

This plugin opens a remote HTTP API over a ParoiCMS site, protected by Personal Access Tokens. It covers the whole content surface: reading the site schema and documents, searching, creating and translating documents and parts, updating fields, managing media and accounts.

The paroicms CLI ships with the package as the reference client of the API. The API is usable without the CLI (e.g. with curl).

This package is part of ParoiCMS.

Installation of the backend plugin

Install it:

npm i @paroicms/api-plugin

Enable it in your site-schema.json:

{
  "plugins": [
    // ...
    "@paroicms/api-plugin"
  ]
}

Create a Personal Access Token

1. Go to your ParoiCMS Admin UI
2. Navigate to User Settings → Personal Access Tokens
3. Copy the token (it will only be shown once)

On a development site that allows the unsafe login (allowUnsafeLogin), the CLI can create the token itself:

export PAROICMS_PAT=$(npx paroicms get-pat --site "http://demo2.localhost:28000" --email "dev@localhost" --password "init")

Such a token is flagged as a dev token and is automatically ignored on sites where allowUnsafeLogin is off.

The CLI

Configure the target site with the PAROICMS_SITE_URL and PAROICMS_PAT environment variables, or with the --site <url> and --token <t> flags on any command.

Examples:

export PAROICMS_SITE_URL="https://your-site.example.com"
export PAROICMS_PAT="your-personal-access-token"

npx paroicms info
npx paroicms search plumbing tips -l en
npx paroicms set-fields "12:en" '{"summary": "A short text."}'

Run npx paroicms --help for the full command surface, and npx paroicms guide to learn how a ParoiCMS site is structured (documents, parts, fields, and the field value formats).

The raw HTTP protocol

POST to {site}/api/plugin/api-plugin with an Authorization: Bearer <PAT> header and a JSON body {"action": "...", "payload": {...}}. The response envelope is {"success": true, "data": ...} or {"success": false, "error": "...", "code"?: number}.

curl -X POST "https://your-site.example.com/api/plugin/api-plugin" \
  -H "Authorization: Bearer $PAROICMS_PAT" \
  -H "Content-Type: application/json" \
  -d '{"action": "searchDocuments", "payload": {"language": "en", "words": ["plumbing"]}}'

Actions and payloads mirror the CLI commands: getSiteInfo, loadSiteSchemaAndIds, loadRoutingClusterFromNode, searchDocuments, getDocument, createDocument, createPart, createDocumentTranslation, createPartTranslation, updateDocument, updateFields, updateSiteFields, publishDocument, unpublishDocument, moveDocument, deleteDocument, setMedia, deleteMedia, createAccount, removeSite.

License

Released under the MIT license.