Atlas Developer Overview
Every surface Atlas exposes, which one to build against for a given job, and where each is documented.
Overview#
This section is for developers building software against Atlas: managing ontologies and instance maps programmatically, querying the compiled knowledge graph, feeding live data into Atlas, or reading live values back out of it. If you are configuring ontologies in the Atlas user interface, the Atlas user documentation covers what you need instead.
This chapter is the map. It names every surface Atlas exposes, says which ones to build against, and points at the chapter that documents each one. Route tables, error shapes and wire records live in Atlas API Overview and Connector Protocol Reference.
Three things to take away:
- Atlas exposes eight top-level surfaces. One of them,
/api/v1, is the general-purpose integration surface. - The connector model is push: connectors push live values, and Atlas asks them for ranges of history.
- A successful write is one Git commit. A write with outstanding validation violations is held in your draft session until you publish it.
The eight surfaces#
| Surface | Route | Credential | What it is | Build against it? |
|---|---|---|---|---|
| Machine plane | /api/v1 |
Pulse bearer | Domains, libraries, branches, commits, ontology, instance maps, compile, queries, validation, draft sessions, connectors, views, logs | Yes. This is the one. |
| UI plane | /app |
Session cookie, admin role on most writes | The route set the Atlas web interface uses for itself. It mirrors /api/v1 resource for resource and is not in the published API documents |
No. Listed here because it appears in browser dev-tools. It takes the session cookie rather than a bearer |
| Connector hub | /hubs/connector |
Cookie or bearer | SignalR over MessagePack. Data sources handshake in and push live rowsets | Yes, if you are building a data source |
| Value hub | /hubs/v1/branches/{branch}/domains/{domain}/subscribe |
Cookie or bearer | SignalR over MessagePack. The supported way to read live values out of Atlas. It also streams type descriptions (a type's columns, endpoints or enum roster). Each connection is pinned to one branch and domain by the URL | Yes, if you are consuming live values |
| Log hub | /hubs/logs |
Cookie or bearer | Live log tail. Its history twin is GET /api/v1/logs |
Operational only, not a data surface |
| MCP | /mcp |
Pulse bearer | Model Context Protocol endpoint for AI clients. It exposes the read tool set - ontology, instance maps, Cypher, domains, libraries and skills | Yes, for LLM tooling |
| i3X | /i3x/v1 |
Pulse bearer, except GET /i3x/v1/info which is anonymous |
CESMII i3X v1.0.0 browse surface, including a polled subscription model. It uses its own {success, result} envelope, not application/problem+json. Branch and domain are pinned from the I3x config section and never appear on the wire |
Yes, if you have an i3X client |
| API documentation | /api/help, /api/v1.json, /api/i3x.json |
See the API overview | Swagger UI and the OpenAPI documents. Registered unconditionally, so a Docker deployment still serves them. Only the third ui document is gated to Development |
Use it as the live route reference |
The three SignalR hubs share the HubAccess policy, the only Atlas policy that accepts either the
session cookie or a bearer. Full authentication detail, error shapes and the troubleshooting matrix
are in Atlas API Overview.
Atlas serves its web interface for any URL outside the API surface, so a mistyped route
returns 200 text/html rather than a 404. Check Content-Type before parsing.
The value hub client package#
You do not have to hand-roll the value hub connection.
The Atlas value-hub client library ships AtlasClient, a
HubConnection wrapper with the correct MessagePack options preconfigured. Its second constructor
takes an optional Func<Task<string?>>? accessTokenProvider for bearer auth.
This matters because the default MessagePack setup does not work. The value hub and the connector
hub both carry the typed Column union, which requires ConnectorMessagePackOptions.Options
rather than a bare AddMessagePackProtocol(). See the
Connector Protocol Reference section "Mandatory client
setup" for what goes wrong otherwise.
For browsers, Atlas ships a JavaScript wrapper, atlas-client.js, with a live test harness
beside it. Browser consumers must add @microsoft/signalr-protocol-msgpack;
the default JSON protocol cannot discriminate the Column union.
The hub exposes four server-to-client streams, SubscribeToInstanceProperty, SubscribeToInstance,
SubscribeToInstancePropertyOfType and SubscribeToInstanceOfType, plus four GetRange* backfill reads over the same
connection. There is no Unsubscribe* method: cancelling the
stream is the unsubscribe. Streams do not auto-restore after a reconnect, so re-establish them
yourself when HubConnection.Reconnected fires.
Choosing an integration path#
| What you want to do | Surface | Chapter |
|---|---|---|
| Create or import ontologies and instance maps | /api/v1 |
Atlas API Overview, 02, 03, 05 |
| Compile a domain and inspect validation | PUT /api/v1/branches/{branch}/domains/{domain}/world |
07 |
| Query the compiled graph for reports or dashboards | POST /api/v1/branches/{branch}/domains/{domain}/queries |
06, 07 |
| Automate ontology management in a pipeline | /api/v1 writes plus PUT .../world |
04, 07 |
| Bring live data into Atlas from a data source | /hubs/connector |
08, 09, 11 |
| Read live values out of Atlas | Value hub plus the Atlas value-hub client library | This chapter |
| Expose Atlas to an AI client | /mcp |
Atlas MCP Server |
| Browse Atlas from a standards-based client | /i3x/v1 |
i3X surface |
| Any integration | /api/v1 rather than /app, which takes the browser session cookie |
n/a |
Prerequisites#
For /api/v1, /i3x/v1 and /mcp: an HTTP client and a Pulse-issued bearer token whose aud
claim includes Atlas's Pulse:Auth:ClientId (Atlas by default). Pulse:Auth:Enabled=true is the shipped
default, so there is no unauthenticated path. See
Atlas API Overview.
For the hubs: a SignalR client with MessagePack, bound to
ConnectorMessagePackOptions.Options. The shipped clients use
Microsoft.AspNetCore.SignalR.Client 10.0.3 and
Microsoft.AspNetCore.SignalR.Protocols.MessagePack 10.0.3. For reading values, prefer
Timebase.Atlas.Client or wwwroot/atlas-client.js over hand-rolling.
What Atlas ships as#
Atlas deploys as one process, Atlas, with two supporting libraries other Timebase components reference:
| Piece | What it is |
|---|---|
| Atlas | The service: endpoints, hubs, Git store, compilation, connectors, data store, agent, MCP, licensing, sessions and views |
| The Atlas interface | The React single-page application, built into the same container and served from the same process |
| Query engine | The openCypher parser, planner and execution engine, referenced as a library |
| Value hub client | The value hub client library |
| Shared contracts | The connector and value wire contract, and the shared model types |
Atlas is a single container serving the interface and every surface above from one process, so there is no separate cache or runtime tier to deploy.
Referencing the shared contracts. They are not published as a NuGet package, so an in-repo
consumer takes a project reference. The only external dependency is MessagePack 3.1.4.
What is in the developer docs#
| Chapter | What it covers |
|---|---|
| 01 Atlas Developer Overview | This chapter. Surface inventory and routing |
| 02 JSON-LD and the Atlas Data Model | How ontology definitions map to RDF, and what the compiler produces |
| 03 Ontology Design Patterns | Inheritance, libraries, property kinds, modelling guidance |
| 04 API Authentication and Versioning | The /api/v1 machine plane and the four authorization policies |
| 05 Instance Maps Programming Guide | Property strategies and instance-map writes |
| 06 openCypher Query Reference | Supported syntax, functions, result schema |
| 07 Compile and Query Workflow | When to compile, how validation works, draft-session interaction |
| 08 Connector Overview and Lifecycle | Connect, handshake, reconcile, subscribe, disconnect, reconnect |
| 09 Connector Protocol Reference | The wire contract: every record, key number, union tag and enum ordinal, in both directions |
| 11 Connector Range Queries | GetRange request fields, pushdown translation, residual semantics |
Chapter 09 owns every wire shape, so a question about a message shape is answered there.
Where to look next#
- Live route reference:
https://<your-atlas-server>:4552/api/help, with machine-readable documents at/api/v1.jsonand/api/i3x.json. - API semantics: Atlas API Overview for authentication, the full route table, RFC-9457 error shapes, pagination, and a troubleshooting matrix.
- Connector wire: Connector Protocol Reference.
The i3X surface registers 20 routes, not 22.