Atlas API - Domains

Overview#

A domain is the unit Atlas models the world in. It is a folder in Atlas's git repository holding one ontology.jsonld entry point plus whatever instance maps sit beside it, and it is the thing every ontology, instance, query and compile call is addressed against. This article documents the domain lifecycle surface: creating a domain, listing and reading the catalog, deleting a domain, managing the shared libraries a domain imports, and compiling a domain into a queryable world.

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

Everything here lives under /api/v1. Base address, authentication, the RFC-9457 error envelope, the full route table, and the two failure shapes that catch people out (an unauthenticated call answered with an HTML sign-in page, and a retired route answered with 200 text/html instead of 404) are documented once in the Atlas API Overview. Read that first; this article does not restate it.

Four route groups make up this surface:

The /app/domains and /app/branches/{branch}/domains/{domain}/imports routes you will see in the Atlas single-page application's network traffic are the same MediatR handlers behind a private cookie-authenticated plane. They are excluded from the published API documents and are not an integration surface. Script against /api/v1.

Every call needs a bearer#

Pulse:Auth:Enabled is true by default, and every route in this article is registered with .RequireAtlasApiAuth(configuration). Send a Pulse-issued bearer whose aud claim includes Atlas's Pulse:Auth:ClientId (Atlas by default) on every request. Each curl example below includes it. See the Atlas API Overview for how the token is obtained and what an unauthenticated call actually returns.

The git commit author for every write on this surface is derived from the authenticated principal, falling back to Anonymous when authentication is disabled. There is no request field and no header for it:

• createdBy in a create body is ignored, because it is not one of the accepted fields.

How branching works on this surface#

Domains live in a git repository, so every read is against some commit and every write is a commit. The three route groups address the branch differently, and the difference is load-bearing.

Two consequences worth designing around:

A bad branch name on the catalog list does not error. resolves ?branch= to a commit SHA and reads the pinned tree. If the branch cannot be resolved, or the data root is not a git repository, it falls back to the working-tree scan. A typo returns a plausible-looking wrong list, never a 404. On the imports read the same unresolvable branch maps to 404 Domain '<domain>' not found instead, because that handler has no separate branch error channel.

Branch names containing a slash must be percent-encoded. A branch such as feature/cool is sent as feature%2Fcool in the {branch} path segment. ASP.NET routing preserves the encoded slash in the route value, and the imports handlers call Uri.UnescapeDataString(branch) to recover it.

Domain names#

The name you send is used verbatim as the folder name and as the name in every response. It is not normalised.

What is derived from it, lowercased with spaces turned into hyphens, is the domain's URN prefix written into the new ontology.jsonld. Sending Cooling System produces a folder literally named Cooling System with the prefix cooling-system and the URN base urn:atlas:ontology:cooling-system:. Sending cooling-system makes the two agree, which is what you want. Use lowercase, hyphen-separated names.

The only hard rule the writer enforces is that the name must be non-empty and must contain no character illegal in a file name; either failure is a 400.

List all domains#

Returns every domain visible on the requested branch, ordered by name.

Request

GET /api/v1/domains
GET /api/v1/domains?branch=feature/cool

curl -H "Authorization: Bearer $ATLAS_TOKEN" \
  "https://<your-atlas-server>:4552/api/v1/domains?branch=main"

Response - 200 OK

[
  {
    "name": "brewing-operations",
    "hasOntology": true,
    "description": "Wort production and fermentation"
  },
  {
    "name": "packaging-line",
    "hasOntology": true
  }
]

There is no path field. Responses on this surface never carry a filesystem path, for privacy and portability. DomainInfo still holds Path internally, but the endpoint projects it out. A client reading path gets undefined.

This collection does not paginate. It returns every domain in one array.

Create a domain#

Creates the domain folder and writes a minimal ontology.jsonld into it, as a single git commit on the target branch.

Request

POST /api/v1/domains
Content-Type: application/json

{
  "name": "cooling-system",
  "branch": "feature/cool",
  "libraries": ["isa95-common"],
  "description": "Chilled water and glycol loops"
}

Only name is required. createdBy is not a field. See "Every call needs a bearer" above.

curl -X POST \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"cooling-system","libraries":["isa95-common"],"description":"Chilled water and glycol loops"}' \
  "https://<your-atlas-server>:4552/api/v1/domains"

Response - 201 Created

{
  "name": "cooling-system",
  "hasOntology": false
}

Location: /api/v1/domains/cooling-system is set. hasOntology is hard-coded false in the create response even though the handler has just written ontology.jsonld; read the domain back if you need its real state.

What gets written#

The new domains/{name}/ontology.jsonld is:

{
  "@context": [
    "../../libraries/atlas-core.jsonld",
    "../../libraries/isa95-common.jsonld",
    { "cooling-system": "urn:atlas:ontology:cooling-system:" }
  ],
  "@graph": [
    {
      "@id": "urn:atlas:ontology:cooling-system",
      "@type": "owl:Ontology",
      "rdfs:label": "Cooling System Domain",
      "rdfs:comment": "Chilled water and glycol loops"
    }
  ]
}

Three things to note:

• atlas-core is always imported first, whether or not you list it. It is de-duplicated, so listing it again does not write it twice.
• Each entry in libraries becomes "../../libraries/{name}.jsonld", in the order you gave.
• The library names are not validated at create time. Unlike the add-import call, a name that does not resolve to a library file is written into @context anyway, and the failure surfaces later as a compile error. Prefer creating bare and adding imports one at a time if you want the 404.

rdfs:label is a title-cased rendering of the name with hyphens turned into spaces.

Errors

Get a single domain#

Request

GET /api/v1/domains/{domain}

This route accepts no branch parameter. It always reads the working tree at HEAD. To read a domain that exists only on another branch, use GET /api/v1/domains?branch=... and pick it out of the list.

curl -H "Authorization: Bearer $ATLAS_TOKEN" \
  "https://<your-atlas-server>:4552/api/v1/domains/brewing-operations"

Response - 200 OK

{
  "name": "brewing-operations",
  "hasOntology": true,
  "description": "Wort production and fermentation"
}

Same three fields as a list element, same null omission for description, and no path.

There is no message field, and there is no POST /api/sessions endpoint anywhere in Atlas. If you have a document telling you to start an editing session that way, it is describing something that never shipped. Editing is ordinary writes against the ontology and instance-map routes; the draft-session resource, when one exists, is /api/v1/branches/{branch}/draft.

Errors

Update a domain's description#

PUT /api/v1/domains/{domain}?branch={branch}

The description is the only editable piece of a domain's metadata.

{
  "description": "Bottling line 1, filler through palletiser."
}

The response echoes the description as persisted, which is trimmed, and null when you clear it by sending an empty value:

{
  "name": "juice-factory",
  "description": "Bottling line 1, filler through palletiser."
}

The name is not editable, deliberately. A domain's name is its identity: it derives the urn:atlas:ontology:{prefix} namespace that every entity URI in the domain is built from, the folder on disk, and the {domain} segment of every i3X element id. Renaming would break every external reference at once, so it is not offered here or anywhere else.

Delete a domain#

Hard-deletes the domain folder and everything under it, as one git commit on the target branch.

Request

DELETE /api/v1/domains/{domain}
DELETE /api/v1/domains/{domain}?branch=feature/cool

curl -X DELETE \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  "https://<your-atlas-server>:4552/api/v1/domains/cooling-system?branch=main"

Response - 204 No Content

Existence is checked inside the branch's worktree rather than at HEAD, so a domain that lives only on a feature branch can be deleted on that branch. This differs from the create path's HEAD-scoped duplicate check.

The delete-blocked 409#

Before deleting, Atlas scans every other domain on the branch and inspects the @context of every *.jsonld beneath it, recursively. Any entry that resolves into domains/{target}/ blocks the delete, and the full blocker list is returned. Nothing is removed.

Response - 409 Conflict, application/problem+json

{
  "type": "https://atlas.timebase.io/errors/delete-blocked",
  "title": "Delete Blocked",
  "status": 409,
  "detail": "Cannot delete 'iso-base' — it is referenced by 1 domain.",
  "target": { "name": "iso-base", "kind": "domain" },
  "dependents": [
    {
      "id": "juice-factory",
      "name": "juice-factory",
      "kind": "domain",
      "referenceType": "domain-imports-domain"
    }
  ]
}

target and dependents are RFC-9457 extensions carried only by this problem type. The dependents array is never truncated. There is no code field here, so branch on the type URI: a plain name collision is .../errors/conflict while a blocked delete is .../errors/delete-blocked, and both are 409.

The detail string is emitted verbatim as shown, including its em dash, and pluralises to domains for counts other than one. Do not parse it; read dependents.

Domains do not currently import other domains in any shipped model, so in practice this scan finds nothing and deletes succeed. The check exists because the reference model allows domain-to-domain imports and the loader would follow them.

The open-draft-session 409#

A delete is also refused while the calling identity holds a draft session on the resolved branch. Creates, updates and imports are not: they go into the draft and merge on publish. A deletion has nothing to validate and no half-finished state, so it is never parked in a draft.

Response - 409 Conflict, application/problem+json

{
  "type": "https://atlas.timebase.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Refused 'Delete domain iso-base' on branch 'main': you have an unpublished draft ('draft/alice/main') on this branch, and a deletion cannot be parked in a draft. Publish the draft to promote its changes, or discard it (the Discard action beside Publish, or DELETE /api/v1/branches/main/draft), then delete again."
}

This one is not distinguishable by type. It carries the plain .../errors/conflict URI, the same as a name collision, with no code field and no extensions. On the delete routes the two plain-conflict cases are the draft refusal and nothing else, so on a DELETE a .../errors/conflict means an open draft. Call GET /api/v1/branches/{branch}/draft to confirm, rather than matching on the detail string.

The check runs inside the branch lock, so it cannot be raced by a concurrent save that creates a session. Another identity's draft never blocks you: only your own.

Errors

There is no rename and no update. The group maps exactly four routes: GET "", POST "", GET "/{domain}", DELETE "/{domain}". No PUT, no PATCH, and no rename code path exists anywhere in the Atlas interface. To rename a domain, create the new one, re-point whatever referenced the old one, and delete the old one. Note that a PATCH or PUT to this group matches no route, so Atlas answers with the single-page application shell as 200 text/html rather than 405.

List library imports#

Returns the libraries a domain imports through its ontology.jsonld @context, on one branch.

Request

GET /api/v1/branches/{branch}/domains/{domain}/imports

curl -H "Authorization: Bearer $ATLAS_TOKEN" \
  "https://<your-atlas-server>:4552/api/v1/branches/main/domains/brewing-operations/imports"

Response - 200 OK

["atlas-core", "isa95-common"]

An array of short names. Every @context string entry containing libraries/ is reduced to its file name without the .jsonld extension. The domain's own prefix object is not a string entry, so it never appears.

atlas-core heads the list for every domain created by the current writer, because create always writes it first.

Unlike everything else on this surface, this read is fully branch-scoped: it resolves the branch to a SHA and reads the pinned tree, so a domain that exists only on a branch resolves correctly.

Errors

A domain that exists but has no ontology.jsonld returns 200 [], not an error.

Add a library import#

Inserts a library reference into the domain's @context and commits.

Request

POST /api/v1/branches/{branch}/domains/{domain}/imports
Content-Type: application/json

{ "library": "isa95-common" }

curl -X POST \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"library":"isa95-common"}' \
  "https://<your-atlas-server>:4552/api/v1/branches/main/domains/brewing-operations/imports"

Response - 201 Created

{
  "domain": "brewing-operations",
  "library": "isa95-common"
}

No Location header on this one.

The entry is written as "../../libraries/{library}.jsonld" and inserted after the existing string entries but before the prefix object, so the @context ordering stays "libraries first, prefixes last". Use GET /api/v1/libraries (optional ?branch=) to see what library names exist.

Errors

Remove a library import#

Request

DELETE /api/v1/branches/{branch}/domains/{domain}/imports/{library}

curl -X DELETE \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  "https://<your-atlas-server>:4552/api/v1/branches/main/domains/brewing-operations/imports/isa95-common"

Response - 204 No Content

This call is idempotent in the loosest sense: the rewrite skips the matching @context entry and writes the file back, so removing a library that was never imported still commits and still returns 204. A 204 does not confirm that the import was there. Read the imports list back if you need to know.

Errors

Compile a domain#

PUT .../world is the compile trigger. A URL outside the API surface returns the single-page application shell as 200 text/html.

Request

PUT /api/v1/branches/{branch}/domains/{domain}/world

No request body.

curl -X PUT \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  "https://<your-atlas-server>:4552/api/v1/branches/main/domains/brewing-operations/world"

A compile is weighed against the licence before its world is published: if the compiled types or instances would take the installation over its Types or Instances entitlement, the call is refused with 403 Forbidden and an error code naming the entitlement, nothing is stored, and the previously cached world is untouched. Unload a domain you do not need (below) or model within the limit, then compile again. See Licensing and Entitlements.

Response - 200 OK

{
  "entityCount": 412,
  "edgeCount": 933,
  "archetypeCount": 27,
  "compiledAt": "2026-08-07T14:03:11.482Z",
  "functionErrors": []
}

There is no warnings member and no tripleCount.

The call is idempotent in the useful sense: every call is a full recompile that replaces the cached world for that (branch, domain) pair.

Compilation aborts, it does not degrade. If validation finds any error-severity violation, no world is built at all. The offending types are not skipped; nothing is compiled.

Response - 422 Unprocessable Entity, application/problem+json

{
  "type": "https://atlas.timebase.io/errors/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "3 violation(s) found in brewing-operations.",
  "violations": [
    {
      "ruleId": "O-B3",
      "severity": "Error",
      "filePath": "ontology.jsonld",
      "jsonPointer": "/@graph/7",
      "instanceId": null,
      "message": "...",
      "suggestion": "..."
    }
  ]
}

Each violation also carries occurrences: how many violations that one entry stands for. It is almost always 1, and larger only on a summary entry a rule emits in place of a fan-out it deliberately bounded. The count in detail is the sum of occurrences, not the length of the array, so a detail of "24431 violation(s) found" beside forty entries is correct. Sum occurrences if you total the list yourself.

The body is written by AtlasExceptionHandler.WriteValidationProblemAsync, which pins those eight violation fields. Rule IDs are O-A1 to O-A12 and O-B1 to O-B10 (there is no O-B5) for ontology rules, and I-A1 to I-A11 and I-B1 to I-B22 for instance rules. severity is the .NET enum name, so it is "Error" or "Warning" with a capital letter here, not camelCase like the rest of the surface. Only Error reaches a compile response; warnings never block and cannot appear in a 422.

Errors

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

Read compile status#

Request

GET /api/v1/branches/{branch}/domains/{domain}/world

Reads the cached world statistics without recompiling.

curl -H "Authorization: Bearer $ATLAS_TOKEN" \
  "https://<your-atlas-server>:4552/api/v1/branches/main/domains/brewing-operations/world"

Response - 200 OK

{
  "entityCount": 412,
  "edgeCount": 933,
  "archetypeCount": 27,
  "compiledAt": "2026-08-07T14:03:11.482Z",
  "isStale": false,
  "compiledAtSha": "9f3c1ab...",
  "currentSha": "9f3c1ab..."
}

Note the shape difference from the PUT: this response has isStale, compiledAtSha and currentSha but no functionErrors. They are two different records (WorldStatus versus CompileResult).

isStale: true is the answer to "did my import take effect?". After adding or removing an import, GET .../world will report the world stale, because the staleness check fans out across the domain's imported libraries. Compile again to clear it.

Errors

The 404 means "never compiled on this branch", not "no such domain". The cache is in-process and in-memory.

List compiled worlds#

The discovery endpoint: which (branch, domain) pairs are compiled and therefore queryable right now.

Request

GET /api/v1/worlds
GET /api/v1/worlds?branch=main&domain=brewing-operations

curl -H "Authorization: Bearer $ATLAS_TOKEN" \
  "https://<your-atlas-server>:4552/api/v1/worlds?branch=main"

Response - 200 OK

{
  "items": [
    {
      "branch": "main",
      "domain": "brewing-operations",
      "compiledAt": "2026-08-07T14:03:11.482Z",
      "entityCount": 412,
      "edgeCount": 933,
      "archetypeCount": 27,
      "isStale": false,
      "compiledAtSha": "9f3c1ab...",
      "currentSha": "9f3c1ab..."
    }
  ]
}

Note the envelope: an object with an items array, not a bare array like GET /api/v1/domains. A client that follows this list before querying will never hit Query.NotCompiled, because only compiled worlds appear. The filters are exact-match and case-sensitive, so a near-miss returns an empty items array rather than an error.

Unload a domain#

DELETE .../world removes a domain's compiled world from the cache. The domain stops answering queries and stops counting against the licensed Instances entitlement; its files are untouched, and a later PUT .../world rebuilds it.

Request

DELETE /api/v1/branches/{branch}/domains/{domain}/world

curl -X DELETE \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  "https://<your-atlas-server>:4552/api/v1/branches/main/domains/brewing-operations/world"

Response - 204 No Content, whether or not a world was cached. The call is idempotent on purpose: a teardown script never has to treat "already unloaded" as an error, and the machine plane does not say which of the two happened.

Deleting the domain, deleting the branch, or discarding a draft session that held a compiled world also evicts it, with the same effect on the licensed count.

Draft sessions and this surface#

Elsewhere in the Atlas API a save that fails validation returns 2xx while its content lands in the caller's private draft session and the target branch does not advance. The domain lifecycle writes are different, and the difference is intended.

Create, delete, add-import and remove-import all run through ExecuteInBranchAsync, which does raw file I/O and never runs the validation pipeline. They pass no validation outcome, so they can never produce an invalid verdict and therefore never create a draft session. A 201 or 204 from these routes means the commit is on the target branch, and no Atlas-Validation-Violations response header is stamped.

One exception, and it is the one to design around: if you already have a draft session on that branch from some earlier ontology save, these writes are routed into that existing draft worktree instead, and the target branch is not advanced. So a create can return 201 and still be invisible on the branch to everyone else. Check GET /api/v1/branches/{branch}/draft and publish with POST /api/v1/branches/{branch}/draft/publish.

Compile behaves the same way from the other side: when the caller is draft-routed, PUT .../world returns the full CompileResult but does not store the result in the shared world cache, so other callers keep reading the last compile of the real branch. Combined with the above, a caller who holds a draft session can create a domain, compile it, receive two success responses, and see no change on the branch and no change in anyone else's query results.

Troubleshooting#

Related articles#

• Atlas API Overview - base address, authentication, error envelope, full route table
• Atlas API Overview - Libraries
• Atlas API Overview - Ontology
• Atlas API Overview - Instance Maps
• Atlas API Overview - Query