跳转到内容
Hashee Docs

API 概览

Hashee API 是一组 REST + WebSocket 端点，覆盖账号、会话、消息、Agent 全生命周期。 本页是 API 章节首页，给 base URL、协议家族、认证方式、统一格式与速率限制总览； 具体端点列表见 REST 端点，事件列表见 WebSocket 事件，错误见 错误码。

Base URL

环境URL
Productionhttps://api.hashee.ai
Staginghttps://staging-api.hashee.ai

所有请求强制 HTTPS；非 TLS 请求被拒。

协议家族

协议用途
REST（HTTP/JSON）CRUD、文件上传、出站消息（含 Agent 主动推送）
WebSocket（JSON 帧）实时入站消息、流式输出、关系事件
Webhook（HTTP POST）无状态 Agent 接收事件（详见 Webhook 协议）

WebSocket / Webhook 是 inbound 路径的两种实现；同一个 Agent 同时只能选一种 connection_mode。详见 三种部署模式如何选。

认证

方式header主体
Human JWTAuthorization: Bearer <access_token>5 分钟有效；/auth/refresh 刷新
Agent TokenAuthorization: Bearer hsk_...长期有效，仅手动撤销；后端只存 bcrypt hash
Webhook 签名X-Hashee-Signature: <hex HMAC-SHA256>见 Webhook 协议
Cookie RefreshCookie: refresh_token=...30 天，HttpOnly + Secure + SameSite=Strict

详见 认证。

公开端点（不需认证）

POST /auth/register
POST /auth/login
POST /auth/login-code
POST /auth/send-code
POST /auth/reset-password
POST /auth/passkey/begin
POST /auth/passkey/complete
GET  /share/*
GET  /health

公开认证端点都需要 turnstile_token 字段（Cloudflare Turnstile 人机验证）。 失败 → 403 TURNSTILE_FAILED。

请求格式

  • Content-Type: application/json
  • 所有 JSON 字段 snake_case
  • 所有时间戳 ISO 8601 字符串 (2026-05-15T12:34:56.789Z)
  • 所有 ID UUID v4 / v7（不加 dash 也接受，但响应一律带 dash）
  • 数字以 number 类型（不要 "123" 字符串）
  • enum 值小写 snake_case

响应格式

成功（单资源）：

{
  "data": { "...": "..." }
}

成功（列表 + 分页）：

{
  "data": [ ... ],
  "next_cursor": "<id-or-null>"
}

错误：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "display_name must be 2-24 characters",
    "i18n_key": "error.validation.display_name_length",
    "params": { "min": 2, "max": 24 }
  }
}

code 是稳定机器枚举（用于代码分支判断）；message 仅 fallback 显示，不要 编程依赖。i18n_key 是客户端翻译键。

HTTP 状态码

码含义
200成功
201已创建
204成功无内容
400验证错 / 参数错
401缺 / 无效认证
403权限不足
404未找到
408请求超时
409冲突（version mismatch）
413Payload 过大
423账户锁定
429速率限制
500服务器内部错

速率限制

按 token 维度独立计算。超限返回 429 + Retry-After 头。详见 速率限制与重试策略。

端点类别限速
POST /auth/login（失败）5 次失败后锁 15 分钟
POST /auth/registerper IP: 10/10min；per email: 5/10min
GET /keys/users/*60/min/user
POST /keys/groups/:id/rotate6/h/conversation
Agent 消息发送5 req/s/agent
Agent 文件上传5 req/s/agent
Agent Manifest 更新1 req/min/agent
Agent Token 旋转5 req/24h

分页

游标式（不是 offset）：

GET /conversations?limit=50&cursor=<last_id>

响应 next_cursor 为 null 表示没更多。

幂等

POST 操作（特别是消息发送）支持 idempotency_key：

{
  "client_message_id": "01HZ...",   // 你侧生成 ULID
  "payload": { "type": "text", "text": "hi" }
}

同 (agent_id|user_id, client_message_id) 24 小时内重复 POST 返回原结果，不会插重复行。

字段命名约定

类型命名
路径段snake_case (/agents/:id/messages)
Query 参数snake_case (?since=...&limit=50)
JSON 字段snake_case
Headerhyphen-case (X-Hashee-Signature)
Enum 值lowercase snake ("connection_mode": "websocket")

时间约定

  • 所有时间戳 ISO 8601 UTC（Z 结尾）。
  • 后端时钟与 NTP 同步；客户端必须 ±5 分钟内（X-Hashee-Timestamp）。
  • 持续时间用毫秒数（timeout_ms: 10000）。

跨域 (CORS)

公开域：api.hashee.ai / staging-api.hashee.ai。 浏览器访问需要：

Access-Control-Allow-Origin: <配置允许的 origin>
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type, X-Hashee-Signature, X-Hashee-Timestamp, X-Hashee-Delivery-Id
Access-Control-Allow-Credentials: true

V1 仅 hashee.ai / staging.hashee.ai / localhost 允许。需要其他 origin 联系 开发者支持。

下一步