{"openapi":"3.1.0","info":{"title":"JobsLoop Open API","version":"1.0.0","summary":"JobsLoop 招聘开放 API v1","description":"JobsLoop 面向招聘者的官方 Open API。基础地址为 https://api2.jobsloop.cn。 所有接口使用 Authorization: Bearer hecn_live_… 鉴权；写入类接口建议携带 Idempotency-Key 头防重复扣费。 仅面向招聘者角色开放；按量付费：先扣促销发放的正式赠送积分、再注册赠送积分、再资源包、最后付费积分；余额不足返回 402。 接入方式：REST（本规范）、Agent Function Calling（见 https://jobsloop.cn/docs/api-reference）、MCP Streamable HTTP（https://api2.jobsloop.cn/api/mcp）。","contact":{"name":"JobsLoop 开放平台","url":"https://jobsloop.cn/docs/api-reference"}},"servers":[{"url":"https://api2.jobsloop.cn","description":"生产环境"}],"tags":[{"name":"resume","description":"简历解析与识别"},{"name":"matching","description":"人岗匹配与批量筛选"},{"name":"jd","description":"JD 优化"}],"security":[{"BearerKey":[]}],"paths":{"/api/open/v1/resumes/parse":{"post":{"operationId":"parseResume","tags":["resume"],"summary":"简历解析","description":"将 PDF 简历解析为结构化纯文本，适合 ATS、校招系统与人才库做入库前预处理。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fileDataUrl"],"properties":{"fileDataUrl":{"type":"string","maxLength":25000000,"description":"PDF 的 base64 data URL，形如 data:application/pdf;base64,…"},"fileName":{"type":["string","null"],"maxLength":240,"description":"文件名，仅用于审计展示"},"pages":{"type":["integer","null"],"minimum":1,"maximum":10000,"description":"显式指定页数；不传则按 PDF 内部 /Type /Page 估算"},"timeoutMs":{"type":["integer","null"],"minimum":10000,"maximum":660000,"description":"单次解析超时毫秒数"}}}}}},"responses":{"200":{"description":"执行成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"request_id":{"type":"string"},"data":{"type":"object","properties":{"text":{"type":"string","description":"识别出的简历纯文本"},"pages":{"type":"integer"}},"required":["text","pages"]},"usage":{"type":"object","properties":{"pages":{"type":"integer"},"provider":{"const":"jobsloop"},"model":{"const":"resume-recognition"}}},"billing":{"type":"object","properties":{"billed_point_cents":{"type":"integer","description":"本次实际扣费的 point_cents（100 point_cents = 1 积分）"},"billed_points":{"type":"number","description":"本次扣费积分数（展示值，含小数）"},"balance_point_cents":{"type":"integer","description":"扣费后的账户余额 point_cents"},"balance_points":{"type":"number","description":"扣费后余额积分展示值"},"resource_point_cents":{"type":"integer","description":"资源包抵扣的 point_cents"},"resource_points":{"type":"number","description":"资源包抵扣积分展示值"}},"required":["billed_point_cents","billed_points","balance_point_cents","balance_points","resource_point_cents","resource_points"]}},"required":["ok","request_id","data","usage","billing"]}}}},"400":{"description":"参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"缺少或无效 API Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"余额不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"仅招聘者角色可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"请求体超限","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"超出日/月请求限额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerKey":[]}]}},"/api/open/v1/matches/resume-jd":{"post":{"operationId":"matchResumeToJd","tags":["matching"],"summary":"人岗匹配","description":"输入 JD 与简历文本，返回匹配分、优势、差距、关键词覆盖与下一步复核建议。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["resume_text","jd_text"],"properties":{"resume_text":{"type":"string","minLength":1,"maxLength":12000,"description":"简历正文（也接受 camelCase resumeText）"},"jd_text":{"type":"string","minLength":10,"maxLength":8000,"description":"岗位描述正文（也接受 camelCase jdText）"},"job_title":{"type":["string","null"],"maxLength":200,"description":"岗位名称，辅助匹配定向"}}}}}},"responses":{"200":{"description":"执行成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"request_id":{"type":"string"},"data":{"type":"object","description":"匹配结果：score / strengths / gaps / keywords / recommendation 等","additionalProperties":true},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}},"billing":{"type":"object","properties":{"billed_point_cents":{"type":"integer","description":"本次实际扣费的 point_cents（100 point_cents = 1 积分）"},"billed_points":{"type":"number","description":"本次扣费积分数（展示值，含小数）"},"balance_point_cents":{"type":"integer","description":"扣费后的账户余额 point_cents"},"balance_points":{"type":"number","description":"扣费后余额积分展示值"},"resource_point_cents":{"type":"integer","description":"资源包抵扣的 point_cents"},"resource_points":{"type":"number","description":"资源包抵扣积分展示值"}},"required":["billed_point_cents","billed_points","balance_point_cents","balance_points","resource_point_cents","resource_points"]}},"required":["ok","request_id","data","usage","billing"]}}}},"400":{"description":"参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"缺少或无效 API Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"余额不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"仅招聘者角色可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"超出日/月请求限额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerKey":[]}]}},"/api/open/v1/jds/optimize":{"post":{"operationId":"optimizeJd","tags":["jd"],"summary":"JD 优化","description":"输入岗位描述或要点要求，生成结构更完整、更合规、更有吸引力的 JD 文案。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","anyOf":[{"required":["jd_text"]},{"required":["job_title"]},{"required":["requirements"]}],"properties":{"jd_text":{"type":["string","null"],"maxLength":8000,"description":"原始 JD 正文"},"job_title":{"type":["string","null"],"maxLength":200,"description":"岗位名称"},"requirements":{"type":["string","null"],"maxLength":8000,"description":"用人要求要点"},"location":{"type":["string","null"],"maxLength":120},"experience":{"type":["string","null"],"maxLength":120}}}}}},"responses":{"200":{"description":"执行成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"request_id":{"type":"string"},"data":{"type":"object","description":"优化后的 JD 内容","additionalProperties":true},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"}}},"billing":{"type":"object","properties":{"billed_point_cents":{"type":"integer","description":"本次实际扣费的 point_cents（100 point_cents = 1 积分）"},"billed_points":{"type":"number","description":"本次扣费积分数（展示值，含小数）"},"balance_point_cents":{"type":"integer","description":"扣费后的账户余额 point_cents"},"balance_points":{"type":"number","description":"扣费后余额积分展示值"},"resource_point_cents":{"type":"integer","description":"资源包抵扣的 point_cents"},"resource_points":{"type":"number","description":"资源包抵扣积分展示值"}},"required":["billed_point_cents","billed_points","balance_point_cents","balance_points","resource_point_cents","resource_points"]}},"required":["ok","request_id","data","usage","billing"]}}}},"400":{"description":"参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"缺少或无效 API Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"余额不足","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"仅招聘者角色可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"超出日/月请求限额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerKey":[]}]}},"/api/open/v1/batches/screen":{"post":{"operationId":"startBatchScreening","tags":["matching"],"summary":"批量人岗筛选（异步）","description":"提交一批候选人简历文本与 JD，后台逐条完成 AI 匹配并排序；首响应立即返回 batch_id，用 GET /batches/{id} 轮询结果。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["resumes","jd_text"],"properties":{"jd_text":{"type":"string","minLength":10,"maxLength":8000,"description":"目标岗位 JD（也接受 camelCase jdText）"},"label":{"type":["string","null"],"maxLength":120,"description":"批次备注名"},"resumes":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["text"],"properties":{"label":{"type":["string","null"],"maxLength":120,"description":"候选人标识（默认“候选人 N”）"},"text":{"type":"string","minLength":1,"maxLength":12000}}}}}}}}},"responses":{"200":{"description":"执行成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"request_id":{"type":"string"},"data":{"type":"object","properties":{"batch_id":{"type":"string","format":"uuid"},"status":{"const":"running"},"total":{"type":"integer"}}},"billing":{"type":"object","properties":{"billed_point_cents":{"type":"integer","description":"本次实际扣费的 point_cents（100 point_cents = 1 积分）"},"billed_points":{"type":"number","description":"本次扣费积分数（展示值，含小数）"},"balance_point_cents":{"type":"integer","description":"扣费后的账户余额 point_cents"},"balance_points":{"type":"number","description":"扣费后余额积分展示值"},"resource_point_cents":{"type":"integer","description":"资源包抵扣的 point_cents"},"resource_points":{"type":"number","description":"资源包抵扣积分展示值"}}},"estimated_point_cents":{"type":"integer","description":"预估总扣费 = 候选人数 × 100 point_cents"},"billing_note":{"type":"string"}}}}}},"400":{"description":"参数校验失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"缺少或无效 API Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"402":{"description":"余额不足以覆盖整批任务","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"仅招聘者角色可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"超出日/月请求限额","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerKey":[]}]}},"/api/open/v1/batches/{id}":{"get":{"operationId":"getBatchScreeningResult","tags":["matching"],"summary":"查询批量筛选结果","description":"轮询批量任务状态；任务 running 超过 stale 阈值会被自动回收标 failed，不会永远挂起。","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"batch_id"}],"responses":{"200":{"description":"执行成功","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"const":true},"data":{"type":"object","properties":{"batch_id":{"type":"string"},"status":{"enum":["running","done","partial","failed"]},"total":{"type":"integer"},"completed":{"type":"integer"},"label":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"billing_status":{"type":"string"},"billing":{"type":"object","properties":{"billed_point_cents":{"type":"integer","description":"本次实际扣费的 point_cents（100 point_cents = 1 积分）"},"billed_points":{"type":"number","description":"本次扣费积分数（展示值，含小数）"},"balance_point_cents":{"type":"integer","description":"扣费后的账户余额 point_cents"},"balance_points":{"type":"number","description":"扣费后余额积分展示值"},"resource_point_cents":{"type":"integer","description":"资源包抵扣的 point_cents"},"resource_points":{"type":"number","description":"资源包抵扣积分展示值"}}},"items":{"type":"array","items":{"type":"object","properties":{"candidate_label":{"type":"string"},"score":{"type":["integer","null"],"minimum":0,"maximum":100},"tags":{"type":"array","items":{"type":"string"}},"recommendation":{"type":"string"}}},"description":"按 score 降序排列的候选人榜单"},"summary":{"type":["object","null"],"description":"整体结论与 Top 理由","additionalProperties":true}}}}}}}},"401":{"description":"缺少或无效 API Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"仅招聘者角色可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"batch 不存在或不属于当前用户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"security":[{"BearerKey":[]}]}}},"webhooks":{},"components":{"securitySchemes":{"BearerKey":{"type":"http","scheme":"bearer","bearerFormat":"hecn_live_*","description":"在「用户中心 → API 密钥」创建，明文仅展示一次。"}},"schemas":{"Billing":{"type":"object","properties":{"billed_point_cents":{"type":"integer","description":"本次实际扣费的 point_cents（100 point_cents = 1 积分）"},"billed_points":{"type":"number","description":"本次扣费积分数（展示值，含小数）"},"balance_point_cents":{"type":"integer","description":"扣费后的账户余额 point_cents"},"balance_points":{"type":"number","description":"扣费后余额积分展示值"},"resource_point_cents":{"type":"integer","description":"资源包抵扣的 point_cents"},"resource_points":{"type":"number","description":"资源包抵扣积分展示值"}},"required":["billed_point_cents","billed_points","balance_point_cents","balance_points","resource_point_cents","resource_points"]},"ErrorEnvelope":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"string","description":"稳定错误码，如 invalid_input / unauthorized / insufficient_points"},"message":{"type":"string","description":"中文可读说明"},"detail":{"description":"400 时 zod 校验细节"},"required_point_cents":{"type":"integer","description":"402 时所需 point_cents"},"balance_point_cents":{"type":"integer","description":"402 时当前余额"},"resource_point_cents":{"type":"integer","description":"402 时资源包余额"}},"required":["ok","error"]}}}}