Reference · API docs

The Cortex API surface, four protocols.

This page tells you which protocol to use and how to make your first call. The full reference lives at docs.x.hiq.earth.

Authentication

§ I

One header. Two limits.

Keys are not self-serve at this time. Email info@hiqlcd.com with your use case and preferred protocol; HiQ-AI provisions a key and shares the account console link.

Once you have a key, every Cortex endpoint accepts one header:

X-API-Key: sk_xxx

MCP also accepts Authorization: Bearer sk_xxx. Never pass your key in the request body or URL query string — any key that enters a log or browser history must be rotated.

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

Exceeding either limit returns 429 Too Many Requests. Each key carries a monthly LLM cost budget set at the account level. 401: key missing, invalid, or revoked. 403: subscription does not cover the requested data source.

Four protocols

§ II

When to reach for each.

REST

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

When to use

You have a list of materials and need matched, DQI-scored LCA dataset candidates back in one call — no streaming required, no client configuration. REST is the right choice for backend batch jobs, CBAM scope walkthroughs, and BOM screening pipelines where you POST a query and parse the JSON response.

Cortex handles query decomposition, vector retrieval, and field verification internally. The response carries a "datasets" array; each entry includes name, loc, src, ver, model, dqi, gwp (when the dataset is non-restricted), and a fit rating (high / medium / low). Add stream=true to receive an SSE event stream instead.

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'

Full REST reference →

MCP

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

When to use

You are connecting an AI coding assistant — Cursor, Claude Desktop, Claude Code, Cline, or any client that speaks Model Context Protocol — and want Cortex LCA search available as a native tool inside that client.

MCP exposes two tools: search_datasets (semantic retrieval, returns top-k candidates) and lookup_datasets (batch detail fetch by dataset key). Claude Desktop, Cursor, and Claude Code all use the same config block; only the file path differs.

// ~/.cursor/mcp.json  (or project-level .cursor/mcp.json)
{
  "mcpServers": {
    "cortex": {
      "url": "https://x.hiqlcd.com/api/cortex/mcp",
      "headers": {
        "X-API-Key": "sk_xxx"
      }
    }
  }
}

Full MCP reference →

AG-UI

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

When to use

You are building a front-end chat interface or connecting an Agent framework that speaks the AG-UI protocol. One POST returns a server-sent event stream — RUN_STARTED, TEXT_MESSAGE_CONTENT deltas, RUN_FINISHED. CORS is open; you can call this from a browser directly.

The thread_id field carries session continuity across calls. Use @ag-ui/client to parse the SSE stream without writing the event machine by hand.

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": {}
  }'

Full AG-UI reference →

A2A

Root prefix · https://x.hiqlcd.com/api/cortex/a2a

When to use

Your system follows the Google Agent-to-Agent protocol and you want to register Cortex Chat as a peer agent. A2A uses JSON-RPC 2.0 over HTTP. Fetch the agent card for capability discovery, then call message:stream for substantive queries — the non-streaming message:send works only for short exchanges that do not trigger the LLM streaming path.

The response is an SSE stream of JSON-RPC objects carrying TaskStatusUpdateEvent and TaskArtifactUpdateEvent increments until status.state reaches completed.

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

# Stream a query
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"}]
      }
    }
  }'

Full A2A reference →

Common patterns

§ III

Filter by source and system model.

Pass session_state as a JSON string in your REST body to scope results.

session_state.sources accepts "HiQLCD", "Ecoinvent:3.12.0", or a pipe-separated list ("HiQLCD:1.4.0|Ecoinvent:3.12.0").
session_state.system_model accepts cut_off, apos, or consequential.

Both fields default to empty (no filter applied). The MCP search_datasets tool exposes sources as a direct parameter.

Support

§ IV

When something breaks.

Authentication errors, rate-limit questions, dataset coverage gaps — open a ticket on the GitHub issues tracker. For account, billing, or new-key requests, email info@hiqlcd.com.