ezyhost

# EzyHost — Agent Skill

> This document describes how AI agents can interact with EzyHost programmatically.
> For human users, visit [ezyhost.io](https://ezyhost.io).

## Base URL

```
https://ezyhost.io/api
```

## Authentication

All API requests require an API key passed as a header:

```
x-api-key: $EZYHOST_API_KEY
```

The key is loaded from the `EZYHOST_API_KEY` environment variable. Generate your API key at `https://ezyhost.io/dashboard/api-keys`.

**Note:** API access requires the Pro plan or higher.

---

## Endpoints

### Projects

#### List Projects
```
GET /api/projects
```
Returns `{ projects: [{ id, name, slug, subdomain, customDomain, status, storageUsed, seoScore, deployedAt, _count: { files, analytics } }] }`

#### Create Project
```
POST /api/projects
Content-Type: application/json
Body: { "name": "my-site", "subdomain": "my-site" }
```
Returns `{ project: { id, name, subdomain, s3Prefix, url, ... } }`

The subdomain must be 3+ characters, lowercase alphanumeric with hyphens. Returns `409 SUBDOMAIN_TAKEN` if already in use. Your site will be live at `https://{subdomain}.ezyhost.site`.

Optional fields: `displayMode` ("standard" | "presentation"), `hideFromSearch` (boolean), `password` (string).

#### Check Subdomain Availability
```
GET /api/projects/check-subdomain/:subdomain
```
Returns `{ available: true/false, subdomain }`. Use this to validate before creating.

#### Get Project
```
GET /api/projects/:id
```
Returns `{ project: { id, name, subdomain, customDomain, status, storageUsed, seoScore, files: [...], ... } }`

#### Update Project
```
PATCH /api/projects/:id
Content-Type: application/json
Body: { "name": "new-name", "metaTitle": "...", "metaDescription": "...", "password": "...", "removeBranding": true, "displayMode": "standard", "hideFromSearch": false, "emailCapture": true }
```

#### Delete Project
```
DELETE /api/projects/:id
```
Deletes the project and all associated files from storage. This cannot be undone.

---

### File Upload

#### Upload Files (ZIP or individual)
```
POST /api/upload/:projectId
Content-Type: multipart/form-data
Body: files (multipart)
```
Returns `{ message, filesUploaded, totalSize, project: { id, subdomain } }`

Supports `.zip` archives (auto-extracted) and individual files. All uploaded files go through malware scanning (ClamAV + magic byte validation).

**Supported file types:** HTML, CSS, JS, JSON, XML, SVG, images (PNG, JPG, GIF, WebP, AVIF, ICO), PDFs, presentations (PPTX), documents (DOCX, XLSX), audio (MP3, WAV, OGG, FLAC, AAC), video (MP4, WebM, MOV), fonts (WOFF, WOFF2, TTF, OTF, EOT), archives (ZIP), 3D models (GLB, GLTF, OBJ), and any other static asset.

**Blocked file types:** Executables (.exe, .dll, .bat, .sh, .php, .asp, .jar) and SVGs containing scripts or event handlers are rejected.

#### Delete a File
```
DELETE /api/upload/:projectId/files/:fileId
```

#### Bulk Delete Files
```
POST /api/upload/:projectId/files/bulk-delete
Content-Type: application/json
Body: { "fileIds": ["id1", "id2", "id3"] }
```

#### Rename a File
```
PATCH /api/upload/:projectId/files/:fileId
Content-Type: application/json
Body: { "newPath": "assets/renamed-file.png" }
```

---

### GitHub Import

#### Import from GitHub
```
POST /api/github/:projectId
Content-Type: application/json
Body: { "owner": "username", "repo": "repo-name", "branch": "main", "subfolder": "dist" }
```
Returns `{ message, repo, branch, filesUploaded, filesSkipped, totalSize }`

Imports files from a public GitHub repository. The `branch` defaults to "main" and automatically falls back to "master" if not found. The optional `subfolder` field lets you import only a subdirectory (e.g. "dist", "build").

Requires Pro plan or higher.

---

### Version Rollback

#### List Versions
```
GET /api/versions/:projectId
```
Returns `{ versions: [{ id, version, label, fileCount, totalSize, createdAt }] }`

#### Create Version Snapshot
```
POST /api/versions/:projectId
Content-Type: application/json
Body: { "label": "v1.0" }
```
Snapshots the current state of all project files. Requires Pro plan or higher.

#### Rollback to Version
```
POST /api/versions/:projectId/rollback/:version
```
Restores all files to the state captured in the specified version number.

---

### SEO

#### Get SEO Report
```
GET /api/seo/:projectId
```
Returns `{ score, suggestions: [{ id, type, severity, message, resolved }] }`

Requires Pro plan or higher.

#### Run SEO Analysis
```
POST /api/seo/:projectId/analyze
```
Triggers a fresh SEO scan and returns updated suggestions.

#### Resolve a Suggestion
```
PATCH /api/seo/suggestion/:id/resolve
```

#### AI Auto-Fix SEO Issues
```
POST /api/seo/:projectId/ai-fix
Content-Type: application/json
Body: { "suggestionIds": ["id1", "id2"] }
```
Uses AI to automatically fix SEO issues in your HTML files. Counts against AI generation limits.

---

### Analytics

#### Get Analytics
```
GET /api/analytics/:projectId?period=7d
```
Periods: `24h`, `7d`, `30d`, `90d`

**Basic analytics (all plans):**
Returns `{ totalVisits, visitsByDay, topPages, isAdvanced }`

**Advanced analytics (Pro+ plans):**
Additionally returns `{ uniqueVisitors, uniqueByDay, topReferrers, topCountries, devices, browsers }`

Free plan users receive `isAdvanced: false` and advanced fields are empty.

#### Track Event (public, no auth required)
```
POST /api/analytics/track
Content-Type: application/json
Body: { "projectId": "...", "path": "/page", "referrer": "..." }
```

---

### QR Codes

#### Generate QR Code
```
POST /api/qrcode/:projectId
```
Returns `{ qrCodeUrl: "data:image/png;base64,...", siteUrl: "https://..." }`

Generates a QR code pointing to the project's live URL (subdomain or custom domain). Returns a base64 data URL. Available on all paid plans.

#### Get QR Code
```
GET /api/qrcode/:projectId
```
Returns `{ qrCodeUrl: "data:image/..." | null }`

---

### Email Capture

#### Toggle Email Capture on Project
```
PATCH /api/emails/:projectId/toggle
```
Returns `{ emailCapture: true/false }`. Requires Business plan.

When enabled, visitors to the hosted site see a popup email collection form after 5 seconds.

#### Submit Email (public, no auth)
```
POST /api/emails/submit
Content-Type: application/json
Body: { "email": "visitor@example.com", "projectId": "...", "source": "modal" }
```
Source options: `modal`, `inline`, `api`. Only works if the project has email capture enabled and the project owner has a Business plan.

#### Get Captured Emails
```
GET /api/emails/:projectId?page=1&limit=50
```
Returns `{ emails: [{ id, email, source, createdAt }], total, page, totalPages }`

Requires Business plan.

#### Export Emails as CSV
```
GET /api/emails/:projectId/export
```
Returns a CSV file download. Requires Business plan.

#### Delete a Captured Email
```
DELETE /api/emails/:projectId/:emailId
```

---

### Teams

#### List Teams
```
GET /api/teams
```
Returns `{ teams: [{ id, name, ownerId, members: [...] }] }`

#### Create Team
```
POST /api/teams
Content-Type: application/json
Body: { "name": "My Team" }
```
Requires Business plan.

#### Add Team Member
```
POST /api/teams/:teamId/members
Content-Type: application/json
Body: { "email": "user@example.com", "role": "editor" }
```
Roles: `editor`, `viewer`.

#### Update Member Role
```
PATCH /api/teams/:teamId/members/:memberId
Content-Type: application/json
Body: { "role": "viewer" }
```

#### Remove Team Member
```
DELETE /api/teams/:teamId/members/:memberId
```

#### Leave Team
```
POST /api/teams/:teamId/leave
```

#### Delete Team
```
DELETE /api/teams/:teamId
```

---

### Domains

#### Add Custom Domain
```
POST /api/domains/:projectId
Content-Type: application/json
Body: { "domain": "example.com" }
```
Returns `{ dnsInstructions: { type, name, value } }` — DNS records you need to create.

Requires Pro plan or higher.

#### Verify Domain DNS
```
GET /api/domains/:projectId/verify
```
Returns `{ verified: true/false, dnsInstructions }`. Call this after setting up DNS records.

#### Remove Domain
```
DELETE /api/domains/:projectId
```

---

### AI Builder

#### Chat (generate/edit websites via AI)
```
POST /api/aibuilder/chat
Content-Type: application/json
Body: { "message": "build a portfolio site", "history": [], "currentFiles": [] }
```
Returns **SSE stream** with events:
- `status` — progress updates ("Generating HTML...")
- `progress` — percentage (0-100)
- `done` — `{ files: [{ filename, content }] }` — the generated files
- `error` — `{ message }` on failure

Counts against per-plan AI generation limits. Only one AI generation can run at a time per user.

#### Deploy AI-Generated Files
```
POST /api/aibuilder/deploy/:projectId
Content-Type: application/json
Body: { "files": [{ "filename": "index.html", "content": "<!DOCTYPE html>..." }] }
```

#### Download as ZIP
```
POST /api/aibuilder/download-zip
Content-Type: application/json
Body: { "files": [{ "filename": "index.html", "content": "..." }] }
```
Returns a ZIP file download.

#### Templates

```
GET    /api/aibuilder/templates           — list saved templates
GET    /api/aibuilder/templates/:id       — get template details
POST   /api/aibuilder/templates           — save new template
PATCH  /api/aibuilder/templates/:id       — update template
DELETE /api/aibuilder/templates/:id       — delete template
```

Template body: `{ "name": "My Template", "description": "...", "messages": [...], "files": [...] }`

---

### API Keys

#### Get Current Key
```
GET /api/apikey
```
Returns `{ hasKey: true/false, apiKey: "ag_••••..." }` — key is partially masked.

#### Generate New Key
```
POST /api/apikey/generate
```
Returns `{ apiKey: "ag_..." }` — full key shown only once. Store it securely. Revokes any previous key.

Requires Pro plan or higher.

#### Revoke Key
```
DELETE /api/apikey
```

---

### Plans (Public)

#### Get All Plans
```
GET /api/plans
```
No authentication required. Returns `{ plans: [{ plan, name, priceMonthly, maxProjects, maxStorageMB, ... }] }` with all feature flags and limits for each plan.

---

### Billing

#### Get Billing Info
```
GET /api/billing
```
Returns `{ plan, subscription, aiCredits, usage }`.

#### Get AI Usage
```
GET /api/billing/ai-usage
```
Returns `{ used, limit, remaining, resetsAt }`.

---

## Plan Limits

| Feature | Free | Pro ($9/mo) | Business ($29/mo) |
|---------|------|-------------|-------------------|
| Projects | 2 | 15 | Unlimited |
| Storage | 50 MB | 2 GB | 20 GB |
| Max file size | 10 MB | 100 MB | 500 MB |
| Custom domains | — | 3 | Unlimited |
| API access | — | ✅ | ✅ |
| GitHub import | — | ✅ | ✅ |
| Version rollback | — | Up to 5 | Up to 30 |
| Password protection | — | ✅ | ✅ |
| Remove branding | — | ✅ | ✅ |
| SEO tools | — | ✅ | ✅ |
| Advanced analytics | — | ✅ | ✅ |
| QR codes | ✅ | ✅ | ✅ |
| Hide from search | — | ✅ | ✅ |
| Email capture | — | — | ✅ |
| Team members | — | — | Up to 5 |
| Priority support | — | — | ✅ |
| AI generations | 3/mo | 10/mo | 30/mo |
| AI templates | 1 | 10 | Unlimited |
| Presentation mode | — | ✅ | ✅ |
| Basic analytics | ✅ | ✅ | ✅ |

---

## Hosted Site URLs

Sites are served at:
- **Free subdomain:** `https://{subdomain}.ezyhost.site`
- **Custom domain:** `https://{your-domain.com}` (Pro+ plans)

All sites include HTTPS, CDN caching, automatic file browser for non-HTML projects, and optional presentation mode for PDF/PPTX files.

**Injected features on served sites:**
- **Branding badge:** "Hosted on ezyhost" badge shown on free plan sites. Removable on paid plans via `removeBranding` project setting.
- **Email capture popup:** When enabled (Business plan), visitors see a subscribe popup after 5 seconds. Dismissible and stored in sessionStorage.
- **Analytics tracking:** Pageviews are automatically tracked for HTML files.

---

## Error Responses

All errors return JSON:
```json
{ "error": "Description of the error" }
```

Plan limit errors include `"upgrade": true` to indicate a higher plan is needed:
```json
{ "error": "GitHub import requires a Pro plan or higher", "upgrade": true }
```

Subdomain conflicts:
```json
{ "error": "The subdomain \"my-site\" is already taken.", "code": "SUBDOMAIN_TAKEN" }
```

Common HTTP status codes:
- `400` — Bad request / validation error
- `401` — Not authenticated
- `403` — Plan limit reached or feature disabled
- `404` — Resource not found
- `409` — Conflict (subdomain taken)
- `429` — Rate limited
- `500` — Server error

---

## Rate Limits

- **General API:** 300 requests per 15 minutes per API key
- **Upload:** 2 requests per second
- **Analytics tracking:** 60 writes per minute per IP
- **Email capture submit:** 10 per minute per IP
- **AI Builder:** Subject to per-plan generation limits (1 concurrent request max)

---

## Example: Deploy a Static Site

```bash
# 1. Check subdomain availability
curl https://ezyhost.io/api/projects/check-subdomain/my-site \
  -H "x-api-key: $EZYHOST_API_KEY"

# 2. Create a project
curl -X POST https://ezyhost.io/api/projects \
  -H "x-api-key: $EZYHOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-site", "subdomain": "my-site"}'

# 3. Upload files (ZIP)
curl -X POST https://ezyhost.io/api/upload/PROJECT_ID \
  -H "x-api-key: $EZYHOST_API_KEY" \
  -F "files=@site.zip"

# 4. Generate QR code
curl -X POST https://ezyhost.io/api/qrcode/PROJECT_ID \
  -H "x-api-key: $EZYHOST_API_KEY"

# 5. Check SEO (Pro+)
curl https://ezyhost.io/api/seo/PROJECT_ID \
  -H "x-api-key: $EZYHOST_API_KEY"

# 6. Add custom domain (Pro+)
curl -X POST https://ezyhost.io/api/domains/PROJECT_ID \
  -H "x-api-key: $EZYHOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'
```

Your site is now live at `https://my-site.ezyhost.site`

## Example: Import from GitHub

```bash
# Import a public repo (auto-detects main/master branch)
curl -X POST https://ezyhost.io/api/github/PROJECT_ID \
  -H "x-api-key: $EZYHOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"owner": "emilbaehr", "repo": "automatic-app-landing-page"}'
```

## Example: AI-Generate and Deploy

```bash
# 1. Generate a site with AI (SSE stream)
curl -N -X POST https://ezyhost.io/api/aibuilder/chat \
  -H "x-api-key: $EZYHOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "build a modern portfolio with dark theme", "history": []}'

# 2. Deploy the generated files to a project
curl -X POST https://ezyhost.io/api/aibuilder/deploy/PROJECT_ID \
  -H "x-api-key: $EZYHOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files": [{"filename": "index.html", "content": "..."}]}'
```