Connect your own agent

Your own AI agent, or any program that sends HTTP requests, can edit your site through its WordPress REST API. This page covers the password, the routes and the request shapes.

Good to know

An agent with this password can change every editable field and the theme files on your site. Give it only to software you trust.
Undo in the Site agent covers only the Site agent's own changes. For your own agent, take a snapshot before each change.
Keep the password out of chat logs and out of any file you share or publish.

Get a password

Open the site's page in your dashboard.
Find the Connect your own AI agent card. It shows the Username.
Type a name for the agent and click Generate. With no name, it is called "My agent".
Copy the password. The card shows it once.

The password is a WordPress Application Password for the site's admin user. Each agent can have its own. The card appears once the site has finished building.

Turn a password off

On the same card, click Revoke next to the agent's name. The site's own system password is not listed there and cannot be revoked from the card.

Sign in

Send every request with HTTP Basic auth: the username from the card and the agent's Application Password. The routes are under /wp-json/oneclick/v1/ on your site's address. The card's Site URL row shows your WP Admin address. The site's address is the part before /wp-admin/.

bash

curl -u "USERNAME:APPLICATION_PASSWORD" \
  https://YOUR-SITE/wp-json/oneclick/v1/schema

Routes

Every path below follows /wp-json/oneclick/v1.

Route	What it does
`GET /schema`	Every field: key, label, type, scope (`site` or `post`), group, and whether it is writable.
`GET /fields?q=hero`	The same records, filtered. `q` matches the key, label or group. Also takes `group` and `scope`.
`GET /state?scope=site`	Current values of every site-wide field.
`GET /state?post_id=45`	Current values of the page fields of one page or post.
`POST /validate`	Checks a change without saving it. Returns `ok` and a list of `problems`.
`POST /state`	Saves a change, then clears the caches. Returns 400 with the problems if the change is invalid, and 409 listing the fields that could not be written.
`POST /cache/clear`	Clears the site's caches.
`GET /snapshot`	A copy of the site settings, the page fields of your pages, services and service areas, and the theme files.
`POST /snapshot/restore`	Puts a snapshot back. Body: `{"snapshot": { ... }}`. Clears the caches after.
`GET /files`	Lists the theme files you can read and write: `.php`, `.css`, `.js`, `.json`, `.txt`, `.svg`, `.html`. Paths are relative, like `assets/components/hero.css`.
`GET /files/{path}`	Reads one file. Returns `path`, `content` and `bytes`.
`PUT /files/{path}`	Writes one file. Body: `{"content": "..."}` or plain text. Creates the file and its folders inside the theme if needed. Clears the caches.
`DELETE /files/{path}`	Deletes one file. Clears the caches.

If your client cannot send PUT or DELETE, send POST with _method=PUT or _method=DELETE in the query string. File paths may not contain .., start with /, or go into hidden folders. If the theme folder cannot be written on that site, a file write or delete returns an error.

Request shapes for /validate and /state

A site-wide change:

json

{"site": {"fields": {"hero_headline": "New headline"}}}

A change to one page or post:

json

{"post": {"post_id": 45, "fields": {"FIELD_KEY": "New value"}}}

A key that is not in /schema is refused as an unknown field.
A site field sent in a post payload, or the other way round, is refused.
A read-only field is refused, and the problem names the field to write instead.

A complete edit

bash

SITE="https://YOUR-SITE"
AUTH="USERNAME:APPLICATION_PASSWORD"
API="$SITE/wp-json/oneclick/v1"

# 1. Save a rollback point.
curl -s -u "$AUTH" "$API/snapshot" > rollback.json

# 2. Find the field.
curl -s -u "$AUTH" "$API/fields?q=hero"

# 3. Check the change.
curl -s -u "$AUTH" -X POST -H 'content-type: application/json' \
  -d '{"site":{"fields":{"hero_headline":"New headline"}}}' \
  "$API/validate"

# 4. Save it.
curl -s -u "$AUTH" -X POST -H 'content-type: application/json' \
  -d '{"site":{"fields":{"hero_headline":"New headline"}}}' \
  "$API/state"

To roll back, post the snapshot object from rollback.json to /snapshot/restore.

SEO fields

SEO fields are page fields in the seo group: SEO title, SEO description, Canonical URL, Hide from search engines and Social share image. List them with /fields?group=seo and write them with a post payload.

Pages, posts, services and service areas

To create or list content, use the standard WordPress routes: /wp-json/wp/v2/pages, /wp-json/wp/v2/posts, /wp-json/wp/v2/service and /wp-json/wp/v2/service_area.

Theme colours and fonts

The Theme panel's colours and fonts are not fields in /schema. /state does not change them.

Matching the page to fields

Elements on a rendered page carry data-ocf-field="FIELD_KEY" for the field that controls them. The home page headline carries data-ocf-field="hero_headline".

Rules for your agent

Take a snapshot before the first write.
Look a field up in /schema or /fields before writing it. Write only fields marked writable.
Run /validate before /state.
Read a theme file before writing it, and change only what you need.
Do not write facts about the business that you were not given.
Open the page afterwards and check the result.

If it does not connect

401: check the username and the password. A revoked password stops working.
403 that is not JSON: the firewall in front of the site refuses some default user agents. Send your own User-Agent header.
404 on every route: check the site address. If you moved the site to another host, use its new address.