快速开始
- 登录你的 ServerPrism 账户。
- 打开账户 → API 凭据并创建一个令牌。
- 只选择你的集成所需的最小 scope 集合。
- 令牌显示时请只复制一次:我们从不以明文保存它,也无法找回。
- 将令牌作为 Bearer 凭据,用于下面的端点。
所有请求都发往 https://serverprism.com。所有响应均为 JSON。所有时间戳均为 UTC 的 ISO-8601 格式。
认证
请在 Authorization: Bearer 请求头中传入令牌。令牌属于个人:每个令牌只属于一位 ServerPrism 客户,只能操作该客户名下的服务。
curl https://serverprism.com/api/v1/client/servers \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Accept: application/json"你在控制台创建的令牌是个人访问令牌。OAuth 的 client-credentials 和 authorization-code 流程目前不向客户集成开放。
Scopes
每个令牌带有一个或多个 scope。端点要求具备特定 scope:缺少时返回 403。
| Scope | 允许 |
|---|---|
servers:read |
查看你的服务器(状态、资源、基本信息) |
servers:control |
向你的服务器发送电源信号(start/stop/restart/kill)和控制台命令 |
backups:create |
为你的服务器创建新备份(占用你的备份名额) |
billing:read |
查看你的服务计费详情和账单(包括 PDF 下载) |
tickets:read |
查看你的支持工单及其回复 |
tickets:write |
创建新的支持工单并回复你现有的工单 |
account:read |
查看你的基本账户信息(姓名、邮箱地址) |
速率限制
限制按分钟计算,并同时适用两层:每个令牌一层,账户下所有令牌合计一层(先用完的先生效)。限制刻意设得较保守。如果你需要更高额度,请提交工单并告诉我们你的集成情况。
| 分组 | 限制 | 端点 |
|---|---|---|
read |
每个令牌 60 次,每个账户 120 次 | 除账单 PDF 外的所有 GET 端点 |
control |
每个令牌 20 次,每个账户 30 次 | 电源、命令、创建备份、账单 PDF |
tickets |
每个令牌 5 次,每个账户 10 次;另外每 30 秒最多 1 个新工单 | 创建工单、回复工单 |
超出限制会返回 429 Too Many Requests 并带有 Retry-After 头。每个响应都带有令牌分组的 X-RateLimit-Limit 和 X-RateLimit-Remaining。请退避后重试,切勿在收到 429 后紧密循环重试。
错误
错误响应为 JSON,包含便于阅读的 message;API 特有的错误还会带一个稳定的、机器可读的 error 代码,例如 service_not_active。验证错误 (422) 还会包含按字段组织的 errors 对象。
| 状态码 | 含义 |
|---|---|
| 401 | 缺少令牌或令牌无效。 |
| 403 | 令牌不包含所需的 scope。 |
| 404 | 未找到,或不属于你(两种情况有意看起来一样)。 |
| 409 | 服务器当前状态不允许此操作:service_not_active(已暂停、已取消、待处理)、service_paused(冷存储)、server_offline、server_busy、backup_limit_reached、backup_in_progress。 |
| 422 | 请求体未通过验证。 |
| 429 | 超出速率限制。 |
| 503 | 上游节点暂时不可用。请稍等片刻后重试。 |
端点
URL 中的服务器 ID 是数字形式的服务 ID,与你的 /services/{id} URL 中的相同。下面所有路径都相对于 https://serverprism.com/api/v1/client。列表端点支持 page 和 per_page(最大 100),并返回包含 total 和 last_page 的 meta 块。
/api/v1/client/serversscope: servers:read列出令牌持有者名下所有活跃或已暂停的服务。轮询成本低:不会联系服务器。
请求
curl https://serverprism.com/api/v1/client/servers \
-H "Authorization: Bearer YOUR_TOKEN"响应
{
"data": [
{
"id": 1234,
"product": "Minecraft 4 GB",
"service_status": "active",
"name": "Fred's Minecraft",
"paused": false,
"game": { "slug": "minecraft", "name": "Minecraft", "runtime": "paper", "version": "1.21.4" },
"expires_at": "2026-11-01T00:00:00+00:00"
}
]
}/api/v1/client/servers/{id}scope: servers:read包含列表端点的全部内容,另加玩家使用的连接地址、服务器端口、资源限制,以及尽力提供的实时资源使用情况。
响应
{
"data": {
"id": 1234,
"name": "Fred's Minecraft",
"service_status": "active",
"paused": false,
"game": { "slug": "minecraft", "name": "Minecraft", "runtime": "paper", "version": "1.21.4" },
"expires_at": "2026-11-01T00:00:00+00:00",
"address": "fredcraft.example.com",
"allocations": [
{ "ip": "203.0.113.7", "port": 25565, "primary": true, "notes": null }
],
"limits": {
"memory_mb": 4096,
"disk_mb": 25600,
"cpu_percent": 200
},
"resources": {
"current_state": "running",
"memory_bytes": 2147483648,
"cpu_absolute": 18.5,
"disk_bytes": 7300000000,
"network_rx_bytes": 12345678,
"network_tx_bytes": 87654321,
"uptime_ms": 3600000
}
}
}如果节点短暂不可达,resources 块可能为 null。请重试,或改看面板中的状态指示。
/api/v1/client/servers/{id}/powerscope: servers:control向服务器发送电源信号。仅在服务处于活跃状态时有效:已暂停、已取消或已暂停使用的服务会返回 409。
请求体
{
"signal": "start" // one of: "start", "stop", "restart", "kill"
}kill 会强制终止进程,不给游戏保存的机会。对有存档的游戏,请用 stop 正常关闭。
示例
curl -X POST https://serverprism.com/api/v1/client/servers/1234/power \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"signal":"restart"}'响应
{ "data": { "signal": "restart", "sent": true } }/api/v1/client/servers/{id}/commandscope: servers:control向运行中的服务器发送单条控制台命令(例如 say hello、stop、whitelist add Notch)。服务器必须正在运行,否则会返回 409 server_offline。
请求体
{
"command": "say Server restarting in 5 minutes"
}单行,最多 1024 个字符。换行和其他控制字符会被以 422 拒绝:每条命令发送一个请求。
响应
{ "data": { "command": "say Server restarting in 5 minutes", "sent": true } }/api/v1/client/servers/{id}/backupsscope: servers:read列出服务器的备份和你的备份名额。名额由你的所有服务器共享,并随套餐内存增长。
响应
{
"data": [
{
"uuid": "6f1c0e2a-...",
"name": "nightly",
"status": "completed", // "in_progress" | "completed" | "failed"
"size_bytes": 734003200,
"locked": false,
"created_at": "2026-09-30T03:00:00+00:00",
"completed_at": "2026-09-30T03:04:12+00:00"
}
],
"meta": { "quota": { "used": 2, "total": 3, "can_create_more": true, "is_trial": false } }
}/api/v1/client/servers/{id}/backupsscope: backups:create开始备份并立即返回 202。备份在后台运行:请轮询列表端点,直到 status 变为 completed 或 failed。每个备份占用一个名额;名额用完时返回 409 backup_limit_reached。试用套餐不含备份(403)。恢复和删除备份只能在控制台中进行。
请求体(可选)
{ "name": "before-1.21-update" }响应 (202)
{ "data": { "uuid": "9a2b...", "name": "before-1.21-update", "status": "in_progress", "size_bytes": 0, "locked": false, "created_at": "2026-10-01T12:00:00+00:00", "completed_at": null } }/api/v1/client/accountscope: account:read响应
{ "data": { "id": 42, "first_name": "Fred", "last_name": "Smith", "email": "fred@example.com", "email_verified": true, "created_at": "2025-03-01T10:00:00+00:00" } }/api/v1/client/servicesscope: billing:read你名下所有状态的服务,附带计费详情。可选过滤参数 ?status=,取值之一:pending、provisioning、active、suspended、cancelled、failed。
响应
{
"data": [
{
"id": 1234,
"name": "Fred's Minecraft",
"product": "Minecraft 4 GB",
"status": "active",
"paused": false,
"plan": { "name": "Monthly", "type": "recurring", "billing_period": 1, "billing_unit": "month" },
"quantity": 1,
"price": { "amount": "8.00", "currency": "EUR", "formatted": "€8.00" },
"next_due_date": "2026-11-01T00:00:00+00:00",
"cancellation_requested": false,
"cancellation_type": null,
"created_at": "2026-05-01T09:12:00+00:00"
}
],
"meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }
}/api/v1/client/invoicesscope: billing:read你的账单,最新的在前。可选过滤参数 ?status=pending|paid|cancelled。
响应
{
"data": [
{
"id": 5512,
"number": "SP-2026-05512",
"status": "pending",
"currency": "EUR",
"total": { "amount": "8.00", "currency": "EUR", "formatted": "€8.00" },
"tax": { "amount": "1.60", "currency": "EUR", "formatted": "€1.60" },
"remaining": { "amount": "8.00", "currency": "EUR", "formatted": "€8.00" },
"due_at": "2026-10-04T00:00:00+00:00",
"created_at": "2026-09-27T00:00:00+00:00",
"pdf_url": "https://serverprism.com/api/v1/client/invoices/5512/pdf",
"dashboard_url": "https://serverprism.com/invoices/SP-2026-05512"
}
],
"meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }
}要支付账单,请打开它的 dashboard_url。API 绝不会动用资金。
/api/v1/client/invoices/{id}scope: billing:read字段与列表相同,另加账单明细项。{id} 是数字 id,不是账单编号。
响应(节选)
{
"data": {
"id": 5512,
"status": "pending",
"items": [
{ "description": "Minecraft 4 GB (Oct 01, 2026 - Nov 01, 2026)", "quantity": 1, "unit_price": "8.00", "total": "8.00", "service_id": 1234 }
]
}
}/api/v1/client/invoices/{id}/pdfscope: billing:read以 PDF 下载账单(application/pdf),与控制台里的下载按钮是同一份文件。计入 control 速率限制分组。
curl -o invoice.pdf https://serverprism.com/api/v1/client/invoices/5512/pdf \
-H "Authorization: Bearer YOUR_TOKEN"/api/v1/client/ticketsscope: tickets:read你的支持工单,最近更新的在前。可选过滤参数 ?status=open|replied|closed。replied 表示我们的团队已回复,正在等你。
响应
{
"data": [
{
"id": 1301,
"subject": "Server lagging in the evening",
"status": "replied",
"priority": "medium",
"department": "Support",
"service_id": 1234,
"messages_count": 3,
"last_message_at": "2026-10-01T09:30:00+00:00",
"created_at": "2026-09-30T18:02:00+00:00",
"updated_at": "2026-10-01T09:30:00+00:00",
"dashboard_url": "https://serverprism.com/tickets/1301"
}
],
"meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }
}/api/v1/client/tickets/{id}scope: tickets:read工单及其对话,最早的消息在前。author 为 you 或 staff。附件只列出文件名;请在控制台下载。
响应(节选)
{
"data": {
"id": 1301,
"status": "replied",
"messages": [
{ "id": 9001, "author": "you", "author_name": "Fred Smith", "message": "TPS drops every evening", "attachments": [], "created_at": "2026-09-30T18:02:00+00:00" },
{ "id": 9007, "author": "staff", "author_name": "ServerPrism Support", "message": "We moved you to a quieter host...", "attachments": [], "created_at": "2026-10-01T09:30:00+00:00" }
]
}
}/api/v1/client/ticketsscope: tickets:write创建工单。department 必填,必须是控制台新建工单表单中显示的部门之一。priority 为 low(默认)、medium 或 high。service_id 可选,必须是你名下的服务之一。每个账户每 30 秒最多创建 1 个新工单。返回 201,响应体与获取工单相同。
请求体
{
"subject": "Server lagging in the evening",
"message": "TPS drops to ~12 between 19:00 and 22:00 CET.",
"department": "Support",
"priority": "medium",
"service_id": 1234
}/api/v1/client/tickets/{id}/messagesscope: tickets:write在你的某个工单中添加回复(最多 20,000 个字符)。回复已关闭的工单会重新打开它,与控制台一致。返回 201 及新消息。
请求体
{ "message": "Still happening tonight, see the timings report." }API 不支持的操作
API 有意不支持支付、取消、升级或降级服务、使用优惠券、删除或恢复备份以及删除文件。这些操作都在控制台中完成,确认之前你可以清楚看到它们会做什么。
版本管理
v1 命名空间是稳定的。不兼容的变更只会出现在新的命名空间(v2)中;我们可能在不另行通知的情况下为现有响应添加新字段,因此请让你的客户端忽略未知的键。
功能建议和错误报告:提交工单并注明“API”。