Context Compiler

When to use this API

Use the Context Compiler's APIs when your applications, analysts or AI agents need answers from one governed view of your enterprise data, instead of querying each source system on its own.

In the console, the Context Compiler connects your systems, files and databases, resolves the same customer, supplier, asset or employee across them, reads the data in your domain's terms and compiles one context graph. To serve a graph to your systems, open it and choose Data Lens for your website: the platform makes the graph's Data Lens (a deployed, versioned view of the graph), deploys it and gives you its id and an API key. Every API on this page is called on that Data Lens.

Authentication

Every request carries the Data Lens's API key. You get one when you choose Data Lens for your website, and you can issue more, rotate or revoke them in the console. A key opens this one Data Lens only, is shown once (only a hash of it is kept) and can be set to expire. Keys start with ok_live_.

x-ok-api-key: ok_live_xxxxxxxxxxxxxxxxxxxxxxxx

x-ok-api-key: ok_live_xxxxxxxxxxxxxxxxxxxxxxxx
Authorization: Bearer ok_live_xxxxxxxxxxxxxxxxxxxxxxxx

Parameters

Path

Body of POST /ask

Request

curl -X POST https://okp.openknowra.ai/workstudio/api/v2/published/$LENS_ID/ask \
  -H "x-ok-api-key: $OPENKNOWRA_LENS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"How many sites have an active critical alarm?"}'

import os, json, urllib.request

url = "https://okp.openknowra.ai/workstudio/api/v2/published/" + os.environ["LENS_ID"] + "/ask"
req = urllib.request.Request(
    url,
    data=json.dumps({"question": "How many sites have an active critical alarm?"}).encode(),
    headers={"x-ok-api-key": os.environ["OPENKNOWRA_LENS_KEY"], "Content-Type": "application/json"},
    method="POST")
print(json.load(urllib.request.urlopen(req, timeout=60)))

const url = `https://okp.openknowra.ai/workstudio/api/v2/published/${process.env.LENS_ID}/ask`;

const res = await fetch(url, {
  method: "POST",
  headers: { "x-ok-api-key": process.env.OPENKNOWRA_LENS_KEY!, "Content-Type": "application/json" },
  body: JSON.stringify({ question: "How many sites have an active critical alarm?" }),
});
console.log(await res.json());

Response

200 OK - the answer, the records behind it, and how it was reached.

{
  "kind": "resolved",
  "found": true,
  "question": "How many sites have an active critical alarm?",
  "headline": "14 sites have an active critical alarm.",
  "value": 14,
  "count": 14,
  "reading": "Sites linked to an Alarm whose severity is Critical and status is Active",
  "items": [
    { "siteId": "S-0042", "name": "North Ridge", "region": "West" }
  ],
  "truncated": false,
  "grounded": { "version": 2, "publishedAt": "2026-10-12T10:20:00.000Z" },
  "steps": ["Sites", "linked Alarms", "severity = Critical", "status = Active"]
}

Model APIs

Every entity of the graph you confirm in the console is a REST resource, named in plural lower case (sites, alarms, customers). Paths are relative to https://okp.openknowra.ai/workstudio/api/v2/published/{lensId}.

curl "https://okp.openknowra.ai/workstudio/api/v2/published/$LENS_ID/model/sites?region=West&limit=20" \
  -H "x-ok-api-key: $OPENKNOWRA_LENS_KEY"

{
  "api": "sites",
  "version": 2,
  "ok": true,
  "total": 38,
  "count": 20,
  "offset": 0,
  "next": 20,
  "records": [
    { "key": "S-0042", "name": "North Ridge", "region": "West",
      "alarms": { "count": 3, "items": [{ "key": "AL-9910", "severity": "Critical" }] } }
  ]
}

MCP server

The Data Lens is an MCP server (Streamable HTTP, JSON-RPC 2.0) at https://okp.openknowra.ai/api/okp/mcp/{lensId}, so an AI agent can work with the graph directly. Every tool is read-only.

{
  "mcpServers": {
    "network-graph": {
      "type": "http",
      "url": "https://okp.openknowra.ai/api/okp/mcp/<lensId>",
      "headers": { "Authorization": "Bearer ok_live_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Filters are a list of { field, op, value } with op one of eq, ne, gt, gte, lt, lte, in, not_in, contains, starts_with, between, exists, empty; a field can be a related path such as "HAS_SUPPLIER.country". The server also offers the graph's dictionary, skills and taxonomy as resources (okp://{lensId}/dictionary, /skills, /taxonomy).

Push API

Your systems can send changed records into one of the graph's connections as they happen. Switch push on for the connection's object in the console (it must have been read once); the console shows its URL and a signing secret.

Authenticate with the API key, or sign the request with the push secret (whsec_...):

import crypto from "node:crypto";

const body = JSON.stringify({ records: [{ siteId: "S-0042", status: "Maintenance" }] });
const ts = Math.floor(Date.now() / 1000).toString();
const sig = "sha256=" + crypto.createHmac("sha256", process.env.PUSH_SECRET).update(ts + "." + body).digest("hex");

await fetch(pushUrl, {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-ok-timestamp": ts, "x-ok-signature": sig },
  body,
});

{ "ok": true, "object": "sites", "entity": "Site", "via": "signed",
  "received": 1, "inserted": 0, "updated": 1, "unchanged": 0, "deleted": 0, "skipped": 0 }

Website chat

Data Lens for your website also gives you a script tag: paste it into any page and a chat answers from the graph. Optional attributes: data-title, data-color, data-position, data-open, data-inline, data-theme.

<script src="https://okp.openknowra.ai/okplatform/widget.js"
        data-agent="<lensId>" data-key="ok_live_xxxxxxxxxxxxxxxxxxxxxxxx"></script>

Pricing

Two things are billed, independently, on graduated slabs (each slab's rate applies only to the volume inside it):

The Model APIs, the MCP server's record tools and the Push API carry no per-call charge. Current rates and an estimator: Context Compiler pricing.

Errors

Errors are { "error": "<code>", "message": "..." }; the MCP server answers with JSON-RPC errors instead.