API 文档

认证与访问范围

下列所有接口都需要请求头 Authorization: Bearer <token>。令牌是创建时生成的 64 位小写十六进制字符串，不能用网页登录 Cookie 代替。发送 JSON 时加上 Content-Type: application/json。

令牌可读取所属账户的项目和监控、创建项目和监控、发起重新检测。访问其他账户的资源与访问不存在的资源均返回 404。当前版本不提供修改或删除项目、修改或删除监控的用户 API。

请将令牌保存在本机环境变量或密钥管理工具中，不要放在网页前端或公开仓库中。撤销后，使用旧令牌的请求返回 401。

接口一览

表中路径均相对于 /api/v1。

快速开始：列出项目，再添加网站

以下示例用于 macOS / Linux 终端。先把 YOUR_API_TOKEN 换成刚创建的令牌；示例中的项目 ID 1 和监控 ID 123 需替换为实际响应中的 ID。创建请求会写入账户，并占用监控额度。

1. 配置环境变量并列出项目

export OKUPTIME_API_TOKEN='YOUR_API_TOKEN'
export OKUPTIME_API_BASE='https://www.okuptime.com/api/v1'

curl --fail-with-body "$OKUPTIME_API_BASE/projects" \
  -H "Authorization: Bearer $OKUPTIME_API_TOKEN"

{"data":[{"id":1,"name":"公司网站"}]}

2. 按需创建项目

curl --fail-with-body "$OKUPTIME_API_BASE/projects" \
  -H "Authorization: Bearer $OKUPTIME_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"公司网站"}'

3. 添加监控

curl --fail-with-body "$OKUPTIME_API_BASE/monitors" \
  -H "Authorization: Bearer $OKUPTIME_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://example.com","project_id":1,"description":"首页","monitor_interval":600}'

成功返回 201 和新监控的 data.id。首次证书与可用性检测在后台执行，创建成功不代表网站可访问或检测已完成。

4. 读取详情，或提交一次重新检测

curl --fail-with-body "$OKUPTIME_API_BASE/monitors/123" \
  -H "Authorization: Bearer $OKUPTIME_API_TOKEN"

curl --fail-with-body -X POST "$OKUPTIME_API_BASE/monitors/123/check" \
  -H "Authorization: Bearer $OKUPTIME_API_TOKEN"

{"data":{"id":123,"check_status":"checking"}}

重新检测返回 202 Accepted，表示已提交任务。稍后再次请求详情获取结果；本接口不会同步等待检测完成，请避免高频轮询。

参数与分页

创建项目：POST /projects

name 必填，必须是字符串，去除首尾空白后长度为 1–255 个字符。新项目始终属于令牌所属账户。

添加监控：POST /monitors

url · 必填字符串

建议传入完整的公网 HTTPS 地址，如 https://example.com:8443/health。地址会按站点规则清洗并规范为 HTTPS；端口从 URL 读取，缺省为 443。不能包含用户名或密码；请使用公网目标，不支持本机或内网监控。

project_id · 可选正整数

必须属于当前账户。省略时使用该账户按 ID 排序的第一个项目；没有项目时返回 422 project_required。不存在或属于其他账户的项目返回 404。

description · 可选字符串

监控的备注说明。

monitor_interval · 可选整数，单位为秒

省略时为 600。当前免费版支持 600 / 1800 / 3600，专业版另支持 60 / 300；必须是当前账户套餐允许的档位，超限返回 422。监控数量也受账户额度限制，查看套餐。

同一项目内，同域名（不区分大小写）和同端口的监控视为重复，即使 URL 路径不同也返回 409 duplicate_monitor。

监控列表：GET /monitors 或 GET /projects/:project_id/monitors

每页最多 100 条，按 ID 升序排列。可选查询参数 after_id 必须为正整数。将上一页的 next_cursor 作为下一页的 after_id；当游标为 null 时结束。按项目查询时，翻页应保留同一个项目路径。

curl --fail-with-body "$OKUPTIME_API_BASE/projects/1/monitors?after_id=123" \
  -H "Authorization: Bearer $OKUPTIME_API_TOKEN"

GET /monitors?project_id=1 不会按项目筛选；请使用上方带项目 ID 的路径。项目列表 GET /projects 返回全部项目，不使用游标分页。

响应与检测状态

成功响应使用 {"data": ...}。监控列表另含 next_cursor；详情与创建接口的监控对象包含以下字段，尚未产生的检测结果可能为 null。

{"data":[],"next_cursor":null}

监控设置

id、project_id、url、description、monitor_enabled、monitor_interval、created_at。

证书检测

check_status：pending / checking / completed / failed / unknown；checked_at 为最近证书检测时间。completed 表示检测流程完成，不能单凭此值判断网站在线。

网站可用性

uptime_status：unknown / up / pending / partial / incomplete / down，分别表示未知、在线、待确认、部分异常、结果不完整、离线。另含 last_uptime_check_at、last_status_code、last_response_time_ms（毫秒）。

接口当前不返回证书到期时间、完整证书详情或逐节点检测明细；这些信息可在网站监控详情页查看。HTTP 请求成功只表示 API 调用成功，判断被监控网站状态应读取检测字段与对应时间。

错误与限流

项目接口与监控接口分别按来源 IP 限制每分钟最多 60 次请求；重新检测另限每分钟最多 10 次，也计入监控接口额度。同一类接口中，同一出口 IP 的多个令牌共享限制，超限返回 429，请降低请求频率并稍后重试。

{"error":{"code":"validation_failed","message":"参数校验失败","details":{"monitor_interval":["不支持的检查频率"]}}}

上方为错误结构示例，具体 message 与字段提示以响应为准；details 仅在部分校验错误中提供。