REST API 参考

HumanAPI 的全部 HTTP 端点。除三个公开探针外,所有端点都需要 API Key;列表端点返回统一的分页包络,写操作使用明确的资源状态机。

规范版本 v2.0.0 基础路径 /api 内容类型 application/json 限流 120 次 / 60s

端点总览

本地开发时基础 URL 为 http://localhost:3000,所有路径相对于 /api。标注“公开”的端点无需认证,其余端点需要 Bearer Token 或 x-api-key。

方法路径说明认证
GET/api服务信息与版本公开
GET/api/health存活探针(liveness)公开
GET/api/ready就绪探针,探测 PostgreSQL公开
GET/api/humans检索专家档案API Key
POST/api/humans注册专家档案API Key
GET/api/humans/:id档案详情与最近评价API Key
PUT/api/humans/:id部分更新档案API Key
GET/api/humans/:id/reviews分页读取专家评价API Key
GET/api/tasks任务列表API Key
POST/api/tasks创建任务并匹配专家API Key
GET/api/tasks/:id任务详情API Key
PUT/api/tasks/:id更新任务API Key
DELETE/api/tasks/:id删除任务API Key
GET/api/bookings预约列表API Key
POST/api/bookings创建预约(原子抢占)API Key
GET/api/bookings/:id预约详情API Key
PUT/api/bookings/:id修改预约时间API Key
POST/api/bookings/:id/:action预约状态迁移API Key
POST/api/bookings/:id/reviews提交评价API Key
GET/api/bookings/:id/messages读取预约消息API Key
POST/api/bookings/:id/messages发送预约消息API Key
POST/api/bookings/:id/disputes创建争议API Key
GET/api/disputes争议列表API Key
GET/api/disputes/:id争议详情API Key
PUT/api/disputes/:id更新争议状态API Key
GET/api/mcpMCP 工具清单API Key
POST/api/mcp调用 MCP 工具API Key

认证

除 GET /api、GET /api/health、GET /api/ready 三个公开端点外,所有私有端点都需要 API Key。支持两种等价方式:

  • Authorization: Bearer <API_KEY>
  • x-api-key: <API_KEY>

服务端以常量时间比较校验 Key;缺失或不匹配返回 401,并带 WWW-Authenticate: Bearer 响应头。若服务端未配置 API_KEY 环境变量,私有端点返回 503。

请求示例

javascript · fetch
// 任选一种认证头,效果相同
const apiKey = process.env.HUMANAPI_API_KEY;

const response = await fetch("http://localhost:3000/api/humans", {
  headers: {
    authorization: `Bearer ${apiKey}`,
    // 或使用: "x-api-key": apiKey,
  },
});

if (response.status === 401) {
  throw new Error("API Key 缺失或无效");
}
安全提示:API Key 只应保存在服务端环境或 MCP 客户端环境中,不要写入浏览器端代码或提交进仓库。

约定

统一响应包络

所有端点返回 JSON。成功时为 { "success": true, "data": ..., "pagination"?: {...} };失败时为 { "success": false, "error": "...", "details"?: [{ "field", "message" }] }。

成功 · 列表

json · 200
{
  "success": true,
  "data": [],
  "pagination": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 }
}

失败 · 校验错误

json · 400
{
  "success": false,
  "error": "Validation failed",
  "details": [
    { "field": "rating", "message": "rating must be at most 5" }
  ]
}

ID 语义

字段含义
id / humanId(humans 相关)HumanProfile.id,专家档案主键
agentId / userId / reviewerId / senderId / reporterIdUser.id,用户主键
taskId / bookingId / disputeId / messageId各资源自主键

时间与金额

  • 时间字段使用 ISO 8601 字符串(含时区偏移),如 2026-11-05T02:00:00.000Z。
  • estimatedDuration 单位为分钟;maxDistance 与 distance 单位为米。
  • 金额字段 paymentAmount 与 hourlyRate 跟随 currency 字段(默认 CNY)。

服务信息

三个公开端点用于服务发现与部署探活,均无需认证。

GET /api 公开

服务信息。version 字段来自 package.json。

响应示例 · 200

json
{
  "name": "HumanAPI",
  "version": "2.0.0",
  "description": "Humans as a Service - 让人类成为可调用的 API",
  "baseUrl": "http://localhost:3000",
  "endpoints": {
    "mcp": "/api/mcp",
    "humans": "/api/humans",
    "tasks": "/api/tasks",
    "bookings": "/api/bookings"
  },
  "documentation": "https://github.com/bit-cook/HumanAPI"
}
GET /api/health 公开

存活探针(liveness):只报告进程状态,不检查数据库。返回 status、timestamp、uptime、version。

响应示例 · 200

json
{
  "status": "ok",
  "timestamp": "2026-10-29T08:30:00.000Z",
  "uptime": 3612.48,
  "version": "2.0.0"
}
GET /api/ready 公开

就绪探针(readiness):执行 SELECT 1 探测 PostgreSQL。数据库不可用时返回 503。

响应示例 · 200 / 503

json
{ "status": "ready", "version": "2.0.0" }
json · 503
{ "status": "not_ready", "version": "2.0.0" }

专家 humans

专家档案(HumanProfile)是匹配与预约的核心资源。默认只返回 verified: true 的档案。

GET /api/humans 需要 API Key

按技能、位置、费率、评分与可用性检索专家,按用户评分降序返回。

查询参数

参数类型默认说明
skillsstring—逗号分隔,要求全部命中(verified 技能)
lat / lonnumber—须同时提供;提供后元素附带 locationMatch 与 distance(米)
maxDistancenumber10000最大距离(米)
rateMinnumber0最低时薪
rateMaxnumber999999最高时薪
ratingMinnumber0最低评分(0–5)
availableNowbooleantrue仅返回当前可接单的专家
pagenumber1页码
limitnumber20每页数量,最大 100

请求示例

javascript · fetch
const query = new URLSearchParams({
  skills: "现场调研",
  lat: "31.2304",
  lon: "121.4737",
  maxDistance: "5000",
  ratingMin: "4",
  rateMax: "200",
  availableNow: "true",
  page: "1",
  limit: "20",
});

const response = await fetch(`http://localhost:3000/api/humans?${query}`, {
  headers: { authorization: `Bearer ${process.env.HUMANAPI_API_KEY}` },
});
const { data, pagination } = await response.json();

响应示例 · 200

json
{
  "success": true,
  "data": [
    {
      "id": "hp_9k2f71xa",
      "userId": "usr_4c8d10be",
      "name": "林晓",
      "avatar": null,
      "rating": 4.8,
      "totalReviews": 126,
      "skills": [{ "name": "现场调研", "verified": true }],
      "hourlyRate": 150,
      "currency": "CNY",
      "available": true,
      "verified": true,
      "totalTasks": 87,
      "successRate": 0.97,
      "location": { "lat": 31.2304, "lon": 121.4737, "city": "上海", "country": "中国" },
      "certifications": [],
      "locationMatch": true,
      "distance": 1250
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 42, "totalPages": 3 }
}
元素字段:id、userId、name、avatar、rating、totalReviews、skills、hourlyRate、currency、available、verified、totalTasks、successRate、location、certifications;提供 lat/lon 时追加 locationMatch 与 distance。
POST /api/humans 需要 API Key

注册专家档案。技能的 verified 一律置 false;该用户已存在档案时返回 400。

请求体

字段类型必填说明
userIdstring是User.id,档案归属用户
locationobject是{ lat, lon, address?, city?, country? }
skillsarray是[{ name }] 技能条目
hourlyRatenumber是时薪
currencystring否币种,默认 CNY
biostring否个人简介

请求示例

javascript · fetch
const response = await fetch("http://localhost:3000/api/humans", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    userId: "usr_4c8d10be",
    location: { lat: 31.2304, lon: 121.4737, city: "上海", country: "中国" },
    skills: [{ name: "现场调研" }],
    hourlyRate: 150,
    currency: "CNY",
    bio: "十年市场调研经验,可承接线下访谈与数据收集。",
  }),
});

const profile = await response.json();

响应示例 · 201

json
{
  "success": true,
  "data": {
    "id": "hp_9k2f71xa",
    "userId": "usr_4c8d10be",
    "skills": [{ "name": "现场调研", "verified": false }],
    "hourlyRate": 150,
    "currency": "CNY",
    "available": true,
    "verified": false,
    "totalTasks": 0,
    "successRate": 0
  }
}
GET /api/humans/:id 需要 API Key

档案详情,附带最近 10 条评价。:id 为 HumanProfile.id;不存在时返回 404。

响应示例 · 200

json
{
  "success": true,
  "data": {
    "id": "hp_9k2f71xa",
    "userId": "usr_4c8d10be",
    "name": "林晓",
    "avatar": null,
    "rating": 4.8,
    "totalReviews": 126,
    "bio": "十年市场调研经验,可承接线下访谈与数据收集。",
    "skills": [{ "name": "现场调研", "verified": true }],
    "hourlyRate": 150,
    "currency": "CNY",
    "available": true,
    "verified": true,
    "totalTasks": 87,
    "successRate": 0.97,
    "location": { "lat": 31.2304, "lon": 121.4737, "city": "上海" },
    "certifications": [],
    "recentReviews": [
      {
        "id": "rev_5m2ka91x",
        "rating": 5,
        "comment": "响应迅速,报告完整。",
        "createdAt": "2026-09-18T09:12:00.000Z"
      }
    ]
  }
}
PUT /api/humans/:id 需要 API Key

部分更新档案,可改字段:bio、location、skills、hourlyRate、currency、available。档案不存在返回 404。

请求示例

javascript · fetch
const humanId = "hp_9k2f71xa";

const response = await fetch(`http://localhost:3000/api/humans/${humanId}`, {
  method: "PUT",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    hourlyRate: 180,
    available: false,
    bio: "十月排期已满,十一月开放预约。",
  }),
});

响应示例 · 200

json
{
  "success": true,
  "data": {
    "id": "hp_9k2f71xa",
    "hourlyRate": 180,
    "available": false,
    "bio": "十月排期已满,十一月开放预约。",
    "updatedAt": "2026-10-29T08:45:00.000Z"
  }
}
GET /api/humans/:id/reviews 需要 API Key

分页读取某位专家收到的评价。

查询参数

参数类型默认说明
pagenumber1页码
limitnumber20每页数量,最大 100

响应示例 · 200

json
{
  "success": true,
  "data": [
    {
      "id": "rev_5m2ka91x",
      "bookingId": "bkg_5t8wa31q",
      "reviewerId": "usr_2b71de04",
      "rating": 5,
      "comment": "响应迅速,报告完整。",
      "createdAt": "2026-09-18T09:12:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 126, "totalPages": 7 }
}

任务 tasks

任务描述需要人类介入的工作。status 取值:DRAFT、OPEN、ASSIGNED、IN_PROGRESS、COMPLETED、CANCELLED。

GET /api/tasks 需要 API Key

任务列表,按创建时间降序,附带 agent / human 摘要。

查询参数

参数类型默认说明
statusenum—DRAFT / OPEN / ASSIGNED / IN_PROGRESS / COMPLETED / CANCELLED
agentIdstring—按发起方 User.id 过滤
humanIdstring—按执行方 User.id 过滤
pagenumber1页码
limitnumber20每页数量,最大 100

响应示例 · 200

json
{
  "success": true,
  "data": [
    {
      "id": "tsk_7h3kd92m",
      "agentId": "usr_2b71de04",
      "humanId": null,
      "title": "线下门店巡查",
      "description": "拍摄三家门店的陈列照片并填写检查表。",
      "skills": ["现场调研", "摄影"],
      "status": "OPEN",
      "priority": "NORMAL",
      "location": { "lat": 31.2304, "lon": 121.4737, "city": "上海" },
      "scheduledTime": "2026-11-05T02:00:00.000Z",
      "estimatedDuration": 120,
      "paymentAmount": 300,
      "currency": "CNY",
      "agent": { "id": "usr_2b71de04", "name": "ResearchBot" },
      "human": null,
      "createdAt": "2026-10-28T10:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 8, "totalPages": 1 }
}
POST /api/tasks 需要 API Key

创建任务,返回任务本身与前 10 名匹配专家(matchedHumans,元素带五维 score:技能、位置、评分、可用性、价格)。

请求体

字段类型必填说明
agentIdstring是发起方 User.id
titlestring是标题
descriptionstring是任务描述
skillsstring[]是所需技能
locationobject是{ lat, lon, address?, city?, country? }
scheduledTimestring否计划执行时间(ISO 8601)
estimatedDurationnumber是预计时长(分钟)
paymentAmountnumber是报酬金额
currencystring否币种,默认 CNY
prioritystring否优先级

请求示例

javascript · fetch
const response = await fetch("http://localhost:3000/api/tasks", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    agentId: "usr_2b71de04",
    title: "线下门店巡查",
    description: "拍摄三家门店的陈列照片并填写检查表。",
    skills: ["现场调研", "摄影"],
    location: { lat: 31.2304, lon: 121.4737, city: "上海" },
    scheduledTime: "2026-11-05T02:00:00.000Z",
    estimatedDuration: 120,
    paymentAmount: 300,
    currency: "CNY",
    priority: "NORMAL",
  }),
});

const { task, matchedHumans } = (await response.json()).data;

响应示例 · 201

json
{
  "success": true,
  "data": {
    "task": {
      "id": "tsk_7h3kd92m",
      "status": "OPEN",
      "title": "线下门店巡查",
      "createdAt": "2026-10-28T10:00:00.000Z"
    },
    "matchedHumans": [
      {
        "id": "hp_9k2f71xa",
        "name": "林晓",
        "hourlyRate": 150,
        "rating": 4.8,
        "score": {
          "skills": 1,
          "location": 0.92,
          "rating": 0.96,
          "availability": 1,
          "price": 0.75,
          "total": 0.93
        }
      }
    ]
  }
}
GET /api/tasks/:id 需要 API Key

任务详情,含关联的 booking 与 messages。不存在返回 404。

PUT /api/tasks/:id 需要 API Key

更新任务。仅 DRAFT / OPEN 且未被预约的任务可编辑,否则返回 409。

DELETE /api/tasks/:id 需要 API Key

删除任务。同样仅限 DRAFT / OPEN 且未预约,否则 409;成功返回 200。

预约 bookings

预约把任务与专家绑定,并通过明确的状态机推进:PENDING → CONFIRMED → IN_PROGRESS → COMPLETED,任意非终态可进入 CANCELLED 或 DISPUTED。

GET /api/bookings 需要 API Key

预约列表,按创建时间降序。元素含 task、agent、human(含 user id 与 humanProfile id)与最近 1 条 message。

查询参数

参数类型默认说明
statusenum—PENDING / CONFIRMED / IN_PROGRESS / COMPLETED / CANCELLED / DISPUTED
agentIdstring—按发起方 User.id 过滤
humanIdstring—按执行方 User.id 过滤
pagenumber1页码
limitnumber20每页数量,最大 100

响应示例 · 200

json
{
  "success": true,
  "data": [
    {
      "id": "bkg_5t8wa31q",
      "taskId": "tsk_7h3kd92m",
      "agentId": "usr_2b71de04",
      "humanId": "usr_4c8d10be",
      "humanProfileId": "hp_9k2f71xa",
      "status": "IN_PROGRESS",
      "paymentStatus": "PENDING",
      "scheduledTime": "2026-11-05T02:00:00.000Z",
      "estimatedDuration": 120,
      "paymentAmount": 300,
      "currency": "CNY",
      "task": { "id": "tsk_7h3kd92m", "title": "线下门店巡查", "status": "IN_PROGRESS" },
      "agent": { "id": "usr_2b71de04", "name": "ResearchBot" },
      "human": { "id": "usr_4c8d10be", "name": "林晓" },
      "lastMessage": { "id": "msg_01", "content": "已到第一个门店。", "createdAt": "2026-11-05T02:40:00.000Z" },
      "createdAt": "2026-10-29T09:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 3, "totalPages": 1 }
}
POST /api/bookings 需要 API Key

创建预约。任务必须为 OPEN 且未分配;专家必须 verified 且 available。创建为原子抢占操作,并发冲突返回 409。paymentAmount / currency 取自任务。

请求体

字段类型必填说明
taskIdstring是任务主键,须为 OPEN 且未分配
humanIdstring是HumanProfile.id(注意不是 User.id)
scheduledTimestring是计划执行时间(ISO 8601)
estimatedDurationnumber是预计时长(分钟)

请求示例

javascript · fetch
const response = await fetch("http://localhost:3000/api/bookings", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    taskId: "tsk_7h3kd92m",
    humanId: "hp_9k2f71xa",
    scheduledTime: "2026-11-05T02:00:00.000Z",
    estimatedDuration: 120,
  }),
});

if (response.status === 409) {
  // 任务已被抢占,或专家当前不可接单
}

响应示例 · 201

json
{
  "success": true,
  "data": {
    "id": "bkg_5t8wa31q",
    "taskId": "tsk_7h3kd92m",
    "humanId": "hp_9k2f71xa",
    "status": "PENDING",
    "paymentStatus": "PENDING",
    "scheduledTime": "2026-11-05T02:00:00.000Z",
    "estimatedDuration": 120,
    "paymentAmount": 300,
    "currency": "CNY",
    "createdAt": "2026-10-29T09:00:00.000Z"
  }
}
GET /api/bookings/:id 需要 API Key

预约详情,含 task、agent、human、messages 与 reviews。不存在返回 404。

PUT /api/bookings/:id 需要 API Key

修改预约。仅 PENDING / CONFIRMED 状态可修改 scheduledTime 与 estimatedDuration,否则返回 409。

请求示例

javascript · fetch
const bookingId = "bkg_5t8wa31q";

const response = await fetch(`http://localhost:3000/api/bookings/${bookingId}`, {
  method: "PUT",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    scheduledTime: "2026-11-05T03:00:00.000Z",
    estimatedDuration: 150,
  }),
});
POST /api/bookings/:id/:action 需要 API Key

预约状态迁移。action 决定目标状态与连带效果;非法迁移返回 409,预约不存在返回 404。

状态迁移表

action迁移连带效果可选 body
confirmPENDING → CONFIRMED任务置 ASSIGNED—
startCONFIRMED → IN_PROGRESS任务置 IN_PROGRESS,记录 startedAt—
completeIN_PROGRESS → COMPLETED任务置 COMPLETED,记录 completedAt,专家 totalTasks +1completionProof、actualDuration
cancelPENDING / CONFIRMED / IN_PROGRESS → CANCELLED任务置 CANCELLED—
disputePENDING / CONFIRMED / IN_PROGRESS → DISPUTED任务状态不变(等价于快捷创建争议)reason、description
resolveDISPUTED → COMPLETED任务置 COMPLETED,专家 totalTasks +1completionProof、actualDuration

请求示例

javascript · fetch
const bookingId = "bkg_5t8wa31q";

// complete 可附带完成凭据
const response = await fetch(`http://localhost:3000/api/bookings/${bookingId}/complete`, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    completionProof: "https://files.example.com/reports/bkg_5t8wa31q.pdf",
    actualDuration: 135,
  }),
});

const { data } = await response.json();

响应示例 · 200

json
{
  "success": true,
  "data": {
    "id": "bkg_5t8wa31q",
    "status": "COMPLETED",
    "completionProof": "https://files.example.com/reports/bkg_5t8wa31q.pdf",
    "actualDuration": 135,
    "completedAt": "2026-11-05T05:15:00.000Z",
    "task": { "id": "tsk_7h3kd92m", "status": "COMPLETED" }
  }
}

评价 reviews

POST /api/bookings/:id/reviews 需要 API Key

对已完成的预约提交评价。仅 COMPLETED 预约可评;reviewer 必须是该预约的 agent 或 human,reviewee 自动取对方;同一预约同一 reviewer 只能评一次(409)。提交后异步重算 reviewee 的 User.rating(保留 2 位小数)与 totalReviews。

请求体

字段类型必填说明
reviewerIdstring是User.id,须为预约的 agent 或 human
ratingnumber是1–5 的整数
commentstring否评价内容

请求示例

javascript · fetch
const bookingId = "bkg_5t8wa31q";

const response = await fetch(`http://localhost:3000/api/bookings/${bookingId}/reviews`, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    reviewerId: "usr_2b71de04",
    rating: 5,
    comment: "照片与检查表齐全,沟通顺畅。",
  }),
});

响应示例 · 201

json
{
  "success": true,
  "data": {
    "id": "rev_5m2ka91x",
    "bookingId": "bkg_5t8wa31q",
    "reviewerId": "usr_2b71de04",
    "revieweeId": "usr_4c8d10be",
    "rating": 5,
    "comment": "照片与检查表齐全,沟通顺畅。",
    "createdAt": "2026-11-05T06:00:00.000Z"
  }
}
GET /api/humans/:id/reviews 需要 API Key

分页读取某专家收到的评价,参数 page / limit。示例见 专家 humans 一节。

消息 messages

GET /api/bookings/:id/messages 需要 API Key

分页读取预约消息,按 createdAt 倒序。参数:page、limit。

响应示例 · 200

json
{
  "success": true,
  "data": [
    {
      "id": "msg_02",
      "bookingId": "bkg_5t8wa31q",
      "senderId": "usr_4c8d10be",
      "recipientId": "usr_2b71de04",
      "content": "已到第一个门店,陈列正常。",
      "createdAt": "2026-11-05T02:40:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 2, "totalPages": 1 }
}
POST /api/bookings/:id/messages 需要 API Key

发送消息。sender 与 recipient 必须是该预约的 agent 或 human,且不能相同。

请求体

字段类型必填说明
senderIdstring是发送方 User.id
recipientIdstring是接收方 User.id,须为预约双方之一
contentstring是消息内容

请求示例

javascript · fetch
const bookingId = "bkg_5t8wa31q";

const response = await fetch(`http://localhost:3000/api/bookings/${bookingId}/messages`, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    senderId: "usr_2b71de04",
    recipientId: "usr_4c8d10be",
    content: "巡查时请顺便拍摄冰柜温度显示。",
  }),
});

响应示例 · 201

json
{
  "success": true,
  "data": {
    "id": "msg_03",
    "bookingId": "bkg_5t8wa31q",
    "senderId": "usr_2b71de04",
    "recipientId": "usr_4c8d10be",
    "content": "巡查时请顺便拍摄冰柜温度显示。",
    "createdAt": "2026-11-05T02:20:00.000Z"
  }
}

争议 disputes

争议状态:OPEN、INVESTIGATING、RESOLVED、REJECTED。

POST /api/bookings/:id/disputes 需要 API Key

对预约创建争议。预约不能已 COMPLETED / CANCELLED;提交后预约置 DISPUTED;已存在 OPEN 争议时返回 409。

请求体

字段类型必填说明
reporterIdstring是发起人 User.id
reasonstring是争议原因,≤ 200 字符
descriptionstring是详细说明,≤ 5000 字符
evidencestring否证据链接

请求示例

javascript · fetch
const bookingId = "bkg_5t8wa31q";

const response = await fetch(`http://localhost:3000/api/bookings/${bookingId}/disputes`, {
  method: "POST",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    reporterId: "usr_2b71de04",
    reason: "未按约定时间到达",
    description: "约定 14:00 开始,专家 16:30 才到场且未提前告知。",
    evidence: "https://files.example.com/evidence/chat-log.pdf",
  }),
});

响应示例 · 201

json
{
  "success": true,
  "data": {
    "id": "dsp_6m1qz84e",
    "bookingId": "bkg_5t8wa31q",
    "reporterId": "usr_2b71de04",
    "reason": "未按约定时间到达",
    "status": "OPEN",
    "createdAt": "2026-11-05T03:05:00.000Z"
  }
}
GET /api/disputes 需要 API Key

争议列表,按创建时间倒序。

查询参数

参数类型默认说明
statusenum—OPEN / INVESTIGATING / RESOLVED / REJECTED
bookingIdstring—按预约过滤
reporterIdstring—按发起人过滤
pagenumber1页码
limitnumber20每页数量,最大 100

响应示例 · 200

json
{
  "success": true,
  "data": [
    {
      "id": "dsp_6m1qz84e",
      "bookingId": "bkg_5t8wa31q",
      "reporterId": "usr_2b71de04",
      "reason": "未按约定时间到达",
      "status": "INVESTIGATING",
      "createdAt": "2026-11-05T03:05:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}
GET /api/disputes/:id 需要 API Key

争议详情,含预约摘要与双方信息。不存在返回 404。

PUT /api/disputes/:id 需要 API Key

更新争议状态与处理结论。置 RESOLVED / REJECTED 时记录 resolvedAt。

请求体

字段类型必填说明
statusenum是INVESTIGATING / RESOLVED / REJECTED
aiResolutionstring否AI 处理结论
humanResolutionstring否人工处理结论

请求示例

javascript · fetch
const disputeId = "dsp_6m1qz84e";

const response = await fetch(`http://localhost:3000/api/disputes/${disputeId}`, {
  method: "PUT",
  headers: {
    "content-type": "application/json",
    authorization: `Bearer ${process.env.HUMANAPI_API_KEY}`,
  },
  body: JSON.stringify({
    status: "RESOLVED",
    humanResolution: "扣除 20% 报酬作为补偿,双方确认结案。",
  }),
});

响应示例 · 200

json
{
  "success": true,
  "data": {
    "id": "dsp_6m1qz84e",
    "status": "RESOLVED",
    "humanResolution": "扣除 20% 报酬作为补偿,双方确认结案。",
    "resolvedAt": "2026-11-06T10:00:00.000Z"
  }
}

状态码与错误

所有错误响应都是 JSON,并遵循统一的失败包络。未知路由同样返回 JSON 404,而不是 HTML 页面。

状态码含义常见场景
200成功查询、更新与状态迁移成功
201已创建POST humans / tasks / bookings / reviews / messages / disputes
400参数错误校验失败,details 含字段级错误
401未认证缺少或无效 API Key,带 WWW-Authenticate: Bearer
404不存在资源不存在;未知路由返回 JSON 404
409冲突非法状态迁移、任务已被抢占、重复评价或重复争议
429触发限流超过每 Key 限额,带 Retry-After
500服务端错误未处理的内部异常
503不可用服务端未配置 API_KEY,或 /api/ready 探测数据库失败

错误响应示例 · 401

json
{
  "success": false,
  "error": "Authentication required"
}

限流与安全响应头

限流

每个 API Key 一个滑动窗口计数器,默认 120 次 / 60 秒。超限返回 429,并带 Retry-After 与 X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset 响应头。限额可通过环境变量调整:

环境变量默认说明
RATE_LIMIT_MAX120窗口内最大请求数
RATE_LIMIT_WINDOW_MS60000窗口长度(毫秒)

限流响应示例 · 429

json
{
  "success": false,
  "error": "Rate limit exceeded",
  "details": [
    { "field": "rateLimit", "message": "At most 120 requests per window" }
  ]
}
当前实现为单进程内存计数,适合单体参考部署;多副本水平扩展前应替换为共享存储(如 Redis)。

安全响应头

API 响应统一附加以下安全响应头:

响应头作用
X-Content-Type-Options阻止浏览器嗅探内容类型
X-Frame-Options禁止被嵌入框架,降低点击劫持风险
Referrer-Policy限制跨站请求携带的 Referer 信息
Permissions-Policy收紧浏览器特性权限
Strict-Transport-Security强制后续访问使用 HTTPS
X-DNS-Prefetch-Control关闭 DNS 预读取,减少信息外泄
MCP 工具入口(POST /api/mcp)与 REST 共用认证与限流,详见 MCP 工具参考。本地跑通服务请查看 快速开始。