Using AI Agents to Manage Your Capuzzella Site via the API

Capuzzella exposes a REST API that lets you list, read, create, edit, publish, and schedule pages programmatically. Any tool that can make HTTP requests can manage your site. AI agents like OpenClaw take this a step further: you describe what you want in plain English, and the agent translates your intent into API calls. Here's how it works.

What the API Can Do

The Capuzzella API covers the full page lifecycle. Every endpoint uses JSON over HTTP and authenticates with a Bearer token.

Page Management

List all pages — GET /api/pages returns every draft page path on your site.
Read a page — GET /api/pages/about.html returns the full HTML source.
Create or update a page — PUT /api/pages/services.html with { "html": "<!DOCTYPE html>..." } creates a new page or overwrites an existing one.
Delete a page — DELETE /api/pages/about.html removes it from drafts and published.

Publishing

Publish a single page — POST /publish/index.html copies the draft to the public directory.
Publish everything — POST /publish/ publishes all drafts at once.
Unpublish — DELETE /publish/about.html removes a page from the public site.
Check status — GET /publish/status/index.html tells you whether a page is published and whether the draft has unpublished changes.

Scheduled Publishing

Schedule a future publish — POST /publish/schedule with { "pagePath": "blog/post.html", "publishAt": "2026-04-01T09:00:00Z" } queues a page to go live at a specific time.
List pending schedules — GET /publish/schedule?status=pending
Cancel a schedule — DELETE /publish/schedule/3

AI Chat

Ask AI to edit a page — POST /api/chat with { "message": "Add a testimonials section", "pagePath": "index.html" } sends a natural-language instruction to the built-in AI editor. Pass a conversationId to continue a multi-turn conversation.

Uploads & Components

Upload files — POST /api/upload accepts images, videos, and PDFs via multipart form data.
List uploads — GET /api/uploads
Load design components — POST /api/components/load with { "names": ["hero", "pricing"] } returns the HTML for reusable design system components you can drop into pages.

Authentication

Every request requires an API key passed as a Bearer token:

Authorization: Bearer cap_your_api_key_here

API keys have roles that control what they can do:

viewer — read-only access to pages and publish status.
editor — read, create, edit, publish, and unpublish pages.
admin — everything, plus API key management.

Each key is rate-limited to 60 requests per minute by default. Exceeding the limit returns a 429 status with a Retry-After header.

Why AI Agents Are a Natural Fit

The Capuzzella API is intentionally simple: a handful of RESTful endpoints, JSON request and response bodies, standard HTTP verbs. This is exactly the kind of interface AI agents are good at. An agent reads the API documentation, understands the available operations, and translates your natural-language requests into the right sequence of HTTP calls.

Instead of manually constructing curl commands or writing scripts, you tell the agent what you want:

"List all my blog posts and tell me which ones have unpublished changes."
"Create a new page at /services.html with a hero section and three feature cards."
"Schedule the pricing page to publish tomorrow at 9 AM UTC."
"Upload this logo and add it to the header of every page."

The agent handles the mechanics — reading the current HTML, making edits, writing it back, publishing — while you focus on what the site should say and look like.

Setting Up OpenClaw with Capuzzella

OpenClaw is an open-source AI agent that runs on your own machine. It has full system access, can execute shell commands, and works with Claude, GPT, Gemini, and local models. Here's how to teach it to talk to your Capuzzella instance.

1. Install OpenClaw

curl -sSL https://openclaw.ai/install.sh | bash

Then run the onboarding wizard:

openclaw onboard --install-daemon

2. Create a Capuzzella Skill

OpenClaw uses skills — small instruction files that teach the agent how to use a tool. Create a skill folder in your OpenClaw workspace:

mkdir -p ~/.openclaw/skills/capuzzella

Then create ~/.openclaw/skills/capuzzella/SKILL.md with the following content:

---
name: capuzzella
description: Manage my Capuzzella website — list, read, create, edit, publish, and schedule pages via the REST API.
---

# Capuzzella API

Base URL: https://your-site.capuzzella.com
Auth: Bearer token via the CAPUZZELLA_API_KEY environment variable.

## Endpoints

### Pages
- GET /api/pages — list all draft pages
- GET /api/pages/<path> — read page HTML
- PUT /api/pages/<path> — create or update (body: { "html": "..." })
- DELETE /api/pages/<path> — delete a page

### Publishing
- POST /publish/ — publish all drafts
- POST /publish/<path> — publish one page
- DELETE /publish/<path> — unpublish
- GET /publish/status/<path> — check publish status

### Scheduled Publishing
- POST /publish/schedule — body: { "pagePath": "...", "publishAt": "ISO-8601" }
- GET /publish/schedule?status=pending — list pending
- DELETE /publish/schedule/<id> — cancel

### AI Chat
- POST /api/chat — body: { "message": "...", "pagePath": "...", "conversationId?": "..." }

### Uploads
- POST /api/upload — multipart form with "file" field
- GET /api/uploads — list uploaded files
- DELETE /api/uploads/<filename>

### Components
- GET /api/components — list component names
- POST /api/components/load — body: { "names": [...] }

## Auth header
Authorization: Bearer $CAPUZZELLA_API_KEY

## Notes
- All page paths end in .html (e.g. index.html, blog/post.html)
- Responses: { success: true, ... } or { error: "message" }
- Rate limit: 60 req/min per key

3. Add Your API Key

Add your Capuzzella API key to ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "capuzzella": {
        "enabled": true,
        "env": {
          "CAPUZZELLA_API_KEY": "cap_your_api_key_here"
        }
      }
    }
  }
}

OpenClaw injects this environment variable into the agent's runtime. The skill instructions tell the agent to use it as a Bearer token for every request.

4. Start Talking to Your Site

That's it. Open a chat with your OpenClaw agent — via Telegram, Discord, WhatsApp, or the terminal — and start giving instructions. The agent reads the skill, understands the API, and executes the calls.

Example Conversations

Here are real-world examples of what you can ask an agent connected to the Capuzzella API.

You:

"What pages do I have on my site?"

Agent runs:

GET /api/pages
Authorization: Bearer cap_...

Response:
{
  "pages": [
    "index.html",
    "about.html",
    "blog/index.html",
    "blog/why-bun.html",
    "blog/cms-approaches-compared.html"
  ]
}

Agent responds:

"You have 5 pages: a homepage, an about page, a blog index, and two blog posts (one about Bun, one comparing CMS approaches)."

You:

"Add a contact page with a simple contact form — name, email, and message fields."

Agent runs:

POST /api/chat
{
  "message": "Create a contact page with a form that has name, email, and message fields. Use Bootstrap styling.",
  "pagePath": "contact.html"
}

# Then publishes:
POST /publish/contact.html

Agent responds:

"Done. I created contact.html with a Bootstrap-styled contact form and published it. You can see it at /contact.html."

You:

"Check which pages have unpublished changes."

Agent runs:

# First, list all pages:
GET /api/pages

# Then check each one:
GET /publish/status/index.html
GET /publish/status/about.html
GET /publish/status/blog/index.html
...

Agent responds:

"Two pages have unpublished changes: index.html and about.html. Want me to publish them?"

You:

"Schedule the new pricing page to go live on April 1st at 9 AM UTC."

Agent runs:

POST /publish/schedule
{
  "pagePath": "pricing.html",
  "publishAt": "2026-04-01T09:00:00Z"
}

Agent responds:

"Scheduled. pricing.html will go live on April 1, 2026 at 9:00 AM UTC."

Beyond OpenClaw

OpenClaw is one example, but the Capuzzella API works with any tool that can make authenticated HTTP requests:

Cursor / Windsurf / Claude Code — coding agents can manage your site using the API skill as context, the same way OpenClaw does.
Custom scripts — a 20-line Python or Bash script can automate publishing workflows, scheduled content updates, or bulk page creation.
CI/CD pipelines — trigger publishes from GitHub Actions, GitLab CI, or any pipeline that can call a REST endpoint.
Zapier / Make / n8n — connect Capuzzella to thousands of other services through webhook-based automation platforms.

The API is the same regardless of what calls it. The authentication, the endpoints, the JSON format — it all stays consistent whether the caller is a human with curl, an AI agent, or a cron job.

The Bigger Picture

Traditional CMS platforms give you an admin panel and expect you to click through it. Capuzzella gives you an API and lets you choose how to interact with your site. The admin panel is still there for visual editing. But the API means your site isn't locked behind a GUI. Any agent, script, or service that speaks HTTP can manage your content.

As AI agents become the primary interface for managing digital infrastructure, the CMS platforms that expose clean, simple APIs will be the ones that integrate naturally into agent workflows. A handful of RESTful endpoints, standard auth, JSON in and out — that's all an agent needs.

Capuzzella was built with this future in mind.