API 参考 / join-requests

申请加入项目

POST /api/v1/join-requests · createJoinRequest

申请加入一个自己还没有权限的项目（B-00284 / 老单 B-00024）。需要已登录且邮箱已验证 ——这道闸挡的是批量注册小号灌申请。

恒返回 202，绝不透露这个子域上有没有项目。 项目壳可见性（B-00199）的既有结论是： 跨组织访客对一个项目子域一律拿 404，因为「返回 403」本身就等于确认「这个子域上确实有个 项目」，是跨租户信息泄漏。申请入口不能把这个结论捅穿，所以：子域存在与否、申请有没有真的 送到某个管理员面前，调用方一概看不出来。子域解析不到项目时申请照样入库（projectId 留空、 只记下用户填的 subdomainPrefix），它不会出现在任何管理员的列表里，到期自动失效。

反滥用（阈值全落 platform_settings 的 join_request_limits，运营后台可运行时调）： ① 同一项目同时只能有一条 pending（唯一索引钉死，重复提交返回 202 但不新增行）； ② 每人同时最多 maxPendingPerUser 条 pending； ③ 每人每 24 小时最多 maxSubmissionsPerDay 次提交——撤销与被驳回的同样计数， 否则「申请→撤销→再申请」可以无限刷，这是只限并发 pending 数挡不住的绕过路径； ④ 同一项目被驳回后 rejectCooldownDays 天内不能再申请，避免驳回即重申的骚扰循环； ⑤ 另有按客户端 IP 的闸，防同一人批量注册账号后横向刷。 触到 ②③④ 任一条返回 429 并带 Retry-After；不返回 403——403 会随子域是否存在而 变化，又把存在性泄漏回去了。

鉴权：项目 API Token（Authorization: Bearer wfp_…）。详见 Agent 接入。

请求体

subdomainPrefix（必填）

string

message

string

响应字段 · 202

id（必填）

string

status（必填）

enum —— 申请恒从待审批起步；取值：pending

错误

• 401：Problem 错误响应
• 403：Problem 错误响应
• 422：Problem 错误响应
• 429：Problem 错误响应

请求示例（curl）

curl -X POST "https://你的项目.workflow.games/api/v1/join-requests" \
  -H "Authorization: Bearer wfp_…" \
  -H "content-type: application/json" \
  --data '{"subdomainPrefix":"示例文本","message":"示例文本"}'

响应示例

HTTP/1.1 202
{
  "id": "018f3c2e-0000-7000-8000-000000000000",
  "status": "pending"
}

合同真值：OpenAPI 3.1（0.1.0）。

相关：Agent 接入指南 · 使用指南 · API 参考索引