Atlas API Overview

Overview#

Atlas exposes a versioned HTTP API that lets you read and change domains, libraries, ontology types, instance maps, compiled worlds, and query results without opening the Atlas user interface. This article is the map of that API: the base address, how to authenticate, the full list of route groups, the response and error formats, and the three failure shapes that confuse people most. Every other Atlas API article links back here for the route table and the version story.

This article is written for developers building an integration against Atlas.

The one thing to take away: the machine-facing API lives under /api/v1. If a script or code sample points at /api/v2/..., /api/domains, /api/libraries or /api/git/..., it is targeting URLs outside the API surface. Those do not return 404: Atlas answers with the single-page application shell as 200 text/html, so check the content type before parsing. See Troubleshooting at the end of this article.

Paths that are not part of the API#

Nothing answers on these. If a script or sample you have targets one, point it at the replacement.

Four resources were renamed at the same time. Correcting only the version prefix is not enough:

The current families are listed below. There is no /api/v2, no /api/domains and no /api/libraries") registration left.

Base address and ports#

Atlas runs as a single container that serves the user interface and the API from the same process. The default listeners are:

https://<your-atlas-server>:4552

HTTPS redirection is active, so a plain HTTP call to 4551 is answered with a redirect to 4552. A plain HTTP call to http://<host>:4551/ returns 307 to https://<host>:4552/. The stock docker-compose.yml publishes only 4551:4551, so if you deploy with that file unchanged, the redirect target is not reachable from outside the container. Publish 4552 as well, or terminate TLS in front of Atlas.

Authentication#

Atlas ships with authentication on. settings.config contains:

"Pulse": {
  "Host": "localhost",
  "Port": 4542,
  "UseTls": true,
  "Auth": {
    "Enabled": true,
    "ClientId": "Atlas",
    "ClientSecret": ""
  }
}

Every /api/v1 route group is gated by RequireAtlasApiAuth, which attaches the bearer-only ApiAccess policy whenever Pulse:Auth:Enabled=true. To call the API you need:

1. A Pulse-issued bearer token (Pulse is the Timebase identity component that checks credentials and issues tokens), sent as Authorization: Bearer <token>.
2. That token's aud (audience) claim must include the value of Atlas's Pulse:Auth:ClientId, which is Atlas by default. Your calling client's Pulse registration must list Atlas in its audiences.

With a valid bearer, a read such as GET /api/v1/domains returns 200 application/json.

Without a token you may get HTML, not a 401#

This is worth building into your client once:

On a deployment with authentication enabled, an unauthenticated GET /api/v1/domains returned:

302 Found
Location: https://<pulse-host>:4542/auth/authorize?client_id=Atlas&redirect_uri=.../callback&response_type=code&scope=openid profile

and, after following the redirect, an HTML sign-in page. Not 401, not application/problem+json. Any HTTP client configured to follow redirects therefore receives HTML where it expects JSON, and your JSON parser throws on the leading <. The same shape applies to /api/v1/branches and /api/v1.json.

The ApiAccess policy pins the JWT bearer scheme, so a missing or invalid token produces a 401 rather than a browser redirect. Some deployments answer with a 302 to the Pulse sign-in page instead, so write your client for both: always send a bearer, and turn off redirect-following so you see the status rather than a page of HTML.

Turning authentication off#

Setting Pulse:Auth:Enabled=false leaves the machine plane open, and named policies are then not attached at all. Use this only for local development. In open mode, writes are attributed to Anonymous rather than to a named identity.

The X-Atlas-Author header is gone#

Git commit authorship comes from the authenticated caller, defaulting to Anonymous when authentication is disabled.

The eight top-level surfaces#

Atlas maps eight top-level route families. Only the first is a general-purpose integration surface.

The three SignalR hubs share the HubAccess policy, the only Atlas policy that accepts either the session cookie or a bearer.

The /api/v1 route table#

Every machine-plane module is registered in one place, (the five ontology modules are the block). These are the route groups, with the resources in each.

Catalogs and repository (not branch-scoped in the path)#

Branch-scoped resources#

All of these sit under /api/v1/branches/{branch}/....

Ontology resources (five kinds, domain and library scope)#

Each of the five ontology kinds is mapped twice, once for domains and once for libraries:

/api/v1/branches/{branch}/domains/{domain}/{kind}
/api/v1/branches/{branch}/libraries/{library}/{kind}

The verb rule: entity types, relationship types, properties, instance-map instances and branch renames update with PATCH (partial merge). Data types and functions update with PUT (a full atomic re-emit of the whole definition). Sending PUT where PATCH is expected does not match a route, and Atlas answers with the single-page application shell as 200 text/html rather than 404 or 405.

data-types is a full ontology resource in its own right, including the isTimeAxis flag.

Request and response format#

• Send Content-Type: application/json on every POST, PUT and PATCH body.
• Responses use camelCase property names, omit null values entirely, and serialize enums as camelCase strings (the entity node kind becomes "entity"). These options are applied globally to /api/v1, /app/v1 and /i3x/v1. A strongly typed client that expects null members to be present, or expects integer enums, will break.
• Response compression is applied to the public /api surface, excluding /api/help, plus the i3X surface. text/event-stream is never compressed so that streaming responses are not buffered.
• 201 Created returns the created resource in the body. A Location header is present only on domain, library and branch creation. Ontology creates return 201 with no Location header, so do not build a client that blindly follows it.

The query body field is cypher, not query#

The most common first-call mistake against POST /api/v1/branches/{branch}/domains/{domain}/queries:

{
  "cypher": "MATCH (n:Plant) RETURN n.Label",
  "parameters": {},
  "projections": false
}

Sending {"query": "..."} returns 400 with the detail "Cypher query string is required.".

A successful response is {"columns": [...], "data": [[...]]}. Set "projections": true to get the enriched shape, which adds classesTouched and instanceIdsByClass; the latter carries durable instance URN strings, not integers.

Querying a domain that has never been compiled returns 400 with "code": "Query.NotCompiled", not 404. Compile with PUT .../world first.

Pagination#

Collections paginate, and one of them applies a default page size when you omit limit.

If you request commit history without a limit, you get ten commits and no error. Page with nextCursor until it comes back null.

Errors#

Every /api/v1 failure returns RFC-9457 Problem Details as application/problem+json. There is no error field and no message field on the current surface, and responses carry no filesystem path.

{
  "type": "https://atlas.timebase.io/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Domain 'my-domain' not found",
  "traceId": "00-…"
}

The type URIs are frozen once emitted, so branch your client on the type token, never on the human-readable title.

Successful responses are 200 OK for reads and updates, 201 Created for creates, and 204 No Content for deletes.

There is no universal code field#

Write your error handler to branch on the type URI first. The generic error path emits type, title, status and detail, plus the traceId the framework adds, and carries no code extension.

A code extension appears only on specific problems:

• Query errors, where code carries the stable error key such as Query.NotCompiled.
• Draft.NothingToPublish.
• Delete-blocked 409s, which add target and dependents rather than code.

Write your client to branch on the type URI, and read code only where the specific problem documents it.

Writes, draft sessions and compilation#

Two behaviours change what a successful write means. Both are on by default.

A save that fails validation still returns 2xx. Draft sessions are enabled by default (Atlas:DraftSessions:Enabled). When an ontology save carries outstanding error-severity violations, the content lands in the caller's private draft session and the target branch is not advanced. The only signal is the Atlas-Validation-Violations response header, which carries the count of outstanding violations. Check that header on every write. To promote the draft onto the branch, call POST /api/v1/branches/{branch}/draft/publish.

Compilation validates the whole domain before it builds. PUT /api/v1/branches/{branch}/domains/{domain}/world returns 422 with a violations[] array while any error-severity violation is outstanding, and builds the world once the last one is cleared. On success it returns CompileResult {entityCount, edgeCount, archetypeCount, compiledAt, functionErrors[]}. GET .../world reports isStale, compiledAtSha and currentSha without recompiling. There is no warnings member and no tripleCount; read warnings from GET .../validation.

So a 422 is the compile response; a save with outstanding violations returns 2xx and is held in your draft session.

Atlas recompiles every recorded branch and domain pair at startup, so a manual recompile after a restart is normally unnecessary.

Browse the live API reference#

Atlas serves Swagger UI at:

https://<your-atlas-server>:4552/api/help

with machine-readable OpenAPI documents at /api/v1.json and /api/i3x.json. The documents are selected by URL prefix: v1 covers /api/v1/, i3x covers /i3x/v1/.

The v1 and i3X documents are served on every deployment, including Docker, so /api/help is available in production. The third document, covering the internal /app/v1 routes, is served in Development only.

Troubleshooting#

Related articles#

• Atlas API - Domains
• Atlas API - Ontology
• Atlas API - Instance Maps
• Atlas API - Libraries
• Atlas API - Query
• Atlas API - Connectors
• Atlas API - Branches and Commits
• Atlas MCP Server