第一个 API 调用 — 5 步端到端

10 分钟跑通从登录到问答的完整链路。假设服务部署在 https://<your-host>，已有 demo 账号。

1. 登录拿 Token

TOKEN=$(curl -sS -X POST https://<your-host>/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"demo","password":"<your-password>"}' \
  | jq -r .token)

echo $TOKEN  # eyJhbGc...

2. 创建一个图谱

GRAPH_ID=$(curl -sS -X POST https://<your-host>/api/graphs \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"hello-supply-chain","description":"快速入门图谱","template":"scor"}' \
  | jq -r .graph_id)

echo $GRAPH_ID  # kg_xxxxxx

template 可选 scor（SCOR 供应链）/ hrm（人力）/ supply-chain（通用）等，详见 GET /api/graphs/templates。

3. 导入一篇文档

JOB_ID=$(curl -sS -X POST "https://<your-host>/api/graphs/$GRAPH_ID/import-document" \
  -H "Authorization: Bearer $TOKEN" \
  -F file=@./annual-report.pdf \
  | jq -r .job_id)

echo $JOB_ID  # 异步任务 id

4. 轮询导入进度

while true; do
  STATUS=$(curl -sS https://<your-host>/api/tasks/$JOB_ID \
    -H "Authorization: Bearer $TOKEN" | jq -r .state)
  echo "state=$STATUS"
  [ "$STATUS" = "SUCCESS" ] || [ "$STATUS" = "FAILURE" ] && break
  sleep 5
done

SUCCESS 即文档已抽取实体关系入图谱（按 LLM 速度通常 30s-2min）。

5. 自然语言问答

curl -sS -X POST "https://<your-host>/api/graphs/$GRAPH_ID/query" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "query":"这家公司去年营业收入是多少？",
    "mode":"hybrid",
    "include_sources":true
  }' | jq

响应含 answer（Markdown 文本）+ sources（命中的文档片段 + 实体）。

复杂问题 → 走深度推理

简单事实查询用 /query 单轮 ~3-5s；复杂问题（风险 / 原因 / 瓶颈 / 预测）改用 /query/deep 走 Critic+Researcher 多轮迭代：

curl -sS -X POST "https://<your-host>/api/graphs/$GRAPH_ID/query/deep" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"query":"这条供应链有哪些单点风险？","max_rounds":3}' | jq

响应含 was_deep（是否走了迭代）+ rounds_used + reasoning_trace（每轮 critique + follow_up）。建议客户端超时设 180s（最长 3 轮 × 60s）。

进阶：Agent 集成

如果你想让 Claude Desktop / Cursor 直接调 GraphForge 跑指标 + 血缘 + RCA，跳到 MCP 概览 —— 不用走 REST，直接走 9 个 MCP tools。

看完整 API

API Reference — Scalar 渲染的 287 路由按 13 个 tag 分组，含每个 endpoint 的 curl 示例 + 错误码 + 试调按钮。