---
name: oneclickwebsite-api
description: Create complete 1ClickWebsite WordPress sites, generate Lead Gen mini-sites, check build status, and edit finished V2 sites—including Slim SEO metadata—through the 1ClickWebsite, WordPress REST, and OCF APIs. Use when an agent needs to create, monitor, or edit a 1ClickWebsite site from Codex, Claude Code, Cursor, or another API-capable tool.
---

# 1ClickWebsite API Skill

Version: 2.1.0
Last updated: August 10, 2026

Use these instructions to choose the correct workflow:

1. Use **Full Site Creation** to create a complete V2 WordPress website. This is available on every 1ClickWebsite plan and uses one normal site credit.
2. Use **Lead Gen** to create lightweight prospect mini-sites in batches. This uses Lead Gen credits on standard accounts.
3. Use **Site Editing** after a V2 WordPress site exists and the user wants to change its content, design, pages, or media.

Official human-readable references:

- Full Site Creation: `https://www.1clickwebsite.ai/docs/site-creation-api`
- Lead Gen: `https://www.1clickwebsite.ai/docs/lead-gen-api`
- Copyable version of this skill: `https://www.1clickwebsite.ai/ai-agent-guide`

## Shared API Rules

- Use `https://www.1clickwebsite.ai` as the base URL for standard accounts. The bare domain redirects to `www`, so API clients should use the canonical hostname directly rather than relying on redirect handling.
- Send account API keys as `Authorization: Bearer YOUR_API_KEY`.
- Existing `lgen_...` account keys work for both Full Site Creation and Lead Gen.
- White-label agency keys begin with `1cw_agency_...` and can use agency-specific routes documented in the full Site Creation reference.
- Treat every key as a password. Never print it, commit it, place it in browser code, or include it in a public file.
- The raw key is shown once. 1ClickWebsite stores a SHA-256 hash and a short preview, not the raw key.
- A `401` response means the key is missing, invalid, or revoked.
- Keep resource IDs from create responses; use them to poll status with the same key.

# 1. Full Site Creation

Use this flow with a normal 1ClickWebsite account API key on any plan.

## Create A Complete Site

```http
POST https://www.1clickwebsite.ai/api/provision
```

Required JSON fields:

- `templateId`: use `lightning` for the current public V2 template.
- `businessName`: the business name used on the site.

Common optional fields include `industry`, `email`, `phone`, `address`, `businessWebsite`, `aboutBusiness`, `businessHours`, `services`, `serviceAreas`, `locations`, `logoUrl`, `primaryColor`, `secondaryColor`, `backgroundTheme`, `headingFont`, `bodyFont`, `primaryLanguage`, `skipImages`, `createServicePages`, `createServiceAreaPages`, and `createLocationPages`.

Supported `primaryLanguage` values are `en`, `es`, `fr`, `de`, `it`, `ro`, and `tr`. English is the default.

Example:

```bash
curl -X POST "https://www.1clickwebsite.ai/api/provision" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "lightning",
    "builderVersion": "v2",
    "businessName": "Austin Patio Pros",
    "industry": "Patio contractor",
    "email": "owner@example.com",
    "phone": "+15125550123",
    "address": "Austin, Texas",
    "aboutBusiness": "Austin Patio Pros builds patios, outdoor kitchens, and stone walkways.",
    "services": ["Patio installation", "Outdoor kitchens", "Stone walkways"],
    "serviceAreas": ["Austin", "Round Rock", "Cedar Park"],
    "primaryColor": "#D23832",
    "backgroundTheme": "light",
    "primaryLanguage": "en"
  }'
```

A successful request returns `202 Accepted`:

```json
{
  "slug": "c4b09c11-austin-patio-pros",
  "siteId": "6ca4fd0f-1190-4df2-a27d-ad4088344cd2",
  "previewUrl": null,
  "statusUrl": "/api/provision/6ca4fd0f-1190-4df2-a27d-ad4088344cd2"
}
```

Save `siteId` and `statusUrl`.

## Check A Full Site Build

```http
GET https://www.1clickwebsite.ai/api/provision/{siteId}
```

Send the same API key used to create the site:

```bash
curl "https://www.1clickwebsite.ai/api/provision/SITE_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Poll every 2 to 5 seconds. Stop when `status` is `complete` or `failed`.

Common states are `queued`, `provisioning`, `live`, `enhancing`, `complete`, and `failed`. A site can be reachable at `previewUrl` before it is complete, so wait for `complete` before reporting final success.

Important response fields:

- `currentStep` and `progressPct`: current worker progress.
- `previewUrl`: public website URL once assigned.
- `adminUrl`: WordPress admin URL once available.
- `warnings`, `error`, and `enhancementError`: build problems.
- `completedAt`: final completion time.
- `creditRefunded`: whether the failed build credit was returned.

Credit rules:

- Validation runs before charging a credit.
- One accepted standard build uses one normal site credit.
- A failed queued build normally refunds the credit exactly once.
- A `403` can mean the account has no site credits left.

Never retry a `202 Accepted` create request merely because polling is slow; that would create and charge for another site. Continue polling the returned site ID.

# 2. Lead Gen

Lead Gen creates lightweight prospect mini-sites in batches. Use it for previews and outreach, not as a replacement for a complete WordPress site.

## Create A Lead Gen Batch

```http
POST https://www.1clickwebsite.ai/api/lead-gen/batches
```

Use top-level batch defaults and send 1 to 500 rows. Each new row should include `businessName` or `business_name`.

```bash
curl -X POST "https://www.1clickwebsite.ai/api/lead-gen/batches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": "Roofing",
    "templateKey": "lightning",
    "primaryColor": "#0B1F3A",
    "backgroundTheme": "light",
    "rows": [
      {
        "businessName": "RidgeLine Roofing",
        "phone": "(555) 010-0199",
        "email": "hello@example.com",
        "address": "Denver, Colorado"
      }
    ]
  }'
```

A successful response includes `batchId`, `creditsReserved`, and `creditsRemaining`. Save `batchId`.

Standard accounts reserve at least five Lead Gen credits per batch: `max(5, number of rows)`. If batch creation fails, the reserved credits are returned. Agency keys use the agency's configured OpenAI key and do not spend standard user Lead Gen credits.

## Check Or List Lead Gen Batches

```http
GET https://www.1clickwebsite.ai/api/lead-gen/batches/{batchId}
GET https://www.1clickwebsite.ai/api/lead-gen/batches
```

The single-batch response includes the batch and its items. Completed items include `public_url` and saved site state.

The compatibility route below reports whether the worker owns and is processing the queue; it does not start a second build:

```http
POST https://www.1clickwebsite.ai/api/lead-gen/batches/{batchId}/process
```

## Update Lead Gen Batch Design

Use `PATCH /api/lead-gen/batches/{batchId}` to change one or more batch defaults:

- `primaryColor` or `primary_color`
- `backgroundTheme` or `background_theme`
- `logoSizePx` or `logo_size_px`, from 48 to 160

Rows with their own override keep that override. Do not send both camelCase and snake_case versions of the same field.

For full Lead Gen field details and response shapes, read `https://www.1clickwebsite.ai/docs/lead-gen-api`.

# 3. Site Editing

Use the rest of this guide to edit an existing 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/delete active theme files | `GET/PUT/DELETE /ocf/v1/files/{path}` |
| Read SEO metadata for a post | `GET /ocf/v1/posts/{post_id}/seo` |
| Update SEO metadata for a post | `POST/PUT/PATCH /ocf/v1/posts/{post_id}/seo` |
| Clear page cache | `POST /ocf/v1/cache/clear` |

Additional authenticated OCF routes:

| Need | Route |
| --- | --- |
| Read or save CAPTCHA settings | `GET/POST /ocf/v1/captcha/settings` |
| Read or save form confirmation settings | `GET/POST /ocf/v1/form-confirmation/settings` |
| Read package status or the live package | `GET /ocf/v1/package/status`, `GET /ocf/v1/package` |
| Patch package state | `POST /ocf/v1/package/state` |
| Read or write a package file | `GET/PUT /ocf/v1/package/file` |
| List, restore, or pin package revisions | `GET /ocf/v1/package/revisions`, `POST /ocf/v1/package/restore`, `POST /ocf/v1/package/pin` |

`POST /ocf/v1/lead` is the public contact-form submission route. `/ocf/v1/provision/bootstrap` and `/ocf/v1/provision/enrich` are provisioning routes; do not call them for normal site editing. `POST /ocf/v1/schema` replaces the active schema and is also not a normal content-editing operation.

All editing routes require a WordPress user with `manage_options`. The public lead route is the exception.

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.
- `get_post_seo` -> call `GET /ocf/v1/posts/{post_id}/seo`.
- `set_post_seo` -> read current SEO first, then call `POST`, `PUT`, or `PATCH /ocf/v1/posts/{post_id}/seo` with only the fields that should change.
- `list_media`, `upload_media` -> use `/wp/v2/media`.
- `capture_screenshot` -> use your own browser/screenshot tool when the request or reported problem requires checking the rendered page; do not run it routinely after every edit.
- `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.

## Slim SEO Metadata

OCF 0.8.0 and newer expose Slim SEO overrides for WordPress posts, pages, services, service areas, and other public content items:

```text
GET /wp-json/ocf/v1/posts/123/seo
POST /wp-json/ocf/v1/posts/123/seo
```

The response separates search metadata from the visible WordPress title and body:

```json
{
  "ok": true,
  "post": {
    "id": 123,
    "type": "page",
    "title": "Visible page title",
    "url": "https://example.com/example/"
  },
  "seo": {
    "title": "Search result title",
    "description": "Search result description.",
    "canonical": null,
    "noindex": null
  }
}
```

Update only the fields the user asked to change:

```json
{
  "title": "Austin Patio Installation | Austin Patio Pros",
  "description": "Custom patios, outdoor kitchens, and stone walkways in Austin."
}
```

Supported fields are `title`, `description`, `canonical`, and `noindex`. Omitted fields are preserved. Send `null` or an empty string to clear `title`, `description`, or `canonical`; send `null` to clear the `noindex` override. A canonical value must be a valid URL.

Always read the current SEO object before writing so unrelated overrides can be preserved and rolled back. After writing:

1. Read the SEO object again and compare every requested field.
2. Call `POST /ocf/v1/cache/clear` with a short reason such as `seo_updated`.
3. Inspect the public page source to confirm the rendered `<title>`, meta description, canonical link, or robots directive.

The SEO write route updates WordPress metadata but does not purge an already-cached public page by itself. Do not report the visible metadata as updated until the cache has been cleared and the page source has been checked.

If this route returns `rest_no_route` or HTTP 404, the site needs OCF 0.8.0 or newer. Do not fall back to editing Slim SEO's private post-meta format through WordPress REST.

## 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.
- `active-blueprint.json`: live page and region order on template version 2.0.0 or newer.
- `front-page.php`: homepage section order and component calls on legacy template versions; a safe fallback only on version 2 sites.
- `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 Editing 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 to `active-blueprint.json` on version 2 sites, or to the matching root route file on legacy sites
- 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