# QuickHost API Reference

QuickHost publishes AI-generated deliverables (HTML, PDF, Markdown, images, data, zip sites) to clean URLs with access control, engagement tracking, and an agent revision loop.

## Authentication

All `/v1` endpoints require `Authorization: Bearer qh_...`.

Create an API token:
- Dashboard: https://app.quickhost.ing/settings/tokens
- CLI: `uv tool install quickhost-cli && qh login`

## Endpoints

### Projects

| Method | Path | Description |
|--------|------|-------------|
| GET    | /v1/projects | List projects + usage |
| POST   | /v1/projects | Multipart publish (create) |
| PUT    | /v1/projects/{slug} | Raw-body single-request publish (create or replace) |
| POST   | /v1/projects/{slug}/files | Add/replace files (site; new version) |
| GET    | /v1/projects/{slug} | Project detail + version list |
| PATCH  | /v1/projects/{slug} | Update metadata / rename / password |
| DELETE | /v1/projects/{slug} | Soft-delete + storage delete |

**Publish a file (single request):**
```
PUT https://api.quickhost.ing/v1/projects/my-report
Authorization: Bearer qh_...
Content-Type: application/pdf

<binary PDF bytes>
```

Response: `{"slug": "my-report", "url": "...", "kind": "pdf", "version": 1}`

Content-Types supported: `text/html`, `text/markdown`, `text/plain`, `text/csv`, `application/json`, `application/pdf`, `application/zip`, `image/*`, `video/*`.

### Share Links

| Method | Path | Description |
|--------|------|-------------|
| GET    | /v1/projects/{slug}/share-links | List share links (token hidden) |
| POST   | /v1/projects/{slug}/share-links | Create share link (token shown once) |
| PATCH  | /v1/share-links/{id} | Update label / expiry |
| DELETE | /v1/share-links/{id} | Revoke |

**Create a share link:**
```
POST https://api.quickhost.ing/v1/projects/my-report/share-links
Authorization: Bearer qh_...
Content-Type: application/json
X-CSRF-Token: <csrf>

{"label": "For Acme Inc", "expires_in_days": 7, "notify_on_first_open": true}
```

Response includes `share_url` and `token` (shown once).

### Comments

| Method | Path | Description |
|--------|------|-------------|
| GET    | /v1/projects/{slug}/comments?status=open/resolved/all | List comments |
| POST   | /v1/comments/{id}/resolve | Resolve comment |
| POST   | /v1/comments/{id}/replies | Reply to a comment |
| PATCH  | /v1/comments/{id} | Edit a comment you authored |
| DELETE | /v1/comments/{id} | Delete comment (add ?author_only=true to restrict to your own) |

Comments carry an `edited` flag — true means the author revised the body after
posting, so the text is not what was originally written. Editing and
author-scoped deleting are limited to comments you wrote, within 15 minutes of
posting, and only while the comment is unresolved.

**List open comments:**
```
GET https://api.quickhost.ing/v1/projects/my-report/comments?status=open
Authorization: Bearer qh_...
```

### Analytics

| Method | Path | Description |
|--------|------|-------------|
| GET    | /v1/projects/{slug}/analytics?days=30 | Analytics (1-90 days, default 30) |

**Get analytics:**
```
GET https://api.quickhost.ing/v1/projects/my-report/analytics?days=7
Authorization: Bearer qh_...
```

## Error Envelope

All errors return:
```json
{
  "error": {
    "code": "slug_taken",
    "message": "The slug 'my-report' is already taken.",
    "field": "slug",
    "details": {}
  }
}
```

Common codes: `auth_required` (401), `not_found` (404), `slug_taken` (409), `quota_exceeded` (402), `upload_too_large` (413), `validation_error` (422).

## CLI Quickstart

```bash
uv tool install quickhost-cli
qh login          # opens browser for auth
qh publish .      # publish current directory as a site
qh publish report.pdf --visibility public
qh publish index.html --slug my-page
```

## MCP Setup (Claude Code)

Other clients — Codex CLI, Gemini CLI, Cursor, VS Code, Claude Desktop, Grok —
and troubleshooting: https://api.quickhost.ing/mcp.md

```bash
# Production
claude mcp add --transport http quickhost https://api.quickhost.ing/mcp \
  --header "Authorization: Bearer qh_..."

# Local dev
claude mcp add --transport http quickhost https://api.quickhost.ing/mcp \
  --header "Authorization: Bearer qh_..."
```

MCP tools available:
- `publish`
- `update`
- `list_projects`
- `list_folders`
- `create_folder`
- `update_folder`
- `delete_folder`
- `move_project`
- `get_comments`
- `resolve_comment`
- `reply_comment`
- `edit_comment`
- `delete_comment`
- `set_visibility`
- `create_share_link`
- `get_project_link`
- `get_analytics`

All tools require the `Authorization: Bearer qh_...` header.
Text content cap: 256 KB. Binary cap: 1 MB. Use `qh publish` CLI for larger files.

## Interactive Docs

OpenAPI: https://api.quickhost.ing/docs
ReDoc: https://api.quickhost.ing/redoc