REST API

入口：https://api.vesselmcp.com。只读、需鉴权。exact path，不接受 query 参数。成功响应为 { "data": ... }。没有 CORS permission header，响应禁用缓存。

路由

方法	路径	成功 data
GET	/v1/vessels/{imo}	{ "vessel": 身份对象 }
GET	/v1/vessels/{imo}/recent-ports	{ "imo", "recentPorts", "fetchedAt" }

字段规则见 约定。

GET /v1/vessels/9331919
Authorization: Bearer vmcp_api_v1_<key-id>_<secret>

{
  "data": {
    "vessel": {
      "imo": "9331919",
      "name": "OCEAN HIRYU",
      "fetchedAt": "2026-09-06T01:02:03.456Z"
    }
  }
}

靠港：

GET /v1/vessels/9331919/recent-ports
Authorization: Bearer vmcp_api_v1_<key-id>_<secret>

{
  "data": {
    "imo": "9331919",
    "recentPorts": [],
    "fetchedAt": "2026-09-06T01:02:03.456Z"
  }
}

只接受 vmcp_api_v1_... key。MCP key 不能调用本服务。

限流

先按请求方 IP，鉴权成功后再按非敏感 key ID。限额按 Cloudflare location 计，不是全局计费配额。

阶段	限额
鉴权前，按 IP	每 60 秒 60 次
鉴权后，按 key ID	每 60 秒 30 次

超限返回 429 RATE_LIMITED 与 Retry-After: 60。身份与靠港各计一次。

错误

错误外形：{ "error": { "code", "message" } }。

校验顺序为：IP 限流、鉴权、key ID 限流、精确路径、HTTP 方法，最后检查 IMO 校验位和 query 参数。下表中的路由错误以已通过鉴权和两级限流为前提。例如，未鉴权请求访问未知路径通常先返回 401，不是 404；限流或服务异常也可能更早返回。

HTTP	error.code	何时
400	INVALID_REQUEST	GET 已匹配路由，但 IMO 校验位无效、为 0000000 或带 query 参数
401	UNAUTHORIZED	缺少或无效 API key
404	NOT_FOUND	路径不精确匹配上述任一路由，包括 IMO 段格式错误、尾斜杠或多余路径段
404	VESSEL_NOT_FOUND	身份真实未找到
405	METHOD_NOT_ALLOWED	已匹配路由，但方法不是 GET；未知路径优先返回 404
429	RATE_LIMITED	IP 或 key ID 超限
502	BACKEND_UNAVAILABLE	查询失败、超时或不合格结果
503	SERVICE_UNAVAILABLE	服务暂时不可用

靠港失败不会变成空数组或 VESSEL_NOT_FOUND。