黑色星期五:新服务器使用优惠码 终身立减 25%。查看套餐

ServerPrism API

用代码控制你的服务器(状态、电源、控制台命令、备份),并在你自己的脚本、仪表盘和机器人中读取账单与支持工单。

在使用 Claude、Cursor、VS Code 或其他 AI 助手?用我们的 MCP 服务器连接它:同一个令牌,无需写代码。

端点路径、字段名、状态码和代码示例与你的代码所见完全一致,因此在所有语言中都保持英文。

本页内容

快速开始

  1. 登录你的 ServerPrism 账户。
  2. 打开账户 → API 凭据并创建一个令牌。
  3. 只选择你的集成所需的最小 scope 集合。
  4. 令牌显示时请只复制一次:我们从不以明文保存它,也无法找回。
  5. 将令牌作为 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 块。

列出服务器
GET/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"
    }
  ]
}
获取服务器
GET/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。请重试,或改看面板中的状态指示。

电源信号
POST/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 } }
发送命令
POST/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 } }
列出备份
GET/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 } }
}
创建备份
POST/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 } }
账户
GET/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" } }
服务(计费)
GET/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 }
}
列出账单
GET/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 绝不会动用资金。

获取账单
GET/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 }
    ]
  }
}
账单 PDF
GET/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"
列出工单
GET/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 }
}
获取工单
GET/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" }
    ]
  }
}
创建工单
POST/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
}
回复工单
POST/api/v1/client/tickets/{id}/messagesscope: tickets:write

在你的某个工单中添加回复(最多 20,000 个字符)。回复已关闭的工单会重新打开它,与控制台一致。返回 201 及新消息。

请求体

{ "message": "Still happening tonight, see the timings report." }

API 不支持的操作

API 有意不支持支付、取消、升级或降级服务、使用优惠券、删除或恢复备份以及删除文件。这些操作都在控制台中完成,确认之前你可以清楚看到它们会做什么。

版本管理

v1 命名空间是稳定的。不兼容的变更只会出现在新的命名空间(v2)中;我们可能在不另行通知的情况下为现有响应添加新字段,因此请让你的客户端忽略未知的键。

功能建议和错误报告:提交工单并注明“API”。