{
  "openapi": "3.1.0",
  "info": {
    "title": "1ClickWebsite API",
    "version": "2.0.0",
    "description": "Create complete V2 websites, generate Lead Gen mini-sites, manage white-label agency requests, and edit completed WordPress sites. Platform endpoints use a 1ClickWebsite bearer API key. Site Editing endpoints run against the generated site and use a WordPress username and application password."
  },
  "servers": [
    {
      "url": "https://www.1clickwebsite.ai",
      "description": "1ClickWebsite production API"
    }
  ],
  "tags": [
    {
      "name": "Site Creation",
      "description": "Create and monitor complete V2 WordPress website builds."
    },
    {
      "name": "Lead Gen",
      "description": "Create and manage Lead Gen V2 mini-site batches."
    },
    {
      "name": "White-label Agency",
      "description": "Optional agency request flow for workspace templates, approval, and agency-owned builds."
    },
    {
      "name": "Site Editing — OCF",
      "description": "Read and update the structured fields rendered by a completed V2 site."
    },
    {
      "name": "Site Editing — WordPress",
      "description": "Manage WordPress CMS records and post SEO on a completed V2 site."
    },
    {
      "name": "Resources",
      "description": "Machine-readable integration resources."
    }
  ],
  "paths": {
    "/api/templates": {
      "get": {
        "tags": ["Site Creation"],
        "summary": "List site templates",
        "description": "Returns the currently visible and provisionable V2 site templates. Anonymous requests receive the public catalog; send the same bearer API key used for site creation to include any templates available specifically to that account.",
        "operationId": "listSiteTemplates",
        "security": [{ "BearerAuth": [] }, {}],
        "responses": {
          "200": {
            "description": "Available site templates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/SiteTemplate" }
                },
                "example": [
                  {
                    "id": "lightning",
                    "templateId": "lightning",
                    "themeId": null,
                    "name": "Lightning",
                    "description": "A fast, flexible service-business website.",
                    "version": "2.0.0",
                    "hasServices": true,
                    "hasServiceAreas": true,
                    "featureImage": "https://example.com/lightning.png",
                    "previewUrl": "https://example.com/lightning"
                  }
                ]
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/provision": {
      "post": {
        "tags": ["Site Creation"],
        "summary": "Create a site",
        "description": "Queues a complete V2 WordPress website build. One accepted build uses one site credit. Call `GET /api/templates` first and submit an available `templateId` and optional `themeId`.",
        "operationId": "createSite",
        "security": [{ "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SiteCreateRequest" },
              "example": {
                "templateId": "lightning",
                "builderVersion": "v2",
                "businessName": "Austin Patio Pros",
                "industry": "Patio contractor",
                "email": "owner@example.com",
                "phone": "+15125550123",
                "address": "123 Main St, Austin, TX 78701",
                "addressLine1": "123 Main St",
                "addressCity": "Austin",
                "addressRegion": "TX",
                "addressPostalCode": "78701",
                "countryCode": "US",
                "hasPublicBusinessAddress": true,
                "customerModel": "travel_to_customers",
                "businessHoursMode": "open_24_hours",
                "services": ["Patio installation", "Outdoor kitchens"],
                "serviceAreas": ["Austin", "Round Rock"],
                "primaryColor": "#D23832",
                "backgroundTheme": "light",
                "primaryLanguage": "en"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Build accepted and queued",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SiteCreateAccepted" },
                "example": {
                  "slug": "c4b09c11-austin-patio-pros",
                  "siteId": "6ca4fd0f-1190-4df2-a27d-ad4088344cd2",
                  "previewUrl": null,
                  "statusUrl": "/api/provision/6ca4fd0f-1190-4df2-a27d-ad4088344cd2"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/provision/{siteId}": {
      "get": {
        "tags": ["Site Creation"],
        "summary": "Check a site build",
        "description": "Returns the current build state. Use the same API key that created the site and poll every 2–5 seconds until `complete` or `failed`.",
        "operationId": "getSiteStatus",
        "security": [{ "BearerAuth": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/SiteId" }
        ],
        "responses": {
          "200": {
            "description": "Current build status",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SiteStatus" },
                "example": {
                  "status": "complete",
                  "currentStep": "Site complete",
                  "progressPct": 100,
                  "previewUrl": "https://site-name.preview-domain.com",
                  "adminUrl": "https://site-name.preview-domain.com/wp-admin/",
                  "warnings": [],
                  "error": null,
                  "completedAt": "2026-08-09T19:27:01.456Z",
                  "creditRefunded": false
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/integrations/site-status": {
      "post": {
        "tags": ["Site Creation"],
        "summary": "Check site status from a workflow",
        "description": "POST wrapper for workflow products that cannot call the GET status endpoint. It uses the same API-key authentication and ownership check.",
        "operationId": "postSiteStatus",
        "security": [{ "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/WorkflowStatusRequest" },
              "example": { "siteId": "6ca4fd0f-1190-4df2-a27d-ad4088344cd2" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Workflow-friendly build status",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/WorkflowSiteStatus" },
                "example": {
                  "ok": true,
                  "siteId": "6ca4fd0f-1190-4df2-a27d-ad4088344cd2",
                  "statusUrl": "/api/provision/6ca4fd0f-1190-4df2-a27d-ad4088344cd2",
                  "status": "complete",
                  "progressPct": 100,
                  "previewUrl": "https://site-name.preview-domain.com",
                  "adminUrl": "https://site-name.preview-domain.com/wp-admin/",
                  "error": null
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/lead-gen/templates": {
      "get": {
        "tags": ["Lead Gen"],
        "summary": "List Lead Gen templates",
        "description": "Returns the active Lead Gen templates available to the authenticated account. Submit a returned `key` as `templateKey` when creating a batch.",
        "operationId": "listLeadGenTemplates",
        "security": [{ "BearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Available Lead Gen templates",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/LeadGenTemplateCatalogResponse" },
                "example": {
                  "ok": true,
                  "templates": [
                    {
                      "id": "44444444-4444-4444-8444-444444444444",
                      "key": "lightning",
                      "label": "Lightning",
                      "description": "A fast, polished Lead Gen treatment based on the OCF Lightning template.",
                      "version": "1.0.0",
                      "previewUrl": "/lead-gen/carlos-plumbing-demo?templateKey=lightning",
                      "thumbnailUrl": "/api/templates/lightning/assets/preview.png"
                    }
                  ]
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/lead-gen/batches": {
      "post": {
        "tags": ["Lead Gen"],
        "summary": "Create a batch",
        "description": "Creates a Lead Gen V2 batch and reserves credits. Standard accounts have a five-credit minimum per batch. Submit 1–500 business rows.",
        "operationId": "createLeadGenBatch",
        "security": [{ "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/LeadGenBatchCreateRequest" },
              "example": {
                "industry": "Roofing",
                "templateKey": "lightning",
                "primaryColor": "#0B1F3A",
                "backgroundTheme": "light",
                "logoSizePx": 96,
                "rows": [
                  {
                    "businessName": "RidgeLine Roofing",
                    "phone": "(555) 010-0199",
                    "address": "1480 Main St, Denver, CO 80202"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch created",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/LeadGenBatchCreateResponse" },
                "example": {
                  "ok": true,
                  "batchId": "24fc4b0b-d1e2-4320-b822-5bb39c4437bf",
                  "batch": {
                    "id": "24fc4b0b-d1e2-4320-b822-5bb39c4437bf",
                    "status": "pending",
                    "industry": "Roofing",
                    "template_key": "lightning",
                    "total_count": 1,
                    "credits_reserved": 5
                  },
                  "creditsReserved": 5,
                  "creditsRemaining": 42
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/Conflict" }
        }
      },
      "get": {
        "tags": ["Lead Gen"],
        "summary": "List batches",
        "description": "Returns recent Lead Gen V2 batches for the authenticated account.",
        "operationId": "listLeadGenBatches",
        "security": [{ "BearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Recent batches",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "batches": { "type": "array", "items": { "$ref": "#/components/schemas/LeadGenBatch" } }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/lead-gen/batches/{batchId}": {
      "get": {
        "tags": ["Lead Gen"],
        "summary": "Get a batch",
        "description": "Returns a batch and its items. Completed items include the generated public URL and saved site state.",
        "operationId": "getLeadGenBatch",
        "security": [{ "BearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/BatchId" }],
        "responses": {
          "200": {
            "description": "Batch with generated items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "batch": { "$ref": "#/components/schemas/LeadGenBatch" },
                    "items": { "type": "array", "items": { "$ref": "#/components/schemas/LeadGenItem" } }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "patch": {
        "tags": ["Lead Gen"],
        "summary": "Update batch settings",
        "description": "Updates shared design defaults. Rows with individual overrides retain those overrides.",
        "operationId": "updateLeadGenBatch",
        "security": [{ "BearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/BatchId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/LeadGenBatchUpdateRequest" },
              "example": {
                "primaryColor": "#173B57",
                "backgroundTheme": "dark",
                "logoSizePx": 104
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch settings updated",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/LeadGenBatchUpdateResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/lead-gen/batches/{batchId}/process": {
      "post": {
        "tags": ["Lead Gen"],
        "summary": "Confirm a batch is queued",
        "description": "Compatibility endpoint that confirms the dedicated Lead Gen worker owns processing for the batch.",
        "operationId": "processLeadGenBatch",
        "security": [{ "BearerAuth": [] }],
        "parameters": [{ "$ref": "#/components/parameters/BatchId" }],
        "responses": {
          "200": {
            "description": "Batch queued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "batchId": { "type": "string", "format": "uuid" },
                    "queued": { "type": "boolean" },
                    "status": { "type": "string" },
                    "message": { "type": "string" }
                  }
                },
                "example": {
                  "ok": true,
                  "batchId": "24fc4b0b-d1e2-4320-b822-5bb39c4437bf",
                  "queued": true,
                  "status": "queued",
                  "message": "The dedicated Lead Gen worker owns batch processing."
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agency/v1/templates": {
      "get": {
        "tags": ["White-label Agency"],
        "summary": "Get agency templates",
        "description": "Returns templates and optional themes available to a white-label workspace.",
        "operationId": "getAgencyTemplates",
        "security": [{ "BearerAuth": [] }],
        "responses": {
          "200": {
            "description": "Available templates",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/agency/v1/site-requests": {
      "post": {
        "tags": ["White-label Agency"],
        "summary": "Create an agency site request",
        "description": "Creates an agency-owned site request. With auto approval enabled, the build is queued immediately; otherwise it waits for approval.",
        "operationId": "createAgencySiteRequest",
        "security": [{ "BearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AgencySiteRequest" },
              "example": {
                "templateId": "lightning",
                "autoApprove": true,
                "businessName": "Austin Patio Pros",
                "industry": "Patio contractor",
                "email": "owner@example.com",
                "services": ["Patio installation", "Outdoor kitchens"],
                "serviceAreas": ["Austin", "Round Rock"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agency request created",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/agency/v1/site-requests/{requestId}": {
      "get": {
        "tags": ["White-label Agency"],
        "summary": "Check an agency site request",
        "description": "Returns approval status, build status, public site URL, and any error for an agency-owned request.",
        "operationId": "getAgencySiteRequest",
        "security": [{ "BearerAuth": [] }],
        "parameters": [
          {
            "name": "requestId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Agency request status",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/wp-json/ocf/v1/schema": {
      "servers": [{ "url": "https://{siteHost}", "description": "Generated or connected WordPress site", "variables": { "siteHost": { "default": "your-site.com", "description": "Generated preview hostname or connected live domain" } } }],
      "get": {
        "tags": ["Site Editing — OCF"],
        "summary": "Read the active field schema",
        "description": "Returns the active field names, types, scopes, and content groups. Read it before building or changing an editing integration.",
        "operationId": "readOcfSchema",
        "security": [{ "WordPressBasic": [] }],
        "responses": {
          "200": {
            "description": "Active OCF schema",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          },
          "401": { "$ref": "#/components/responses/WordPressUnauthorized" }
        }
      }
    },
    "/wp-json/ocf/v1/state": {
      "servers": [{ "url": "https://{siteHost}", "description": "Generated or connected WordPress site", "variables": { "siteHost": { "default": "your-site.com", "description": "Generated preview hostname or connected live domain" } } }],
      "get": {
        "tags": ["Site Editing — OCF"],
        "summary": "Read current field values",
        "description": "Reads site-scoped state, or includes one item’s post-scoped fields when `post_id` is provided.",
        "operationId": "readOcfState",
        "security": [{ "WordPressBasic": [] }],
        "parameters": [
          {
            "name": "post_id",
            "in": "query",
            "required": false,
            "description": "WordPress post ID for post-scoped fields.",
            "schema": { "type": "integer", "minimum": 1 }
          }
        ],
        "responses": {
          "200": {
            "description": "Current OCF state",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OcfStateResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/WordPressUnauthorized" }
        }
      },
      "post": {
        "tags": ["Site Editing — OCF"],
        "summary": "Update rendered field values",
        "description": "Validates and saves site-scoped or post-scoped fields rendered by the V2 template.",
        "operationId": "updateOcfState",
        "security": [{ "WordPressBasic": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/OcfStateUpdate" },
              "example": {
                "post": {
                  "post_id": 52,
                  "fields": {
                    "faq_question": "Do you offer free inspections?",
                    "faq_answer": "Yes. Contact our team to schedule one."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "State saved",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OcfStateResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/WordPressUnauthorized" }
        }
      }
    },
    "/wp-json/ocf/v1/validate": {
      "servers": [{ "url": "https://{siteHost}", "description": "Generated or connected WordPress site", "variables": { "siteHost": { "default": "your-site.com", "description": "Generated preview hostname or connected live domain" } } }],
      "post": {
        "tags": ["Site Editing — OCF"],
        "summary": "Validate an update",
        "description": "Checks proposed OCF values against the active schema without saving them.",
        "operationId": "validateOcfState",
        "security": [{ "WordPressBasic": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/OcfStateUpdate" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "errors": { "type": "array", "items": { "type": "string" } }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/WordPressUnauthorized" }
        }
      }
    },
    "/wp-json/ocf/v1/cache/clear": {
      "servers": [{ "url": "https://{siteHost}", "description": "Generated or connected WordPress site", "variables": { "siteHost": { "default": "your-site.com", "description": "Generated preview hostname or connected live domain" } } }],
      "post": {
        "tags": ["Site Editing — OCF"],
        "summary": "Clear the page cache",
        "description": "Clears page and object caches. OCF state writes already clear cache automatically; use this after workflows that also modify native WordPress records or media.",
        "operationId": "clearSiteCache",
        "security": [{ "WordPressBasic": [] }],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": { "reason": { "type": "string" } }
              },
              "example": { "reason": "api_update" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cache cleared",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "cleared": { "type": "boolean" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/WordPressUnauthorized" }
        }
      }
    },
    "/wp-json/wp/v2/{postType}": {
      "servers": [{ "url": "https://{siteHost}", "description": "Generated or connected WordPress site", "variables": { "siteHost": { "default": "your-site.com", "description": "Generated preview hostname or connected live domain" } } }],
      "get": {
        "tags": ["Site Editing — WordPress"],
        "summary": "List CMS records",
        "description": "Lists records for a supported custom post type such as FAQs, services, service areas, reviews, gallery items, or locations.",
        "operationId": "listCmsRecords",
        "security": [{ "WordPressBasic": [] }],
        "parameters": [{ "$ref": "#/components/parameters/PostType" }],
        "responses": {
          "200": {
            "description": "CMS records",
            "content": {
              "application/json": {
                "schema": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
              }
            }
          },
          "401": { "$ref": "#/components/responses/WordPressUnauthorized" }
        }
      },
      "post": {
        "tags": ["Site Editing — WordPress"],
        "summary": "Create a CMS record",
        "description": "Creates and optionally publishes a supported WordPress CMS record. Save its visible template fields through the OCF state endpoint using the returned post ID.",
        "operationId": "createCmsRecord",
        "security": [{ "WordPressBasic": [] }],
        "parameters": [{ "$ref": "#/components/parameters/PostType" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/WordPressRecordRequest" },
              "example": {
                "title": "Do you offer free inspections?",
                "status": "publish"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "CMS record created",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/WordPressUnauthorized" }
        }
      }
    },
    "/wp-json/ocf/v1/posts/{postId}/seo": {
      "servers": [{ "url": "https://{siteHost}", "description": "Generated or connected WordPress site", "variables": { "siteHost": { "default": "your-site.com", "description": "Generated preview hostname or connected live domain" } } }],
      "patch": {
        "tags": ["Site Editing — WordPress"],
        "summary": "Update post SEO",
        "description": "Updates SEO title, meta description, canonical URL, and noindex overrides independently from visible OCF content.",
        "operationId": "updatePostSeo",
        "security": [{ "WordPressBasic": [] }],
        "parameters": [{ "$ref": "#/components/parameters/PostId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SeoUpdateRequest" },
              "example": {
                "title": "Roof Repair in Austin, TX",
                "description": "Local roof repair and storm damage help."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SEO overrides saved",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/WordPressUnauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/ai-agent-guide": {
      "get": {
        "tags": ["Resources"],
        "summary": "Get the AI agent guide",
        "description": "Returns the machine-readable guide for agents that create, generate, and edit 1ClickWebsite sites.",
        "operationId": "getAiAgentGuide",
        "security": [],
        "responses": {
          "200": {
            "description": "Machine-readable integration guide",
            "content": {
              "text/markdown": { "schema": { "type": "string" } },
              "text/html": { "schema": { "type": "string" } }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "1ClickWebsite API key",
        "description": "Account keys begin with `lgen_`; white-label agency keys begin with `1cw_agency_`."
      },
      "WordPressBasic": {
        "type": "http",
        "scheme": "basic",
        "description": "WordPress username and application password. Remove display spaces from the application password."
      }
    },
    "parameters": {
      "SiteId": {
        "name": "siteId",
        "in": "path",
        "required": true,
        "description": "Site build identifier returned by the create endpoint.",
        "schema": { "type": "string", "format": "uuid" }
      },
      "BatchId": {
        "name": "batchId",
        "in": "path",
        "required": true,
        "description": "Lead Gen batch identifier.",
        "schema": { "type": "string", "format": "uuid" }
      },
      "PostId": {
        "name": "postId",
        "in": "path",
        "required": true,
        "description": "WordPress post ID.",
        "schema": { "type": "integer", "minimum": 1 }
      },
      "PostType": {
        "name": "postType",
        "in": "path",
        "required": true,
        "description": "WordPress REST base, for example `faq_item`, `service`, `service_area`, `review`, `gallery_item`, or `location`.",
        "schema": {
          "type": "string",
          "examples": ["faq_item", "service", "service_area", "review", "gallery_item", "location"]
        }
      }
    },
    "schemas": {
      "SiteTemplate": {
        "type": "object",
        "required": ["id", "templateId", "name", "description", "hasServices", "hasServiceAreas"],
        "properties": {
          "id": { "type": "string", "description": "Unique template/theme selection identifier." },
          "templateId": { "type": "string", "description": "Value to send as `templateId` when creating a site." },
          "themeId": { "type": ["string", "null"], "description": "Optional value to send as `themeId` when creating a site." },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "version": { "type": ["string", "null"] },
          "hasServices": { "type": "boolean" },
          "hasServiceAreas": { "type": "boolean" },
          "featureImage": { "type": ["string", "null"], "format": "uri-reference" },
          "previewUrl": { "type": ["string", "null"], "format": "uri-reference" }
        },
        "additionalProperties": false
      },
      "SiteCreateRequest": {
        "type": "object",
        "required": ["templateId", "businessName"],
        "properties": {
          "templateId": { "type": "string", "description": "Template ID returned by `GET /api/templates`." },
          "themeId": { "type": "string", "description": "Optional theme ID returned by `GET /api/templates`." },
          "builderVersion": { "type": "string", "enum": ["v2"], "default": "v2" },
          "businessName": { "type": "string", "minLength": 1 },
          "primaryLanguage": { "type": "string", "enum": ["en", "es", "fr", "de", "it", "ro", "tr"], "default": "en" },
          "industry": { "type": "string" },
          "email": { "type": "string", "format": "email" },
          "phone": { "type": "string" },
          "address": { "type": "string", "description": "Legacy combined public address. Supported for compatibility; structured fields are preferred." },
          "addressLine1": { "type": "string", "description": "Public street address. Omit when `hasPublicBusinessAddress` is false." },
          "addressLine2": { "type": "string", "description": "Optional suite, unit, building, or floor." },
          "addressCity": { "type": "string", "description": "City or locality. May be supplied without a street address for service-area or online businesses." },
          "addressRegion": { "type": "string", "description": "State, province, or region." },
          "addressPostalCode": { "type": "string", "description": "Postal code. Omit when `hasPublicBusinessAddress` is false." },
          "countryCode": { "type": "string", "pattern": "^[A-Za-z]{2}$", "default": "US", "description": "Two-letter ISO country code." },
          "hasPublicBusinessAddress": { "type": "boolean", "default": true, "description": "When false, the street address and postal code are discarded and do not appear on the generated site. City, region, and country may still anchor service-area content." },
          "googlePlaceId": { "type": "string" },
          "businessWebsite": { "type": "string", "format": "uri" },
          "aboutBusiness": { "type": "string" },
          "businessHoursMode": { "type": "string", "enum": ["weekly", "open_24_hours", "do_not_display"], "description": "Display behavior for the main business hours. If omitted, a supplied businessHours value implies weekly; otherwise hours are hidden." },
          "businessHours": { "type": "string", "description": "Weekly schedule as a JSON-encoded string or supported plain text. Used only with businessHoursMode=weekly." },
          "customerModel": { "type": "string", "enum": ["visit_business", "travel_to_customers", "hybrid", "remote_online"], "default": "travel_to_customers", "description": "How customers interact with the business. visit_business and hybrid require hasPublicBusinessAddress=true." },
          "services": { "type": "array", "items": { "type": "string" } },
          "serviceAreas": { "type": "array", "items": { "type": "string" } },
          "locations": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["name"],
              "properties": {
                "name": { "type": "string" },
                "address": { "type": "string" },
                "phone": { "type": "string" },
                "email": { "type": "string", "format": "email" },
                "hours": { "type": "string", "description": "Weekly schedule as a JSON-encoded string or supported plain text." },
                "hoursMode": { "type": "string", "enum": ["weekly", "open_24_hours", "do_not_display"], "description": "Display behavior for this location's hours." },
                "mapUrl": { "type": "string", "format": "uri" },
                "description": { "type": "string" },
                "content": { "type": "string" }
              },
              "additionalProperties": false
            }
          },
          "logoUrl": { "type": "string", "format": "uri" },
          "skipImages": { "type": "boolean" },
          "createServicePages": { "type": "boolean", "default": true },
          "createServiceAreaPages": { "type": "boolean", "default": true },
          "createLocationPages": { "type": "boolean", "default": true },
          "primaryColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
          "secondaryColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
          "backgroundTheme": { "type": "string", "enum": ["light", "dark"] },
          "headingFont": { "type": "string" },
          "bodyFont": { "type": "string" }
        },
        "additionalProperties": true
      },
      "SiteCreateAccepted": {
        "type": "object",
        "required": ["slug", "siteId", "statusUrl"],
        "properties": {
          "slug": { "type": "string" },
          "siteId": { "type": "string", "format": "uuid" },
          "previewUrl": { "type": ["string", "null"], "format": "uri" },
          "statusUrl": { "type": "string" }
        }
      },
      "SiteStatus": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "enum": ["queued", "provisioning", "live", "enhancing", "complete", "failed"] },
          "currentStep": { "type": ["string", "null"] },
          "progressPct": { "type": "integer", "minimum": 0, "maximum": 100 },
          "previewUrl": { "type": ["string", "null"], "format": "uri" },
          "adminUrl": { "type": ["string", "null"], "format": "uri" },
          "warnings": { "type": "array", "items": { "type": "string" } },
          "error": { "type": ["string", "null"] },
          "liveAt": { "type": ["string", "null"], "format": "date-time" },
          "enhancingStartedAt": { "type": ["string", "null"], "format": "date-time" },
          "completedAt": { "type": ["string", "null"], "format": "date-time" },
          "enhancementError": { "type": ["string", "null"] },
          "creditRefunded": { "type": "boolean" }
        }
      },
      "WorkflowStatusRequest": {
        "type": "object",
        "required": ["siteId"],
        "properties": {
          "siteId": { "type": "string", "format": "uuid" }
        },
        "additionalProperties": false
      },
      "WorkflowSiteStatus": {
        "allOf": [
          { "$ref": "#/components/schemas/SiteStatus" },
          {
            "type": "object",
            "required": ["ok", "siteId", "statusUrl"],
            "properties": {
              "ok": { "type": "boolean" },
              "siteId": { "type": "string", "format": "uuid" },
              "statusUrl": { "type": "string" }
            }
          }
        ]
      },
      "LeadGenRow": {
        "type": "object",
        "properties": {
          "businessName": { "type": "string" },
          "business_name": { "type": "string", "deprecated": true },
          "phone": { "type": "string" },
          "email": { "type": "string" },
          "address": { "type": "string" },
          "industry": { "type": "string" },
          "logoUrl": { "type": "string", "format": "uri" },
          "logo_url": { "type": "string", "format": "uri" },
          "primaryColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
          "primary_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
          "backgroundTheme": { "type": "string", "enum": ["light", "dark"] },
          "background_theme": { "type": "string", "enum": ["light", "dark"] },
          "contactMode": { "type": "string", "enum": ["form", "scheduler", "schedule", "booking", "survey"] },
          "contact_mode": { "type": "string", "enum": ["form", "scheduler", "schedule", "booking", "survey"] },
          "google_cid": { "type": "string", "deprecated": true },
          "google_place_id": { "type": "string", "deprecated": true }
        },
        "anyOf": [
          { "required": ["businessName"] },
          { "required": ["business_name"] },
          { "required": ["google_cid"] },
          { "required": ["google_place_id"] }
        ]
      },
      "LeadGenTemplate": {
        "type": "object",
        "required": ["id", "key", "label", "description", "version"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "key": { "type": "string", "description": "Value to send as `templateKey` when creating a Lead Gen batch." },
          "label": { "type": "string" },
          "description": { "type": "string" },
          "version": { "type": "string" },
          "previewUrl": { "type": ["string", "null"], "format": "uri-reference" },
          "thumbnailUrl": { "type": ["string", "null"], "format": "uri-reference" }
        },
        "additionalProperties": false
      },
      "LeadGenTemplateCatalogResponse": {
        "type": "object",
        "required": ["ok", "templates"],
        "properties": {
          "ok": { "type": "boolean" },
          "templates": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/LeadGenTemplate" }
          }
        },
        "additionalProperties": false
      },
      "LeadGenBatchCreateRequest": {
        "type": "object",
        "required": ["rows"],
        "properties": {
          "industry": { "type": "string", "default": "Home Services" },
          "rows": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/LeadGenRow" } },
          "templateKey": { "type": "string", "default": "lightning", "description": "Template key returned by `GET /api/lead-gen/templates`." },
          "template_key": { "type": "string", "deprecated": true, "description": "Snake-case alias of `templateKey`." },
          "primaryColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
          "primary_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
          "backgroundTheme": { "type": "string", "enum": ["light", "dark"] },
          "background_theme": { "type": "string", "enum": ["light", "dark"] },
          "contactMode": { "type": "string", "enum": ["form", "scheduler", "schedule", "booking", "survey"] },
          "contact_mode": { "type": "string", "enum": ["form", "scheduler", "schedule", "booking", "survey"] },
          "logoSizePx": { "type": "integer", "minimum": 48, "maximum": 160, "default": 88 },
          "logo_size_px": { "type": "integer", "minimum": 48, "maximum": 160 }
        }
      },
      "LeadGenBatch": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "status": { "type": "string" },
          "industry": { "type": "string" },
          "template_key": { "type": "string" },
          "total_count": { "type": "integer" },
          "credits_reserved": { "type": "integer" }
        },
        "additionalProperties": true
      },
      "LeadGenBatchCreateResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "batchId": { "type": "string", "format": "uuid" },
          "batch": { "$ref": "#/components/schemas/LeadGenBatch" },
          "creditsReserved": { "type": "integer" },
          "creditsRemaining": { "type": "integer" }
        }
      },
      "LeadGenBatchUpdateRequest": {
        "type": "object",
        "minProperties": 1,
        "properties": {
          "primaryColor": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
          "primary_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
          "backgroundTheme": { "type": "string", "enum": ["light", "dark"] },
          "background_theme": { "type": "string", "enum": ["light", "dark"] },
          "logoSizePx": { "type": "integer", "minimum": 48, "maximum": 160 },
          "logo_size_px": { "type": "integer", "minimum": 48, "maximum": 160 }
        }
      },
      "LeadGenBatchUpdateResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "batchId": { "type": "string", "format": "uuid" },
          "primaryColor": { "type": ["string", "null"] },
          "backgroundTheme": { "type": ["string", "null"] },
          "logoSizePx": { "type": ["integer", "null"] },
          "updatedCount": { "type": "integer" },
          "logoUpdatedCount": { "type": "integer" },
          "logoSkippedCount": { "type": "integer" },
          "colorUpdatedCount": { "type": "integer" },
          "colorSkippedCount": { "type": "integer" },
          "backgroundUpdatedCount": { "type": "integer" },
          "backgroundSkippedCount": { "type": "integer" }
        }
      },
      "LeadGenItem": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "status": { "type": "string" },
          "business_name": { "type": "string" },
          "public_url": { "type": ["string", "null"], "format": "uri" },
          "primary_color": { "type": ["string", "null"] },
          "logo_url": { "type": ["string", "null"], "format": "uri" },
          "template_key": { "type": "string" }
        },
        "additionalProperties": true
      },
      "AgencySiteRequest": {
        "allOf": [
          { "$ref": "#/components/schemas/SiteCreateRequest" },
          {
            "type": "object",
            "required": ["email"],
            "properties": {
              "autoApprove": { "type": "boolean" },
              "themeId": { "type": "string" }
            }
          }
        ]
      },
      "OcfStateUpdate": {
        "type": "object",
        "properties": {
          "site": {
            "type": "object",
            "additionalProperties": true,
            "description": "Site-scoped OCF fields."
          },
          "post": {
            "type": "object",
            "required": ["post_id", "fields"],
            "properties": {
              "post_id": { "type": "integer", "minimum": 1 },
              "fields": { "type": "object", "additionalProperties": true }
            }
          }
        },
        "anyOf": [{ "required": ["site"] }, { "required": ["post"] }]
      },
      "OcfStateResponse": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean" },
          "state_version": { "type": "integer" },
          "fields": { "type": "object", "additionalProperties": true },
          "post": { "type": "object", "additionalProperties": true }
        },
        "additionalProperties": true
      },
      "WordPressRecordRequest": {
        "type": "object",
        "required": ["title"],
        "properties": {
          "title": { "type": "string" },
          "content": { "type": "string" },
          "slug": { "type": "string" },
          "status": { "type": "string", "enum": ["draft", "publish", "pending", "private"] },
          "menu_order": { "type": "integer" },
          "featured_media": { "type": "integer" }
        },
        "additionalProperties": true
      },
      "SeoUpdateRequest": {
        "type": "object",
        "minProperties": 1,
        "properties": {
          "title": { "type": "string" },
          "description": { "type": "string" },
          "canonical": { "type": "string", "format": "uri" },
          "noindex": { "type": "boolean" }
        },
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "properties": {
          "ok": { "type": "boolean", "const": false },
          "error": { "type": "string" },
          "details": {
            "oneOf": [
              { "type": "string" },
              { "type": "array", "items": { "type": "string" } },
              { "type": "object", "additionalProperties": true }
            ]
          }
        },
        "additionalProperties": true
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid or missing request data",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unauthorized": {
        "description": "Missing, invalid, or revoked API key",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "WordPressUnauthorized": {
        "description": "Invalid WordPress username or application password",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Forbidden": {
        "description": "Insufficient access, credits, or template availability",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "NotFound": {
        "description": "Resource not found or not owned by the authenticated account",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Conflict": {
        "description": "Retryable credit reservation conflict",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unavailable": {
        "description": "Site generation is temporarily in maintenance mode",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  }
}