技术文档

集成 MistPage 所需的一切：Quick Start、MCP Server、REST API 和 Webhooks。

快速开始

三步接入 MistPage API，开始以编程方式管理项目。

认证

所有请求需要 Bearer token。在仪表盘 > 设置 > API 密钥中创建。

Authorization: Bearer sk_mistpage_...

Base URL

https://mistpage.com/api/v1

第 1 步：获取 API Key

登录 MistPage，进入仪表盘 > 设置 > API 密钥，点击「创建密钥」。

第 2 步：创建项目

使用 API 创建一个新项目：

curl -X POST https://mistpage.com/api/v1/projects \
  -H "Authorization: Bearer sk_mistpage_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "My Project"}'
{
  "data": {
    "id": "proj_...",
    "title": "My Project",
    "slug": "my-project",
    "status": "draft"
  }
}

第 3 步：上传并发布

上传文件并发布项目：

curl -X POST https://mistpage.com/api/v1/projects/{id}/upload \
  -H "Authorization: Bearer sk_mistpage_..." \
  -F "files=@index.html" \
  -F "files=@style.css" \
  -F "entryFile=index.html"
curl -X POST https://mistpage.com/api/v1/projects/{id}/publish \
  -H "Authorization: Bearer sk_mistpage_..."

MCP Server

通过 Model Context Protocol (MCP) 将 MistPage 接入你的 AI 工具。

什么是 MCP？

Model Context Protocol (MCP) 是一种标准协议，让 AI 助手（如 Claude、Cursor）能直接调用外部工具。MistPage 的 MCP Server 让你的 AI 助手可以创建项目、上传文件、发布内容和查看统计。

连接地址https://mistpage.com/api/mcp
认证方式Bearer token（与 REST API 相同的 API Key）
传输协议Streamable HTTP

Claude Desktop 配置

{
  "mcpServers": {
    "mistpage": {
      "url": "https://mistpage.com/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_mistpage_..."
      }
    }
  }
}

Cursor 配置

{
  "mcpServers": {
    "mistpage": {
      "url": "https://mistpage.com/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_mistpage_..."
      }
    }
  }
}

可用工具

工具名称说明
list_projects列出所有项目
create_project创建新项目
get_project获取项目详情
update_project更新项目信息
delete_project删除项目
upload_files上传文件
publish_project发布项目
deploy_project一键创建、上传并发布
get_analytics获取访问统计
get_account_info获取账户信息和配额

REST API

完整的 RESTful API，支持项目的增删改查、文件上传和数据分析。

认证

所有 API 请求需要在 Header 中携带 Bearer token。在设置 > API 密钥中创建。

Authorization: Bearer sk_mistpage_...
POST/api/v1/projects

创建新项目（托管或链接类型）。

参数

title必填string
slug可选string
description可选string

请求

curl -X POST https://mistpage.com/api/v1/projects \
  -H "Authorization: Bearer sk_mistpage_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "My Project"}'

响应

{
  "data": {
    "id": "proj_...",
    "title": "My Project",
    "slug": "my-project",
    "status": "draft",
    "createdAt": "2026-04-03T12:00:00.000Z"
  }
}
GET/api/v1/projects

列出所有项目及基本统计。

请求

curl https://mistpage.com/api/v1/projects \
  -H "Authorization: Bearer sk_mistpage_..."

响应

{
  "data": [...],
  "meta": { "total": 5 }
}
GET/api/v1/projects/:id

获取项目详细信息。

请求

curl https://mistpage.com/api/v1/projects/{id} \
  -H "Authorization: Bearer sk_mistpage_..."

响应

{
  "data": {
    "id": "proj_...",
    "title": "My Project",
    "slug": "my-project",
    "accessPassword": true,
    "expiresAt": null,
    "webhookUrl": "https://..."
  }
}
PATCH/api/v1/projects/:id

更新项目标题、Slug 或描述。

参数

title可选string
slug可选string
description可选string

请求

curl -X PATCH https://mistpage.com/api/v1/projects/{id} \
  -H "Authorization: Bearer sk_mistpage_..." \
  -H "Content-Type: application/json" \
  -d '{"title": "New Title"}'

响应

{
  "data": {
    "id": "proj_...",
    "title": "New Title",
    "slug": "my-project"
  }
}
DELETE/api/v1/projects/:id

永久删除项目及其所有文件。

请求

curl -X DELETE https://mistpage.com/api/v1/projects/{id} \
  -H "Authorization: Bearer sk_mistpage_..."

响应

{
  "data": { "deleted": true }
}
POST/api/v1/projects/:id/upload

上传文件创建新版本（API 上限 4.5MB）。

参数

files必填multipart files
entryFile可选string
label可选string

请求

curl -X POST https://mistpage.com/api/v1/projects/{id}/upload \
  -H "Authorization: Bearer sk_mistpage_..." \
  -F "files=@index.html" \
  -F "files=@style.css" \
  -F "entryFile=index.html"

响应

{
  "data": {
    "versionId": "ver_...",
    "fileCount": 2,
    "totalSize": 4096
  }
}
POST/api/v1/projects/:id/publish

发布最新版本（或指定版本）。

参数

versionId可选string

请求

curl -X POST https://mistpage.com/api/v1/projects/{id}/publish \
  -H "Authorization: Bearer sk_mistpage_..."

响应

{
  "data": {
    "published": true,
    "versionId": "ver_..."
  }
}
GET/api/v1/projects/:id/analytics

获取项目访问分析数据。

请求

curl https://mistpage.com/api/v1/projects/{id}/analytics \
  -H "Authorization: Bearer sk_mistpage_..."

响应

{
  "data": {
    "overview": { "totalVisits": 128, "uniqueVisitors": 45, "passwordVerified": 12 },
    "daily": [...],
    "devices": [...],
    "countries": [...],
    "referers": [...]
  }
}

错误处理

所有错误返回包含 code 和 message 的 JSON 对象。

{
  "error": {
    "code": "VALIDATION",
    "message": "title is required"
  }
}

400 — 参数错误

401 — 缺少或无效的 API 密钥

403 — 权限不足

404 — 资源未找到

413 — 上传过大（API 上限 4.5MB）

Webhooks

在项目被访问时接收实时通知。

概述

当有人访问你的项目时，MistPage 会向你配置的 URL 发送 POST 请求。

设置方法

进入项目设置 > Webhook，输入你的 HTTPS URL 并保存。

Payload 格式

每次项目被访问时，你会收到以下格式的 JSON：

{
  "event": "project.visited",
  "project": {
    "id": "proj_...",
    "slug": "my-project",
    "title": "My Project"
  },
  "visitor": {
    "country": "US",
    "referer": "https://..."
  },
  "timestamp": "2026-04-03T12:00:00.000Z"
}

更多事件类型（如项目创建、文件上传、版本发布）即将推出。