Atlas — the typed entity graph

Atlas is the module that turns names into addressable concepts. It owns the entities, their aliases, the typed directed edges between them, and the mention-level provenance that says which document and which character offsets produced each fact. Everything below is served by pure SQL — no model, no embedding, no reranker.

What it does

Atlas stores a workspace's concepts as typed entities and connects them with typed, directed relations. Duplicates collapse into a single canonical head, and the serve-time edge table (canonical_relations) is a materialized rollup over that head, so a read never has to reason about merges. Every entity carries the aliases it answers to, a mention count, and the documents it was found in; every extracted edge can carry the quote that grounds it. The public surface is a list, a single concept read, a bounded neighborhood expansion, a workspace manifest, and hand-authored writes for entities and relations.

Use it standalone

Atlas is self-contained. The only things it needs are a workspace and an API key with the right scopes.

1. Give the key the graph scopes

   Reads (GET /entities, GET /entities/:id, the neighborhood, the manifest) require kb:read; the legacy runs:read grant is still accepted on those four. Writes (POST/PATCH/DELETE on entities and relations) require kb:write. Scopes are checked by exact membership — kb:write does not imply kb:read, so a key that both reads and edits the graph needs both. Delegated user keys (eli_uk_) additionally have their owner's live capabilities re-checked: graph:read for the entity reads, graph:write for the writes, and workspace:read for the manifest.

2. Import one module

   Headless: createGraphClient from @eli-ai/client/graph. React: EliKnowledgeGraph from @eli-ai/react/graph. Types-only: @eli-ai/contracts/graph. None of the three pulls in another capability module.

3. Seed the graph by hand, or let ingestion fill it

   POST /api/v1/entities and POST /api/v1/relations are enough to build a complete graph with no documents at all. If documents are present, extraction writes into the same tables and the reads are unchanged.

import { createEliTransport } from "@eli-ai/client/core";
import { createGraphClient } from "@eli-ai/client/graph";

const graph = createGraphClient(
  createEliTransport({
    baseUrl: "https://eli.ai",
    apiKey: () => process.env.ELI_API_KEY!,
    workspaceId: process.env.ELI_WORKSPACE_ID,
  }),
);

// Hand-author two concepts and the edge between them.
const platform = await graph.createEntity({
  name: "Order Platform",
  type: "system",
  aliases: ["order-platform", "OP"],
});
const owner = await graph.createEntity({ name: "Ada Byron", type: "person" });

await graph.createRelation({
  srcEntityId: owner.id,
  dstEntityId: platform.id,
  type: "owns",
  evidence: "Ada is listed as the service owner in the on-call rota.",
});

// Read it back.
const page = await graph.listEntities({ limit: 25, type: "system" });
const around = await graph.neighborhood(platform.id, { depth: 2, perHopCap: 10 });
console.log(page.total, around.edges.length, around.truncated);

React components

@eli-ai/react/graph exports exactly one component, EliKnowledgeGraph, plus its two prop types (EliKnowledgeGraphProps, EliKnowledgeGraphLabels). It renders a Surface containing an optional create form, a filter input, a flat canvas of clickable concept buttons, and a side panel that loads the selected concept's neighborhood at depth 1. It calls three operations through the headless graph client: listEntities on mount, neighborhood when a concept is selected, and createEntity when the form is submitted. The filter is client-side only — it narrows the already-loaded page by name or type and issues no request.

{
  title: "Knowledge graph",
  description: "Explore concepts and the evidence-backed relationships between them.",
  filter: "Filter concepts",
  type: "Type",
  create: "New concept",
  cancel: "Cancel",
  name: "Name",
  aliases: "Aliases",
  save: "Create concept",
  empty: "No concepts found",
  neighborhood: "Neighborhood",
  relations: "Relations",
  sourceDocuments: "Source documents",
}

import { createEliTransport } from "@eli-ai/client/core";
import { EliProvider } from "@eli-ai/react/provider";
import { EliKnowledgeGraph } from "@eli-ai/react/graph";
import "@eli-ai/react/styles.css";

// EliProvider has no API-key prop by design. Point the transport at a
// same-origin route of your own that injects the Bearer key server-side.
const transport = createEliTransport({ fetch: sameOriginProxyFetch });

export function ConceptExplorer({ workspaceId }: { workspaceId: string }) {
  return (
    <EliProvider transport={transport} workspaceId={workspaceId}>
      <EliKnowledgeGraph
        limit={200}
        allowCreate
        labels={{ title: "Concepts", create: "Add concept" }}
        onEntitySelect={(entity) => track("concept.open", entity.id)}
        onDocumentSelect={(documentId) => openDocument("/documents/" + documentId)}
        onError={(error) => reportError(error)}
      />
    </EliProvider>
  );
}

There is no component for the manifest or for relation writes. Both are one hook away — the same generic hooks the packaged components are built on work with any graph-client method and your own markup.

import { createGraphClient } from "@eli-ai/client/graph";
import { useEliQuery } from "@eli-ai/react/hooks";
import type { WorkspaceManifest } from "@eli-ai/contracts/graph";

export function HubConcepts() {
  const manifest = useEliQuery<WorkspaceManifest>(
    "graph.manifest",
    (context, signal) =>
      createGraphClient(context.transport).manifest({
        signal,
        ...(context.workspaceId ? { workspaceId: context.workspaceId } : {}),
      }),
  );

  if (manifest.isLoading) return <p>Loading…</p>;
  if (!manifest.data) return null;

  return (
    <ol>
      {manifest.data.hubConcepts.map((concept) => (
        <li key={concept.id}>
          {concept.name} · in-degree {concept.inDegree} · {concept.authority}
        </li>
      ))}
    </ol>
  );
}

HTTP API

Nine operations across six paths. Every request carries a Bearer key; see Authentication. Examples use https://eli.ai, whose apex 308-redirects, so -L is included on every non-GET example. A resource in another workspace is invisible under row-level security and comes back as 404, never 403.

curl -s "https://eli.ai/api/v1/entities?limit=25&type=system" \
  -H "Authorization: Bearer $ELI_KEY"

{
  "entities": [
    { "id": "01KY0ZW3B8AVDR67NXSE96P81N", "name": "Order Platform", "type": "system", "pagerank": 0.0421 },
    { "id": "01KY10DDDDDDDDDDDDDDDDDDDD", "name": "northwind-ops", "type": "system", "pagerank": null }
  ],
  "total": 27,
  "limit": 25,
  "offset": 0
}

curl -L -X POST https://eli.ai/api/v1/entities \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Fulfillment Console","type":"system","aliases":["fulfillment-console"]}'

{
  "id": "01KY10KKKKKKKKKKKKKKKKKKKK",
  "name": "Fulfillment Console",
  "type": "system",
  "nameNorm": "fulfillment console",
  "origin": "manual",
  "description": null,
  "aliases": ["Fulfillment Console", "fulfillment-console"]
}

curl -s https://eli.ai/api/v1/entities/$ENTITY_ID \
  -H "Authorization: Bearer $ELI_KEY"

{
  "id": "01KY0ZW3B8AVDR67NXSE96P81N",
  "name": "Order Platform",
  "type": "system",
  "nameNorm": "order platform",
  "origin": "extraction",
  "description": "Core order intake and fulfillment system.",
  "aliases": ["order-platform", "OP"],
  "curation": {
    "authority": "curated",
    "lifecycleStatus": "published",
    "ownerId": "usr_01KY0Z9M2E5Q4RS8T0V1WX2Y3Z",
    "stewardIds": [],
    "version": 4,
    "lastReviewedAt": "2026-05-02T10:14:00.000Z",
    "nextReviewAt": "2026-11-02T10:14:00.000Z",
    "supersededBy": null,
    "sourceRefs": [{ "label": "Service catalogue", "url": "https://intranet.example.com/catalogue" }],
    "editorialNote": null
  }
}

curl -L -X PATCH https://eli.ai/api/v1/entities/$ENTITY_ID \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"service"}'

{
  "id": "01KY10KKKKKKKKKKKKKKKKKKKK",
  "name": "Fulfillment Console",
  "type": "service",
  "nameNorm": "fulfillment console",
  "origin": "manual",
  "description": null,
  "aliases": ["Fulfillment Console", "fulfillment-console"]
}

curl -L -X DELETE https://eli.ai/api/v1/entities/$ENTITY_ID \
  -H "Authorization: Bearer $ELI_KEY"

{ "deleted": true, "id": "01KY10KKKKKKKKKKKKKKKKKKKK" }

curl -s "https://eli.ai/api/v1/entities/$ENTITY_ID/neighborhood?depth=2&perHopCap=10" \
  -H "Authorization: Bearer $ELI_KEY"

{
  "entity": {
    "id": "01KY0ZW3B8AVDR67NXSE96P81N",
    "name": "Order Platform",
    "type": "system",
    "aliases": ["order-platform", "OP"],
    "mentionCount": 42,
    "topRelations": ["Order Platform —depends_on→ northwind-ops"],
    "docIds": ["01KY10AAAAAAAAAAAAAAAAAAAA"],
    "authority": "curated",
    "lifecycleStatus": "published"
  },
  "nodes": [
    {
      "id": "01KY10DDDDDDDDDDDDDDDDDDDD",
      "name": "northwind-ops",
      "type": "system",
      "aliases": [],
      "mentionCount": 18,
      "topRelations": ["Order Platform —depends_on→ northwind-ops"],
      "docIds": ["01KY10AAAAAAAAAAAAAAAAAAAA"],
      "authority": "machine_extracted",
      "lifecycleStatus": "published"
    }
  ],
  "edges": [
    {
      "src": "01KY0ZW3B8AVDR67NXSE96P81N",
      "type": "depends_on",
      "dst": "01KY10DDDDDDDDDDDDDDDDDDDD",
      "mentionCount": 7
    }
  ],
  "truncated": false
}

curl -L -X POST https://eli.ai/api/v1/relations \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"srcEntityId":"01KY0ZW3…","dstEntityId":"01KY10KK…","type":"depends_on"}'

{
  "relationId": "01KY10MMMMMMMMMMMMMMMMMMMM",
  "affectedCanonicalIds": ["01KY0ZW3B8AVDR67NXSE96P81N", "01KY10KKKKKKKKKKKKKKKKKKKK"]
}

curl -L -X DELETE https://eli.ai/api/v1/relations/$RELATION_ID \
  -H "Authorization: Bearer $ELI_KEY"

{ "deleted": true, "id": "01KY10MMMMMMMMMMMMMMMMMMMM" }

curl -s https://eli.ai/api/v1/manifest \
  -H "Authorization: Bearer $ELI_KEY"

{
  "generatedAt": "2026-07-21T09:15:00.000Z",
  "workspace": { "id": "ws_01KY0Z00000000000000000000", "name": "Northwind Ops" },
  "counts": {
    "documents": 128,
    "chunks": 3410,
    "entities": 743,
    "relations": 1289,
    "entitiesByType": { "system": 41, "metric": 22, "policy": 17 },
    "relationsByType": { "governed_by": 58, "owned_by": 44 },
    "byAuthority": { "machine_extracted": 601, "asserted": 92, "curated": 38, "certified": 12 },
    "byLifecycle": { "draft": 4, "pending_review": 2, "published": 724, "deprecated": 9, "superseded": 4 },
    "documentsByVerification": { "unverified": 96, "verified": 24, "certified": 6, "deprecated": 2 }
  },
  "hubConcepts": [
    {
      "id": "01KY0ZW3B8AVDR67NXSE96P81N",
      "name": "Order Platform",
      "type": "system",
      "summary": "Core order intake and fulfillment system.",
      "authority": "certified",
      "lifecycleStatus": "published",
      "version": 6,
      "inDegree": 31,
      "outDegree": 12,
      "mentionCount": 87,
      "lastReviewedAt": "2026-07-14T10:02:11.000Z",
      "ownerId": "usr_01KY0Z9M2E5Q4RS8T0V1WX2Y3Z"
    }
  ],
  "staleness": { "overdueReviews": 3, "neverReviewed": 640 }
}

Data elements

Atlas owns ten tables. Every one of them carries a workspace_id column and a tenant-isolation row-level-security policy that constrains both reads and writes to the workspace of the current transaction, so a cross-workspace id is simply not visible rather than forbidden. Ids are ULID strings.

Atlas also reads two tables it does not own: documents (for the ACL columns and to resolve docIds) and chunks (referenced by mentions and evidence). Three more Atlas-adjacent tables exist but have no v1 endpoint on this page — merge_log, extraction_runs, and rejection_tombstones.

How it composes

Atlas is usable on its own, and every other module that touches the graph does so through the same tables and the same serve-time functions this page documents.

• Intake — the biggest gain. With documents in the workspace, extraction writes entities, aliases, relations, mentions, and evidence for you, and the fields that are empty in a hand-built graph fill in: mentionCount, docIds, edge mentionCount, and the manifest's document and chunk counts. Without it, nothing breaks — you author the graph through POST /entities and POST /relations.
• Warrant — required for governance writes. The authority and lifecycle_status columns live on the Atlas entities row and Atlas serves them on every card and in the curation block, but Atlas has no endpoint to change them. Certifying, setting an owner, stamping a review, deprecating, the revision history endpoint, change requests, and the SKOS export are all Warrant. Without Warrant the defaults hold — manual creates are asserted, extraction is machine_extracted, everything is published — and the serving rules above still apply.
• Lineage — reads Atlas from the document side: which concepts a document produced, and how many live relations its evidence grounds. It needs documents, so it is meaningful only alongside Intake.
• Lens — the retrieval pipeline's graph-fusion stage calls the very same frontier expansion this module exposes, to surface evidence that is structurally rather than textually related. Atlas does not need Lens; Lens gets materially better with a populated Atlas. See Retrieval pipeline.
• Conduit — binds a governed live query to an entity id or to an entity type, so Atlas is the addressing scheme for live data. The binding rows live in Conduit's table and reference Atlas ids; Atlas itself neither reads nor needs them.
• Crucible — grades concept recall against entity ids on golden items. Optional, and evaluation-only.
• Ports — exposes the same reads over MCP (kb_entity_lookup, kb_entity_get, kb_graph_query, and the eli://workspace/manifest resource) for agents that speak that protocol instead of REST. Same server functions, different envelope.