Tài liệu API

Cập nhật lần cuối: 2026-07-05

API của hdply cho phép script và AI agent quản lý trang của bạn theo cách lập trình: liệt kê dự án, đọc HTML, đăng bản cập nhật và tạo trang mới. Đây là một REST API nhỏ gọn, dễ đoán — biết dùng curl là biết dùng hdply.

Xác thực

Tạo khóa API cá nhân trong bảng điều khiển console (thẻ "Khóa API"). Gửi kèm dưới dạng bearer token trong mọi yêu cầu:

Authorization: Bearer hdply_sk_…

Khóa chỉ hiển thị một lần khi tạo; tạo lại sẽ thay thế khóa cũ, xóa sẽ thu hồi ngay lập tức. Hãy giữ bí mật — khóa này cấp quyền truy cập mọi dự án của bạn.

URL gốc

https://api.app.hdply.com

Endpoint

GET /v1/projects — liệt kê các dự án của bạn.
POST /v1/projects — tạo dự án. Body JSON: {"name": "tùy chọn", "html": "tùy chọn"}. Nếu có html, trang lên sóng ngay; không có tên thì dùng <title> của HTML. Máy chủ tự gán subdomain ngẫu nhiên.
GET /v1/projects/{id} — một dự án. {id} chấp nhận id dạng số hoặc subdomain (vd. k3v9x2m7q1).
GET /v1/projects/{id}/html — HTML đang chạy hiện tại.
PUT /v1/projects/{id}/html — đăng HTML mới (body text/html thô, lên sóng ngay khi phản hồi trả về).
GET /v1/projects/{id}/deployments — lịch sử triển khai (triển khai qua API gắn nhãn "source": "api").

Không có DELETE. Việc xóa trang cố ý chỉ có trên web, nên agent tự động không bao giờ phá hủy được công sức của bạn. Mọi lần triển khai qua API đều có phiên bản — khôi phục bất kỳ phiên bản nào từ console.

Bắt đầu nhanh

export HDPLY_KEY=hdply_sk_…

# create a site and go live in one call
curl -X POST https://api.app.hdply.com/v1/projects \
  -H "Authorization: Bearer $HDPLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"html": "<!doctype html><title>Hello</title><h1>Hi!</h1>"}'
# → {"project": {"subroute": "k3v9x2m7q1", "url": "https://k3v9x2m7q1.hdply.com", …}}

# read the live HTML
curl https://api.app.hdply.com/v1/projects/k3v9x2m7q1/html \
  -H "Authorization: Bearer $HDPLY_KEY"

# publish an update
curl -X PUT https://api.app.hdply.com/v1/projects/k3v9x2m7q1/html \
  -H "Authorization: Bearer $HDPLY_KEY" \
  -H "Content-Type: text/html" \
  --data-binary @index.html

Giới hạn và lỗi

HTML giới hạn 1 MB mỗi trang (một file độc lập duy nhất là tốt nhất).
Gói miễn phí gồm 20 trang; Pro không giới hạn.
Lỗi ở dạng JSON: {"code": "…", "error": "thông báo"}. Mã thường gặp: unauthorized (401), project_not_found (404), project_limit (403), file_too_large (413).

Claude & MCP

hdply có sẵn máy chủ MCP tích hợp, để Claude Code và Claude Desktop dùng trang của bạn như công cụ gốc (list_sites, create_site, get_site_html, deploy_site, get_deploy_history). Kết nối Claude Code bằng một lệnh:

claude mcp add --transport http hdply https://api.app.hdply.com/mcp \
  --header "Authorization: Bearer hdply_sk_…"

Với Claude Desktop, thêm đoạn sau vào cấu hình MCP (claude_desktop_config.json):

{
  "mcpServers": {
    "hdply": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.app.hdply.com/mcp",
               "--header", "Authorization: Bearer hdply_sk_…"]
    }
  }
}

Dùng với AI agent

Dán khối bên dưới cùng khóa của bạn vào ChatGPT, Claude hoặc bất kỳ agent nào có quyền truy cập shell. Từ đó chỉ cần nói "cập nhật trang của tôi" là nó biết cách làm.

You can manage my hdply websites via its REST API.
Base URL: https://api.app.hdply.com
Auth header on every request: "Authorization: Bearer <MY_KEY>"

Endpoints:
- GET  /v1/projects                     -> list my sites
- POST /v1/projects                     -> create; JSON {"name"?, "html"?}; html goes live instantly
- GET  /v1/projects/{id}/html           -> current HTML ({id} = numeric id or subdomain)
- PUT  /v1/projects/{id}/html           -> publish new HTML (raw text/html body)
- GET  /v1/projects/{id}/deployments    -> version history

Rules: HTML max 1MB, single self-contained file preferred (inline CSS/JS).
There is no delete endpoint. Every deploy is versioned and restorable.
After publishing, the site is live at https://{subroute}.hdply.com immediately.

Bản tóm tắt máy đọc được cho crawler và agent: hdply.com/llms.txt