参考 · API 文档

Cortex API 接入面，4 个协议。

本页讲：选哪个协议、第一个调用怎么发。完整参考在 docs.x.hiq.earth。

认证

§ I

一个 header。两条限制。

API 密钥目前不支持自助开通。发邮件到 info@hiqlcd.com，说明使用场景和所需协议；HiQ-AI 配置密钥并提供账户控制台链接。

拿到密钥后，所有 Cortex 端点统一使用同一个 header：

X-API-Key: sk_xxx

MCP 端点同时接受 Authorization: Bearer sk_xxx。不要在请求体或 URL query string 里传密钥——凡是进了日志或浏览器历史的凭据必须重置。

协议	Per-key	Per-IP
REST / AG-UI / A2A	300 req/min	500 req/min
MCP	—	100 req/min

超过任一限额返回 429 Too Many Requests。每把密钥在账户层级设有月度 LLM 成本上限。 401：密钥缺失、无效或已吊销。 403：当前订阅不覆盖所请求的数据源。

4 个协议

§ II

各取所需。

REST

POST https://x.hiqlcd.com/api/cortex/search

使用时机

有一批物料需要匹配，要拿回经 DQI 评分的 LCA 数据集候选——不需要流式，不需要客户端配置。后端批处理 job、CBAM 申报范围梳理、BOM 筛选流水线：发一个 POST，解析 JSON 响应即可。

Cortex 在内部完成查询拆解、向量检索、字段校验。响应包含 datasets 数组，每条含 name、loc、src、ver、model、dqi、gwp（非受限数据集才有）以及 fit 评级（high / medium / low）。加 stream=true 改为 SSE 事件流返回。

curl -s -X POST https://x.hiqlcd.com/api/cortex/search \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'message=stainless+steel+304&stream=false'

完整 REST 参考 →

MCP

POST https://x.hiqlcd.com/api/cortex/mcp (Streamable HTTP, JSON-RPC over SSE)

使用时机

你在使用 AI 编程助手——Cursor、Claude Desktop、Claude Code、Cline，或任何支持 Model Context Protocol 的客户端——并希望把 Cortex LCA 检索作为原生工具直接集成进去。

MCP 暴露 2 个工具：search_datasets（语义检索，返回 top-k 候选）和 lookup_datasets（按数据集 key 批量获取详情）。Claude Desktop、Cursor、Claude Code 使用同一份配置结构；仅文件路径不同。

// ~/.cursor/mcp.json  (或项目级 .cursor/mcp.json)
{
  "mcpServers": {
    "cortex": {
      "url": "https://x.hiqlcd.com/api/cortex/mcp",
      "headers": {
        "X-API-Key": "sk_xxx"
      }
    }
  }
}

完整 MCP 参考 →

AG-UI

POST https://x.hiqlcd.com/api/cortex/agui

使用时机

你在构建前端聊天界面，或对接支持 AG-UI 协议的 Agent 框架。一个 POST 返回 SSE 事件流：RUN_STARTED、TEXT_MESSAGE_CONTENT 增量、RUN_FINISHED。CORS 已开放，可以从浏览器直接调用。

thread_id 字段在多次调用之间保持会话连续性。用 @ag-ui/client 解析 SSE 流，无需自己实现事件状态机。

curl -sN -X POST https://x.hiqlcd.com/api/cortex/agui \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "X-API-Key: sk_xxx" \
  -d '{
    "thread_id": "thread-001",
    "run_id": "run-001",
    "messages": [
      {"id": "msg-1", "role": "user", "content": "Find datasets for polyethylene, GLO region"}
    ],
    "tools": [], "context": [], "state": {}
  }'

完整 AG-UI 参考 →

A2A

端点根前缀 · https://x.hiqlcd.com/api/cortex/a2a

使用时机

你的系统遵循 Google Agent-to-Agent 协议，需要把 Cortex Chat 注册为对等 Agent。先拉 agent card 做能力发现，实质性查询一律用 message:stream；仅不触发 LLM streaming 的短交互才可用 message:send。

响应为 SSE 流，每条是携带 TaskStatusUpdateEvent 和 TaskArtifactUpdateEvent 增量的 JSON-RPC 对象，直到 status.state 变为 completed。

# 发现 Agent 能力
curl -s https://x.hiqlcd.com/api/cortex/a2a/agents/chat/.well-known/agent-card.json \
  -H "X-API-Key: sk_xxx"

# 流式查询
curl -sN -X POST https://x.hiqlcd.com/api/cortex/a2a/agents/chat/v1/message:stream \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "X-API-Key: sk_xxx" \
  -d '{
    "jsonrpc": "2.0", "id": "req-1", "method": "message/stream",
    "params": {
      "message": {
        "messageId": "msg-1", "contextId": "ctx-001", "role": "user",
        "parts": [{"kind": "text", "text": "Carbon footprint data for polyethylene"}]
      }
    }
  }'

完整 A2A 参考 →

常见用法

§ III

按数据源和系统模型过滤。

在 REST 请求体中以 JSON 字符串形式传递 session_state，可以缩小检索范围。

session_state.sources 接受 "HiQLCD"、 "Ecoinvent:3.12.0"，或管道符分隔的多个值（"HiQLCD:1.4.0|Ecoinvent:3.12.0"）。
session_state.system_model 接受 cut_off、 apos 或 consequential。

两个字段默认为空（不应用过滤）。MCP 的 search_datasets 工具将 sources 作为直接参数暴露。

支持

§ IV

出问题怎么办。

认证报错、限流疑问、数据集覆盖范围——请在 GitHub Issues 提 Issue。账户、计费、申请新密钥相关，邮件至 info@hiqlcd.com。