View Categories

Abilities API, REST and AI Assistants

0:00 5:09
Table of Contents

On WordPress 6.9 and later, with the Premium or Agency plan, GOCSM registers its operations with the WordPress Abilities API. AI assistants (through an MCP server), automation tools and scripts can then manage snippets without opening the admin screens. Each ability is also available over REST at /wp-json/wp-abilities/v1/abilities/gocsm/{ability}/run, authenticated as a WordPress user, for example with an application password.

Over REST, read-only abilities take GET with the input in an input query parameter. The delete abilities take DELETE the same way. Every other ability takes POST with a JSON body of {"input": {...}}. GET /wp-json/wp-abilities/v1/abilities?category=gravityops lists the abilities with their input and output schemas.

Every ability requires the same permission as the Code Snippet Manager screens: gform_full_access when Gravity Forms is active, otherwise manage_options.

Writing code over the API is off by default #

Some actions put code on the site that has not been there before:

  • creating a snippet
  • changing a snippet’s code or type, including with find-and-replace edits
  • adding a GitHub collection, or changing the branch a collection syncs
  • importing snippets, from a GOCSM export or from the Code Snippets plugin

Over the API these are refused unless the site allows them. That way an AI assistant, or a stolen application password, cannot run new PHP on the site. To allow them, add this line to wp-config.php:

define( 'GOCSM_ALLOW_API_CODE_WRITES', true );

The switch is a constant rather than a setting, so a tool that can change WordPress options still cannot turn it on. The admin screens are not affected by it.

Everything else works without the constant. That includes turning snippets on and off, editing their name, description, scope, tags, folder and configuration values, deleting custom snippets, applying updates from collections that are already set up, restoring earlier revisions, and import previews (dry runs).

Configuration values stay hidden unless requested #

Configuration values can hold API keys and other credentials, so abilities leave them out unless the call sets include_config_values: true. Snippet code is returned. Exports made through the API have empty configuration values unless the same option is set.

Avoiding overwrites #

gocsm/get-snippet returns a version token, which changes whenever the snippet’s name, description, type, code, scope or configuration values change. Pass it as expected_version to gocsm/update-snippet or gocsm/patch-snippet. If the snippet changed after you read it, the change is refused with a gocsm_conflict error (HTTP 409) and nothing is saved. Updates return the new version.

Abilities #

Snippets #

Ability What it does
gocsm/list-snippets Lists snippets with their type, status, folder, pending updates, any error message, and edit link. Filters by type, status, tag, collection, folder or search term.
gocsm/get-snippet One snippet in full: code, scope, tags, folder, configuration variables and pending update.
gocsm/create-snippet Creates a snippet, and activates it if asked. Needs code writes.
gocsm/update-snippet Changes only the fields given. Changing code or type needs code writes. Snippets from a GitHub collection only accept scope, tags, folder and configuration values.
gocsm/patch-snippet Changes part of a snippet’s code with find-and-replace edits, without sending the whole snippet. Each edit must match exactly as many times as it expects, or nothing is saved. Needs code writes.
gocsm/delete-snippet Deletes a custom snippet with its configuration and revisions.
gocsm/activate-snippet / gocsm/deactivate-snippet Turns a snippet on or off, reporting why when activation fails.
gocsm/get-pending-update Shows a collection snippet’s pending update: both versions of the code and the configuration variables it adds or removes.
gocsm/apply-update Applies a pending update.

Collections #

Ability What it does
gocsm/list-collections Lists collections with sync status and snippet counts, and whether a GitHub token is configured.
gocsm/add-collection Adds a custom collection, or a GitHub collection (needs code writes).
gocsm/update-collection Renames a collection or turns auto-update on or off. Changing the branch needs code writes.
gocsm/sync-collection Checks a GitHub collection for changes now.
gocsm/delete-collection Deletes a collection and all of its snippets. Requires confirm: true.

Folders, tags and revisions #

Ability What it does
gocsm/list-folders, gocsm/create-folder, gocsm/rename-folder, gocsm/delete-folder Manage folders. Only empty folders can be deleted.
gocsm/move-snippets-to-folder Moves snippets into a folder, or out of folders with folder_id: 0.
gocsm/list-tags Lists tags in use.
gocsm/list-revisions, gocsm/get-revision Lists a snippet’s revisions and compares one with the current version.
gocsm/restore-revision Restores a snippet to an earlier revision.

Site #

Ability What it does
gocsm/get-status Version, snippet counts, snippets in error, pending updates, filesystem status, and whether code writes are allowed.
gocsm/get-settings / gocsm/update-settings Read and change the options on the Settings tab.
gocsm/get-sync-log Reads the Sync Log, with the same filters as the Sync Log tab.
gocsm/get-admin-urls Links to the Code Snippet Manager screens.
gocsm/export-snippets Exports snippets in the JSON format the Import screen accepts.
gocsm/import-snippets Imports a GOCSM JSON export. Previews by default; a real import (dry_run: false) needs code writes.
gocsm/import-code-snippets Imports from the Code Snippets plugin, from this site’s data or from an export. Previews by default; a real import needs code writes.

Each ability describes its own inputs and outputs, so clients that list abilities can discover the exact fields.

What are your Feelings