1ClickWebsite External AI Agent Guide

Version: 1.0.0
Last updated: July 7, 2026

Read this as operating instructions for editing a 1ClickWebsite V2 WordPress site from Codex, Claude Code, Cursor, or another external AI agent.

Do not think in terms of the 1ClickWebsite hosted agent's internal tool calls. You have direct WordPress access. Use WordPress REST, OCF REST, normal browser inspection, and careful edit discipline.

Use this guide as a head start, not as final truth for every site. 1ClickWebsite will add more V2 templates over time, and field keys, visible sections, post types, component files, and schema details can vary by template or plugin version. Always inspect the current site's schema, state, posts, and theme files before writing.

Inputs You Need

The user should provide:

- Site URL: `https://example.com`
- WordPress username
- WordPress application password

If the user has not created an application password or does not know what access details to provide, send them this setup guide first:

```text
https://1clickwebsite.crisp.help/en/article/how-to-connect-your-own-ai-agent-to-edit-your-site-1fjd8uz/
```

They can paste the site URL, WordPress username, and application password directly into the AI tool, or store them in a trusted local environment file if they prefer not to paste credentials into chat.

Use HTTP Basic Auth for REST calls:

```text
Authorization: Basic base64(username:application_password_without_spaces)
Content-Type: application/json
```

Application passwords are often displayed with spaces. Remove spaces before building the Basic Auth value.

Core Routes

WordPress REST:

```text
https://example.com/wp-json/wp/v2
```

OCF REST:

```text
https://example.com/wp-json/ocf/v1
```

Use these OCF endpoints most often:

| Need | Route |
| --- | --- |
| Read field schema | `GET /ocf/v1/schema` |
| Read site fields and design state | `GET /ocf/v1/state` |
| Read post-scoped OCF fields | `GET /ocf/v1/state?post_id=123` |
| Validate OCF payload | `POST /ocf/v1/validate` |
| Save OCF content fields | `POST /ocf/v1/state` |
| Save design tokens | `POST /ocf/v1/design` |
| List active theme files | `GET /ocf/v1/files` |
| Read/write active theme files | `GET/PUT /ocf/v1/files/{path}` |
| Clear page cache | `POST /ocf/v1/cache/clear` |

If a file route has a dotted path, such as `assets/components/hero.css`, use `rest_route`:

```text
https://example.com/?rest_route=/ocf/v1/files/assets/components/hero.css
```

For writes through `rest_route`, use `POST` plus `_method=PUT` if raw `PUT` is blocked.

What To Ignore From The Hosted Agent

The hosted 1ClickWebsite agent has internal tools for chat threads, billing, token usage, temporary chat attachments, hosted image generation, screenshot storage, and change-set rollback.

As an external agent, you usually do not need those.

Translate hosted-agent ideas like this:

- `find_theme_files` -> call `GET /ocf/v1/files` and search the returned paths yourself.
- `read_theme_file` -> call `GET /ocf/v1/files/{path}`.
- `write_theme_file` -> call `PUT /ocf/v1/files/{path}` after reading the current file.
- `find_ocf_fields` -> call `GET /ocf/v1/schema` and inspect the schema yourself.
- `get_ocf_values` -> call `GET /ocf/v1/state` or `GET /ocf/v1/state?post_id=123`.
- `set_ocf_values` -> call `POST /ocf/v1/validate`, then `POST /ocf/v1/state`.
- `list_design_tokens` -> read `design` or `design_tokens` from `GET /ocf/v1/state`.
- `set_design_tokens` -> call `POST /ocf/v1/design`.
- `list_posts`, `read_post`, `create_post`, `update_post` -> use normal `/wp/v2/...` endpoints.
- `list_media`, `upload_media` -> use `/wp/v2/media`.
- `qa_check` -> use your own browser/screenshot tool.
- `rollback_*` -> use WordPress revisions, saved before-edit copies, or a platform restore point if available.

Edit Discipline

Follow this order:

1. Inspect the site, schema, post, file, or media first.
2. Prefer OCF fields, WordPress posts, media IDs, and design tokens before raw theme edits.
3. Edit the smallest useful surface.
4. Use `draft` unless the user clearly asks to publish.
5. Upload images to WordPress media first, then use the attachment ID.
6. Clear cache once after visible changes.
7. Verify the visible page in a browser when layout or content visibility matters.
8. Check the public page source and mobile view before calling visual/content cleanup done. Old text, hidden sections, metadata, mobile-only blocks, or cached markup can remain even when the desktop page looks clean.
9. Report exactly what changed.

Do not invent pricing, awards, licenses, guarantees, emergency service, 24/7 service, same-day service, review counts, certifications, insurance, warranties, or response times.

OCF Model

OCF is the structured editing layer behind V2 sites.

Always read `GET /ocf/v1/schema` when field keys are unclear.

The useful field list is usually under `schema.fields` in the response. Some installs may wrap the response differently, so inspect the returned JSON before assuming the exact path.

Trimmed example:

```json
{
  "schema": {
    "fields": {
      "hero_headline": {
        "label": "Hero headline",
        "type": "text",
        "scope": "site",
        "group": "hero"
      },
      "service_content": {
        "label": "Service content",
        "type": "wysiwyg",
        "scope": "post",
        "group": "service"
      },
      "page_featured_image": {
        "label": "Featured image",
        "type": "image_id",
        "scope": "post"
      }
    }
  }
}
```

The schema can tell you:

- field key
- label
- type
- group
- scope: `site` or `post`
- supported post types for post-scoped fields

Post-scoped fields may not always include the `post_types` filter you expect. Treat `scope`, field names, labels, groups, and current state as clues, then confirm by reading the specific post's OCF state.

Site-scoped fields control shared content like homepage sections, CTA copy, business info, gallery headings, phone, address, and labels. The exact fields depend on the active template.

Post-scoped fields control a specific post, page, service, location, or gallery item. Pass `post_id` when reading or saving them.

For OCF image fields, use a WordPress media attachment ID, not a URL.

When saving OCF values:

1. Read schema.
2. Read current value.
3. Validate changed payload with `POST /ocf/v1/validate`.
4. Save with `POST /ocf/v1/state`.
5. Clear cache.

OCF Save Payloads

For site-scoped fields, validate and save this shape:

```json
{
  "site": {
    "hero_headline": "Fast plumbing help in Austin",
    "hero_subheadline": "Licensed local plumbers for repairs and installs."
  }
}
```

For post-scoped fields, do not send `post_id` at the top level. Nest it under `post` with `fields`:

```json
{
  "post": {
    "post_id": 45,
    "fields": {
      "service_name": "Drain Cleaning",
      "service_short_desc": "Fast help for clogged sinks, tubs, and sewer lines.",
      "service_content": "<p>We clear slow drains, main line clogs, and recurring backups.</p>",
      "page_featured_image": 37
    }
  }
}
```

For design token changes, validate and save this shape:

```json
{
  "design": {
    "color_accent": "#A64D3D",
    "font_heading": "Libre Baskerville"
  }
}
```

`POST /ocf/v1/validate` can be more forgiving than `POST /ocf/v1/state`. A payload shape may validate but still fail to save, for example with `post.post_id is required`. When saving post fields, use the nested `post.post_id` and `post.fields` shape shown above.

Custom Schema Fields

Do not assume you can add live OCF fields by editing `schema.json` through the file API. The active `/ocf/v1/schema` response may come from a registry, generated manifest, plugin cache, theme boot process, or another build step. If a new field key does not appear in `GET /ocf/v1/schema`, treat it as unsupported on that live site until the template/plugin owner documents the schema refresh path.

For normal site edits, use fields already returned by `/ocf/v1/schema`. If a requested change needs a new field, prefer an existing field, a normal WordPress post, or a small theme-file change first.

Design System

Use the existing design system before adding new CSS.

Do not make sections narrower, headings larger, or layout spacing more dramatic just because you are editing a section. Many 1ClickWebsite templates already have tuned container widths, heading sizes, and responsive spacing. Keep existing width, scale, and hierarchy unless the user specifically asks for a layout or typography change, or the current layout is visibly broken.

Design Tokens

Read current tokens from `GET /ocf/v1/state`, usually under `design` or `design_tokens`.

Common tokens:

- `color_heading`
- `color_body`
- `color_accent`
- `color_accent_hover`
- `color_secondary`
- `color_bg`
- `color_bg_alt`
- `color_bg_dark`
- `color_heading_alt`
- `color_body_alt`
- `color_border`
- `color_border_light`
- `color_border_alt`
- `font_heading`
- `font_body`

Use `POST /ocf/v1/design` for palette or font changes before hardcoding CSS.

Example:

```json
{
  "design": {
    "color_accent": "#A64D3D",
    "font_heading": "Libre Baskerville"
  }
}
```

CSS Variables And Globals

Before writing CSS, inspect `assets/global.css`.

Reuse existing variables, classes, and patterns for:

- colors
- border radius
- shadows
- containers
- buttons
- cards
- spacing
- transitions
- typography

Prefer existing `--ocf-*` variables:

```css
color: var(--ocf-color-heading);
background: var(--ocf-color-bg-alt);
border-color: var(--ocf-color-border);
font-family: var(--ocf-font-heading);
```

Use hardcoded values only when a focused component truly needs an exception.

Theme File Roles

- `style.css`: theme metadata. Do not edit for styling.
- `assets/global.css`: global variables, containers, typography, buttons, forms, reusable primitives.
- `assets/components/*.css`: focused component or section styling.
- `components/*.php`: component markup.
- `front-page.php`: homepage section order and component calls.
- `page-*.php`: page templates.
- `manifest.json`: editor/agent metadata.

For styling work:

1. Read the relevant `components/*.php`.
2. Read the matching `assets/components/*.css`.
3. Read `assets/global.css` only when touching shared primitives.
4. Make the smallest focused edit.
5. Clear cache and check desktop/mobile.

When checking design work, inspect the public page source or rendered DOM for old copy and hidden duplicate sections. Also check mobile, because some templates can show different markup, different line breaks, or mobile-only content.

For additive CSS, prefer a stable managed block:

```css
/* OCF_AGENT_BLOCK: theme-redesign */
/* focused CSS here */
/* /OCF_AGENT_BLOCK: theme-redesign */
```

WordPress Content Model

Common post types:

| Content | Endpoint |
| --- | --- |
| Blog posts | `/wp/v2/posts` |
| Pages | `/wp/v2/pages` |
| Services | `/wp/v2/service` |
| Service areas/locations | `/wp/v2/service_area` |
| Media | `/wp/v2/media` |

Common statuses:

- `draft`: hidden publicly
- `publish`: public
- `private`: logged-in only
- `trash`: moved to trash

Use `context=edit` when reading posts for editing.

Visible Body Fields

Do not assume native WordPress `content` is visible.

Defaults:

- Blog posts: native WordPress `content`.
- Service pages: OCF `service_content`.
- Service area pages: OCF `service_area_content`.
- Regular pages: native content or page-specific OCF fields depending on template.

Before editing service or service area body copy:

1. Read schema.
2. Find post-scoped fields for that post type.
3. Read `GET /ocf/v1/state?post_id=123`.
4. Update the OCF body field, not just native `content`.

Media

Upload images through:

```text
POST /wp-json/wp/v2/media
Content-Disposition: attachment; filename="image.jpg"
Content-Type: image/jpeg
```

Use the returned media `id` for:

- `featured_media`
- OCF image fields
- `page_featured_image`
- gallery item images

If you generate images with your own model, show a preview first unless the user clearly says to generate and use it in one step.

Common Workflows

Change Homepage Copy

1. `GET /ocf/v1/schema`
2. Find field keys.
3. `GET /ocf/v1/state`
4. `POST /ocf/v1/validate` with `{ "site": { ...changedFields } }`
5. `POST /ocf/v1/state` with the same `{ "site": { ...changedFields } }` payload
6. `POST /ocf/v1/cache/clear`
7. Verify the page.

Add A Service Page

1. Check duplicates: `GET /wp/v2/service?search=...&context=edit`
2. Upload image if needed.
3. Create draft service: `POST /wp/v2/service`
4. Save service OCF fields with `POST /ocf/v1/state` using `{ "post": { "post_id": 123, "fields": { ... } } }`.
5. Clear cache.
6. Return post ID, status, and preview/admin URL.

These fields are common, but check the current schema because future templates can differ:

- `service_name`
- `service_short_desc`
- `service_content`
- `page_featured_image`

Add A Service Area Page

1. Check duplicates: `GET /wp/v2/service_area?search=...&context=edit`
2. Upload image if needed.
3. Create draft service area: `POST /wp/v2/service_area`
4. Save service area OCF fields with `POST /ocf/v1/state` using `{ "post": { "post_id": 123, "fields": { ... } } }`.
5. Clear cache.
6. Return post ID, status, and preview/admin URL.

These fields are common, but check the current schema because future templates can differ:

- `service_area`
- `service_area_description`
- `service_area_content`
- `page_featured_image`

Edit Styling

1. `GET /ocf/v1/files`
2. Read component PHP.
3. Read focused component CSS.
4. Reuse design tokens and existing globals.
5. Write a focused CSS change.
6. Clear cache.
7. Check desktop and mobile.

Add Gallery Images

1. Confirm the template uses `gallery_item`.
2. Upload images to `/wp/v2/media`.
3. Create or update `gallery_item` posts.
4. Set featured media and any gallery OCF image field if present.
5. Clear cache.
6. Verify the homepage/gallery page.

Gallery sections should render nothing when there are no valid published gallery items with usable media.

Edit Theme Structure

Use theme file edits only when OCF and WordPress content cannot do the job.

Examples:

- adding a component call in `front-page.php`
- creating `page-gallery.php`
- editing component markup in `components/*.php`
- adding focused styles in `assets/components/*.css`

Always read the current file first and preserve unrelated code.

Rollback Practice

Before editing, save enough state to undo:

- post IDs and previous native fields
- previous OCF field values
- previous file contents
- created media IDs
- created post IDs

After editing, report:

```text
Changed:
- Posts:
- OCF fields:
- Theme files:
- Media:
- Cache cleared:
Rollback notes:
```

Final Response Format

When done, tell the user:

- what changed
- what is still draft or unpublished
- what URL or page was affected
- whether cache was cleared
- whether you visually checked it
- any rollback notes