接入文档

概览

一把密钥能用两种方式接：自己的系统调 HTTP 开放接口，或者让 AI 助手通过 MCP 直接调工具。返回的都是脱敏的公开卡，联系方式要对方同意后才交换。

快速开始

四步，十分钟以内能跑通第一次调用。

1. 拿测试密钥

   机构填一张申请（单位、联系人、要接的能力、用途），1 个工作日内联系你，审核通过后发测试密钥；个人开发者登录并实名后，在「设置 · 开放能力」里自助生成，当场可用。

   申请测试密钥
   终端

   复制

   export GEEKHUB_KEY="gk_test_..."   # 把密钥放环境变量，不要写进代码

2. 配置客户端

   用 AI 助手的，把 MCP 地址填进客户端；只用 HTTP 的跳过这一步。

   客户端配置Claude CodeCursorVS Code只支持本地进程的客户端（老版 Claude 桌面版等）

   复制

   claude mcp add --transport http geekhub https://geekwork.cc/api/open/v1/mcp --header "Authorization: Bearer <你的密钥>"

3. 第一次调用

   用一句话找机会。测试密钥回的是 30 张测试卡里对得上的几张，结构和正式环境一样。

   请求curlPythonNode

   复制

   curl -X POST 'https://geekwork.cc/api/open/v1/match' \  -H 'Authorization: Bearer $GEEKHUB_KEY' \  -H 'Content-Type: application/json' \  -d '{"need":"想找苏州的视觉质检场景","limit":10}'

   返回（测试密钥）

   复制

   {  "matches": [    {      "type": "tech_scene",      "board_label": "商业机会",      "card_code": "ctestcardaab",      "title": "示例：工厂视觉质检试点场景",      "city": "苏州",      "verified": true,      "reason": "这是沙箱示例卡，不对应真实内容",      "connect_url": "https://geekwork.cc/c/sandbox-1",      "amount_text": "50–200 万",      "deadline": "2026-12-20",      "cover_url": "https://geekwork.cc/api/v1/scene/sample_neutral-2.webp"    }  ]}

4. 换正式密钥

   测试跑通后开通正式环境：平台审核 → 合同与报价单 → 对公转账 → 到账开通，发正式密钥（gk_live_ 开头）。把环境变量换掉即可，地址和代码都不用改。正式环境每天有免费检索，对接成功才计费。

测试与正式

测试密钥和正式密钥调的是同一个地址、同一套字段，区别只在数据和计费。

• 测试密钥（gk_test_）：只回测试卡，标题以「示例：」开头；不计费、不写库、不占免费检索次数。
• 正式密钥（gk_live_）：回真实公开卡；每天有免费检索次数，对接成功才计费。

限流与额度

超了会回 429，返回里带 retry_at（最早可以重试的时间）。

POST /match

用一句话说明你要找什么，返回最多 10 张候选卡；每张卡的 reason 是一句理由（对得上哪几项由规则判定，带 reason_ai: true 的由 AI 写成句子），connect_url 是网页链接（URL Link，不提供小程序码）。

请求

curl -X POST 'https://geekwork.cc/api/open/v1/match' \  -H 'Authorization: Bearer $GEEKHUB_KEY' \  -H 'Content-Type: application/json' \  -d '{"need":"想找苏州的视觉质检场景","limit":10}'

{  "matches": [    {      "type": "tech_scene",      "board_label": "商业机会",      "card_code": "ctestcardaab",      "title": "示例：工厂视觉质检试点场景",      "city": "苏州",      "verified": true,      "reason": "这是沙箱示例卡，不对应真实内容",      "connect_url": "https://geekwork.cc/c/sandbox-1",      "amount_text": "50–200 万",      "deadline": "2026-12-20",      "cover_url": "https://geekwork.cc/api/v1/scene/sample_neutral-2.webp"    }  ]}

常见错误

出错时返回 4xx / 5xx 状态码，返回内容里写着错误码、原因说明，以及哪几项缺了或填错了。

POST /demands

提交一条需求，审核通过后进入对应板块；每个合作方每天最多 20 条（可被调低），所属组织需已有负责人账号。

请求

curl -X POST 'https://geekwork.cc/api/open/v1/demands' \  -H 'Authorization: Bearer $GEEKHUB_KEY' \  -H 'Content-Type: application/json' \  -d '{"title":"采购一批视觉质检相机","detail":"产线检测用，需要 20 台工业相机，希望本月内有供应商联系我们。","kind":"purchase","region":"苏州","idempotency_key":"demo-0001"}'

{  "request_id": "req_sandbox_0001",  "demand_id": "dmd_test_0a1b2c3d4e",  "status": "sandbox",  "created": true}

常见错误

出错时返回 4xx / 5xx 状态码，返回内容里写着错误码、原因说明，以及哪几项缺了或填错了。

GET /connections/:code

查一次对接的当前状态。开了「找人找资源」或「代提需求」任一项都能调。

请求

curl -X GET 'https://geekwork.cc/api/open/v1/connections/c_sandbox_0001' \  -H 'Authorization: Bearer $GEEKHUB_KEY'

{  "request_id": "req_sandbox_0002",  "connection_id": "c_sandbox_0001",  "status": "initiated",  "created_at": "2026-10-25T09:30:00.000Z",  "decided_at": null,  "achieved_at": null,  "billing": {    "state": "frozen"  }}

常见错误

出错时返回 4xx / 5xx 状态码，返回内容里写着错误码、原因说明，以及哪几项缺了或填错了。

POST /supply

新增一条供给。

常见错误

出错时返回 4xx / 5xx 状态码，返回内容里写着错误码、原因说明，以及哪几项缺了或填错了。

PUT /supply/:external_id

按你自己的编号更新一条供给。

常见错误

出错时返回 4xx / 5xx 状态码，返回内容里写着错误码、原因说明，以及哪几项缺了或填错了。

DELETE /supply/:external_id

按你自己的编号下架一条供给。

常见错误

出错时返回 4xx / 5xx 状态码，返回内容里写着错误码、原因说明，以及哪几项缺了或填错了。

POST /mcp

智能体工具入口（MCP，Streamable HTTP 无状态，JSON-RPC 2.0，一次一条消息）：先 initialize，再 tools/list 看你这把密钥能用的工具；共 7 个：find_people_resources（找机会和资源）、get_card（看卡片详情）、match_policies（查政策）、today_updates（今日更新）、find_incubators（找孵化器）、submit_demand（代提需求）、get_connection_status（查对接状态）。find_people_resources、match_policies、find_incubators 各计入一次免费检索；submit_demand 必须带 user_confirmed:true，个人密钥不能用。测试密钥的回包见文档「沙箱」一节。

常见错误

出错时返回 4xx / 5xx 状态码，返回内容里写着错误码、原因说明，以及哪几项缺了或填错了。

这个接口没有专门要说明的错误，通用错误见「错误」一节。

GET /cards/:code

看卡片详情（与智能体工具 get_card 同一处理器）：code 是候选卡的 card_code；在孵项目、找合伙人只回板块、阶段档、标签和链接。不占免费检索。

常见错误

出错时返回 4xx / 5xx 状态码，返回内容里写着错误码、原因说明，以及哪几项缺了或填错了。

GET /today

今日更新（与 today_updates 同一处理器）：查询参数 board、limit；各板块今日与本周新增数按访客口径分档。不占免费检索。

常见错误

出错时返回 4xx / 5xx 状态码，返回内容里写着错误码、原因说明，以及哪几项缺了或填错了。

GET /incubators

找孵化器（与 find_incubators 同一处理器）：查询参数 city、industry、limit；回公开站点与入孵入口，不出负责人和联系人。占 1 次免费检索。

常见错误

出错时返回 4xx / 5xx 状态码，返回内容里写着错误码、原因说明，以及哪几项缺了或填错了。

MCP 总览

智能体工具走 MCP。七个工具和开放接口共用同一套处理器，返回同一套字段。

七个工具

接入方要守的规则

• 任何返回都不带联系方式；用户想联系时，把对接页链接交给用户本人点开确认。
• 在孵项目、找合伙人只给脱敏标签和阶段档。
• reason_ai 为 true 的理由由 AI 写成，展示给最终用户时要标出（AI）。
• 卡片来源只写「发布方自填」或「平台整理」。

错误分三层

find_people_resources

找机会和资源

用一句话或一段项目介绍，在平台公开卡里挑候选（客户、试点、技术成果、服务商、投资方、孵化器、在孵项目、合伙人；政策用 match_policies），每张带推荐理由和对接页链接。占 1 次免费检索。

参数

常见错误

出错时接口照样返回成功状态，具体原因写在返回内容的 error 里：错误码、哪几项填错了、多久后能重试。

get_card

看卡片详情

用户追问某一张卡时调：传 card_code，回这张卡的公开字段与重新签发的对接页链接（7 天有效）。在孵项目、找合伙人只回板块、阶段档、标签和链接。不占免费检索。

参数

常见错误

出错时接口照样返回成功状态，具体原因写在返回内容的 error 里：错误码、哪几项填错了、多久后能重试。

match_policies

查政策

按地区、行业、阶段配已公开的政策，回前 5 条与自测链接；三项都对不上时回只差一项的。占 1 次免费检索。

参数

常见错误

出错时接口照样返回成功状态，具体原因写在返回内容的 error 里：错误码、哪几项填错了、多久后能重试。

today_updates

今日更新

今天有什么新机会、新政策：各板块今日和本周新增数（访客口径分档）与最新几条。不占免费检索。

参数

常见错误

出错时接口照样返回成功状态，具体原因写在返回内容的 error 里：错误码、哪几项填错了、多久后能重试。

find_incubators

找孵化器

按城市、方向找孵化器：回公开站点和入孵入口，有当期批次时带批次名与截止日。不出负责人和联系人。占 1 次免费检索。

参数

常见错误

出错时接口照样返回成功状态，具体原因写在返回内容的 error 里：错误码、哪几项填错了、多久后能重试。

submit_demand

代提需求

代用户提交一条需求（进审核队列，不会立刻发布）。必须先把内容念给用户确认，确认后才带 user_confirmed: true 调；缺项或取值不对时会说明要改哪个字段。需要机构密钥。

参数

常见错误

出错时接口照样返回成功状态，具体原因写在返回内容的 error 里：错误码、哪几项填错了、多久后能重试。

get_connection_status

查对接状态

查一次对接的当前状态（只能查你这把密钥发起的）。不占免费检索。

参数

常见错误

出错时接口照样返回成功状态，具体原因写在返回内容的 error 里：错误码、哪几项填错了、多久后能重试。

Skill 接入包

Skill 包告诉 AI 什么时候该用这些工具、怎么把候选讲给用户、哪些话不能说，包里还带接口描述和工具对照表。

下载 Skill 接入包

各客户端的界面文字以当前版本为准；支持 OpenAPI 的平台可导入接口描述。

回调与事件

在工作台填一个回调地址、勾上要订阅的事件，发生变化时平台会 POST 一条消息给你。消息里只有编号、状态和时间，不带联系方式和对方的原话。

• 没收到 2xx 会自动重试：间隔 0、1、5、15、30、60、180、360 分钟，共 8 次。
• 30 天内的事件可以在工作台重放。
• 同一事件可能送达不止一次，用事件编号去重。

合作方可订阅

孵化器可订阅

回调长什么样

请求体是 JSON；请求头带事件编号、事件名和签名。签名 = 用你的签名密钥对「时间戳.原始正文」做 HMAC-SHA256；换密钥后 24 小时内新旧两个签名都会带上，对得上任意一个就行。

POST <your-callback-url>Content-Type: application/json; charset=utf-8User-Agent: GeekHub-Webhooks/1X-Geekhub-Event-Id: <event-id>X-Geekhub-Event-Type: booking.confirmedX-Geekhub-Signature: t=<unix-seconds>,v1=<signature>

对接状态

对接从发起到结束会经过这些状态；回调与查询接口里的 status 就是这里的值。

错误

出了错先看错误码：大多数是参数没填对或者调得太快，按「怎么处理」改了再调就行。

{  "code": "validation_failed",  "message": "need: 2-500",  "request_id": "req_01M68K2Q4S6U8W0Y2A4C6E8G0J",  "missing": [    "need"  ]}