--- name: kwiksite description: Read, edit and publish a KwikSite website over the KwikSite API. Use when the user wants their own agent to build or update a site hosted on KwikSite (kwiksite.dev). Requires a KwikSite API key. --- # KwikSite site builder (API) KwikSite hosts **static websites** (HTML/CSS/JS). This skill lets you read a site's files, edit them, and publish — using the user's KwikSite account via an API key. You bring the model; KwikSite stores, hosts and serves the result. ## Setup - **Base URL:** `https://app.kwiksite.dev/api/v1` - **Auth:** send `Authorization: Bearer ` on every request. The user creates a key at https://app.kwiksite.dev/settings. Treat it as a secret. - All requests/responses are JSON unless noted. ## Workflow 1. **List sites:** `GET /projects` → pick the target project `id` (or `POST /projects` `{ "name": "..." }` to create one). 2. **Read current files:** `GET /projects/:id/files?include=content` for the manifest + inline text, and `GET /projects/:id/files/` for a single file. 3. **Edit:** `POST /projects/:id/edits` with an `operations` array (see below). The site has a *draft* you can edit repeatedly. 4. **Publish:** `POST /projects/:id/publish` to make the current draft live. Returns the live `url`. 5. **Verify:** re-read files, or fetch the live `url`. 6. **Roll back (recover):** if a publish went wrong, `GET /projects/:id/versions` to find a previous `versionId`, then `POST /projects/:id/rollback/:versionId`. This restores that version's files into the draft **and** makes it live again — it overwrites the current draft, so read the files first if unsure. ## Editing — `POST /projects/:id/edits` ```json { "operations": [ { "action": "write", "path": "index.html", "content": "" }, { "action": "write", "path": "css/styles.css", "content": "" }, { "action": "rename", "path": "about.html", "from": "about-us.html" }, { "action": "delete", "path": "old.html" } ] } ``` Rules — follow these or edits will be rejected (HTTP 422) or the site will break: - **Static files only:** HTML, CSS, JS, SVG, JSON, fonts, etc. No server code, no build step. - **The entry point must be `index.html`.** - **Relative paths only** — e.g. `css/styles.css`, not `/css/styles.css`. No leading `/`, no `..`. - **For `write`, return the COMPLETE new file body** every time — never a diff or partial file. - **Only include files you are changing.** Leave untouched files out of the array. - **Never `write` raster images** (png/jpg/jpeg/gif/webp/avif/ico) — those come from the user's uploads. You may write `.svg`. - Keep it responsive, clean, modern. Prefer a single stylesheet unless asked otherwise. ### Contact forms KwikSite can email contact-form submissions to the site owner, but only when the site has a custom domain with email enabled (set up in the KwikSite dashboard). If that's configured, the owner can tell you the form endpoint to POST to. Otherwise use a `mailto:` link. ## Endpoints | Method & path | Purpose | |---|---| | `GET /projects` | List the user's sites | | `POST /projects` | Create a site (`{ "name": "..." }`) | | `GET /projects/:id/files` | File manifest (`?include=content` for inline text) | | `GET /projects/:id/files/` | One file's content | | `POST /projects/:id/edits` | Apply write/delete/rename operations to the draft | | `POST /projects/:id/publish` | Publish the draft → returns live `url` | | `GET /projects/:id/versions` | List published versions (newest first; `versionId`, `files`, `createdAt`) | | `POST /projects/:id/rollback/:versionId` | Restore a version into the draft **and** make it live | | `GET /projects/:id/export` | Download the site as a `.zip` | | `GET /domains/:domain/dns` | List DNS records you manage on a domain | | `PUT /domains/:domain/dns` | Add/update a DNS record | | `DELETE /domains/:domain/dns` | Delete a DNS record | Errors: `401` bad/missing key, `404` not your project/domain / not found, `422` invalid operation, `429` rate limited. ## DNS records (for a domain you own through KwikSite) If the user has a custom domain on their account, you can manage its DNS — e.g. set up Google Workspace email. KwikSite's own records (site routing, email/SES, certificate validation) are **hidden and protected**: they won't appear in the list and attempts to edit/delete them return `422`. - `GET /domains//dns` → `{ records: [{ name, type, ttl, values }], managedCount }`. - `PUT /domains//dns` with `{ "name": "@", "type": "MX", "ttl": 3600, "value": "1 aspmx.l.google.com" }`. - `name` is `@` for the root or a subdomain (relative to the domain). Types: A, AAAA, CNAME, MX, TXT, SRV. - `value` may be multiple lines for multi-value records (e.g. several MX). TXT values are quoted for you. - MX value is `" "`; SRV is `" "`. - `DELETE /domains//dns` with `{ "name": "@", "type": "MX" }`. Example — point a domain's email at Google Workspace: ```bash curl -s -H "$AUTH" -H 'Content-Type: application/json' -X PUT \ -d '{"name":"@","type":"MX","ttl":3600,"value":"1 aspmx.l.google.com\n5 alt1.aspmx.l.google.com"}' \ $BASE/domains/example.com/dns curl -s -H "$AUTH" -H 'Content-Type: application/json' -X PUT \ -d '{"name":"@","type":"TXT","value":"v=spf1 include:_spf.google.com ~all"}' \ $BASE/domains/example.com/dns ``` ## Example (curl) ```bash BASE=https://app.kwiksite.dev/api/v1 AUTH="Authorization: Bearer $KWIKSITE_API_KEY" curl -s -H "$AUTH" $BASE/projects curl -s -H "$AUTH" "$BASE/projects/$ID/files?include=content" curl -s -H "$AUTH" -H 'Content-Type: application/json' \ -d '{"operations":[{"action":"write","path":"index.html","content":"

Hello

"}]}' \ $BASE/projects/$ID/edits curl -s -H "$AUTH" -X POST $BASE/projects/$ID/publish ``` A machine-readable contract is at `https://app.kwiksite.dev/skill/openapi.yaml`. ## Prefer a native connector? (MCP) If your agent supports remote **MCP** connectors (e.g. Cowork, Claude), you can skip the API key and add KwikSite as a one-click connector instead — the same actions show up as native tools, authorized via OAuth (sign in + consent once). Connector URL: `https://app.kwiksite.dev/mcp`. See `https://app.kwiksite.dev/api-docs.html#mcp`.