Atlas API - Instance Maps

Overview#

The instance-map surface is the machine-plane API for authoring the A-Box of a domain: the definitions that expand into the concrete instances your queries return. It is organised in two levels. A domain owns a set of .map.json files, and each file holds a list of definitions. You create and delete files, and you create, read, update and delete definitions inside them.

This article is the API reference: routes, verbs, request bodies, response bodies and status codes. It is written for developers building an integration against Atlas.

Three companion articles own material this one does not repeat:

• Atlas API Overview - base address, ports, authentication, the RFC-9457 error envelope, pagination, draft sessions and the retirement of /api/v2. Read it first.
• Instance Maps - the concept model: the three expansion shapes, [Name] placeholders, variables, transforms, relationships, compile behaviour.
• Property Sourcing Strategies - Static, Bound, and Calculated - what each strategy means and the exact format of a bindingPath.

The one thing to take away: almost every field name and route shape in circulation for this surface is out of date. Update is PATCH, the by-id routes carry no {fileName}, instanceBinding and relationships[] no longer exist, the strategy discriminator is type, and property keys must be full urn:atlas:ontology: URIs. Worse, most of those mistakes do not produce an error. See The unknown-property asymmetry and Troubleshooting.

Base path and authentication#

https://<your-atlas-server>:4552/api/v1/branches/{branch}/domains/{domain}/instance-maps

{branch} is a Git branch name, usually main. {domain} is the domain name. Instance maps are domain-scoped only: there is no library half, because A-Box data never lives in a shared library.

Every route in this article is registered under RequireAtlasApiAuth, so a Pulse-issued bearer token is required whenever Pulse:Auth:Enabled is true, which is the shipped default. Every example below sends one. See Atlas API Overview for how to obtain the token and why an unauthenticated call may return an HTML sign-in page rather than a 401.

There is a parallel /app/branches/{branch}/domains/{domain}/instance-maps group with the same five route shapes. That is the private cookie-authenticated glue for the Atlas single-page application, not an integration surface. Do not build against it.

Route table#

Relative to /api/v1/branches/{branch}/domains/{domain}:

A relationship's two endpoints come back from this route as columns, named atlas:Source and atlas:Target. See Atlas Value Hub.

An instance map names a connector by its alias. The interface shows the alias rather than the minted con_ id, which is the same identifier a binding path is written against, so what you read in a map and what you type into a path now match. The id still resolves wherever an alias does.

The first eight are authoring routes and read from the Git branch. The last four are read-only projections of the compiled world and are covered in Read compiled instances.

Instance map files#

List files#

Returns a bare JSON array of file stems, sorted, with the .map.json suffix removed.

GET /api/v1/branches/main/domains/brewing/instance-maps/
Authorization: Bearer <token>

200 OK

["fermentation-area", "line-a", "utilities"]

Create a file#

POST /api/v1/branches/main/domains/brewing/instance-maps/
Authorization: Bearer <token>
Content-Type: application/json

{ "name": "line-b" }

201 Created

{ "name": "line-b" }

The response echoes only the name. There is no Location header on this surface: Location is emitted only on domain, library and branch creation.

409 Conflict when the stem already exists. Matching is case-insensitive, so Line-B collides with line-b.

{
  "type": "https://atlas.timebase.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Instance map file 'line-b' already exists"
}

Delete a file#

Removes the file and every definition in it. Git history retains the content, but there is no API route to restore it.

DELETE /api/v1/branches/main/domains/brewing/instance-maps/line-b
Authorization: Bearer <token>

204 No Content. 404 Not Found when the stem does not exist.

Instance map definitions#

A definition is a template, not a single entity. Depending on what it declares, one definition expands into exactly one instance, a fixed set of instances, or one instance per row a connector returns. The three shapes and the rules that select between them are covered in Instance Maps; this article covers the wire shape only.

List the definitions in a file#

GET /api/v1/branches/main/domains/brewing/instance-maps/line-a/instances
Authorization: Bearer <token>

200 OK with a JSON array of raw definitions, exactly as stored. There is no read projection: what you get back is what is in the file. 404 Not Found when the file does not exist.

Read one definition#

GET /api/v1/branches/main/domains/brewing/instance-maps/instances/line-a-pumps
Authorization: Bearer <token>

200 OK with the raw definition. 404 Not Found when no file in the domain contains that id.

Note the route shape: /instance-maps/instances/{id}, with no file segment. This route wins precedence over /instance-maps/{fileName}/instances, which is exercised by the shipped HTTP tests.

Add a definition#

POST /api/v1/branches/main/domains/brewing/instance-maps/line-a/instances
Authorization: Bearer <token>
Content-Type: application/json

{
  "id": "line-a-pumps",
  "name": "Line A Transfer Pumps",
  "type": "urn:atlas:ontology:brewing:Pump",
  "instanceId": "urn:atlas:instance:brewing:pump-[Num, 00]",
  "label": "Transfer Pump [Num, 00]",
  "description": "Transfer pumps on Line A",
  "map": [
    { "name": "Num", "data": "1-4", "wrap": false }
  ],
  "properties": {
    "urn:atlas:ontology:brewing:nominalCapacity": [
      { "type": "StaticStrategy", "value": 250.0 }
    ],
    "urn:atlas:ontology:brewing:speed": [
      { "type": "BoundStrategy",
        "bindingPath": "historian-juice-factory/The Juice Factory/131-PT-[Num, 00].PV" }
    ]
  }
}

201 Created with the created definition as stored.

Request body fields

The accepted set is exactly id, name, type, instanceId, description, sources, map, properties, label, source, target. Nothing else is read.

id, name, type and instanceId are positional constructor parameters on the request record, so they are marked required in the OpenAPI document. Persisted-file validation (I-A2) is narrower: it enforces only id, type and instanceId. If you are reading a validation report and cannot find a rule for a missing name, that is why.

Fields that no longer exist

Both instanceBinding and relationships[] were removed from the model. Read the next section before you assume a 201 means they worked.

The unknown-property asymmetry#

This is the single most dangerous behaviour on this surface, and it is worth stating precisely because the two halves of Atlas disagree.

• On disk, InstanceMapStore parses .map.json with UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow. One unrecognised property name fails the parse, and the failure is reported against the whole file as rule I-A1, not against the one bad definition. A single stale instanceBinding takes out every definition in that file.
• Over the API, the request bodies are bound with the global Atlas wire options, which do not set UnmappedMemberHandling. The default applies, so an unrecognised JSON property is ignored.

So a POST carrying the relationships[] array returns 201 Created, persists a definition with no endpoints, and creates no edges when you compile. You get a green light and an empty graph. The same is true of instanceBinding: accepted, dropped, never applied.

Nothing in the response tells you a property was discarded. The only reliable check is to GET the definition back and compare it with what you sent.

The map array#

map declares the named variables the rest of the definition interpolates. Each entry:

Two rules that decide how many instances you get, both covered in full in Instance Maps:

Every declared variable must be referenced by something (instanceId, label, a property value, a binding path or a relationship endpoint), or the save reports rule I-A8.

Rowset sources#

sources replaces instanceBinding. It is a map from a source name you choose to a declaration with a connector bindingPath and an optional transforms map. Each transform is a regular expression with named capture groups, evaluated against one column of each row; captures become new columns, and a row whose regex does not match is dropped.

Taken from the shipped golden fixture:

{
  "id": "bound-machines",
  "name": "Bound Test Machines",
  "type": "urn:atlas:ontology:juice-factory:Machine",
  "instanceId": "BoundMachine-[Num, 00]",
  "sources": {
    "fillers": {
      "bindingPath": "historian-juice-factory/The Juice Factory/FillerTemps",
      "transforms": {
        "name": { "regex": "(?<Area>\\d+)\\-(?<Instrument>\\w+)\\-(?<FillerNumber>\\d+)\\.PV" }
      }
    }
  },
  "map": [
    { "name": "Num", "data": "[fillers.FillerNumber]", "wrap": false },
    { "name": "Tag", "data": "[fillers.name]", "wrap": false }
  ],
  "properties": {
    "urn:atlas:ontology:juice-factory:temperature": [
      { "type": "BoundStrategy",
        "bindingPath": "historian-juice-factory/The Juice Factory/[Tag]" }
    ]
  }
}

A definition may declare several sources, but its map entries may reference only one of them. Referencing two is rejected.

Relationships#

A relationship is not a sub-list inside an entity definition. It is an ordinary instance map whose type is a relationship archetype and which carries top-level source and target.

POST /api/v1/branches/main/domains/brewing/instance-maps/topology/instances
Authorization: Bearer <token>
Content-Type: application/json

{
  "id": "feeds-pump01-tank01",
  "name": "Feeds-Pump01-Tank01",
  "type": "urn:atlas:ontology:juice-factory:Feeds",
  "instanceId": "urn:atlas:instance:juice-factory:feeds-pump01-tank01",
  "source": "urn:atlas:instance:juice-factory:pump-01",
  "target": "urn:atlas:instance:juice-factory:tank-01",
  "properties": {
    "urn:atlas:ontology:juice-factory:flowRate": [
      { "type": "StaticStrategy", "value": 2.5 }
    ]
  }
}

Four rules govern the two endpoint fields:

1. Both or neither. A map that declares either endpoint must declare both. Rule I-A9 reports A relationship instance map must declare both 'source' and 'target'; 'target' is missing. An entity map declares neither.
2. They carry instance identities, not definition ids. Each endpoint is matched against the set of expanded instance identities across the whole domain. Putting a definition id there produces a dangling-endpoint violation (I-B6).
3. They are templates. Both accept the same [Name] placeholder syntax as instanceId and are resolved once per expanded row, so one definition can create many edges. Because resolution runs over the full instance set, the two ends may come from entirely different definitions and different files. That decoupling is the point.
4. Edge properties are ordinary properties. A relationship's properties block works exactly like an entity's. There is no separate edge-property surface, and the inline edge sub-resource routes were retired with relationships[].

Rule I-B5 additionally requires the type to be a relationship archetype, and I-B7 checks each resolved endpoint against the archetype's source and target type constraints.

Property strategies#

properties maps a full property URI to a list of strategy entries. Both halves matter.

The key must be a full URI. A short name is accepted by the POST, then flagged by rule I-A4 and dropped at compile:

Property key 'speed' is not a full URI. Property keys must start with 'urn:atlas:ontology:' (short names are dropped at compile).

There is one URN namespace for all five ontology kinds: urn:atlas:ontology:{scope}:{LocalName}. There is no urn:atlas:fn:, no urn:atlas:prop:, no urn:atlas:class: and no urn:atlas:rel:. A functionUri and a propertyUri both use the ontology namespace. Instance identities use the separate urn:atlas:instance: base.

The value is a list because strategies are time-intervalled. Each entry may carry validFrom; when omitted the entry applies from the beginning of time. If a property only ever has one source, the list has one entry.

The discriminator is type, not strategy, and there are six legal values:

Anything else is rejected by rule I-A5:

Strategy type 'Manual' is not recognised. Allowed values: StaticStrategy, BoundStrategy, CalculatedStrategy, NullStrategy, CompositeStrategy, ReferenceStrategy.

There is no Manual strategy. The place to type a value in by hand is StaticStrategy.

Full strategy entry shape:

A CalculatedStrategy argument entry has type ("literal" or "propertyRef"), parameter, order, plus value for a literal or propertyUri for a property reference. A propertyRef may also carry instanceUri to read the input from another instance, which is how you aggregate across instances. parameter accepts either the bare parameter name or the full parameter URI; bare names are rejected only when ambiguous.

"urn:atlas:ontology:juice-factory:temperatureCelsius": [
  {
    "type": "CalculatedStrategy",
    "functionUri": "urn:atlas:ontology:juice-factory:FahrenheitToCelsius",
    "arguments": [
      { "type": "propertyRef",
        "parameter": "urn:atlas:ontology:juice-factory:param/fahrenheit",
        "propertyUri": "urn:atlas:ontology:juice-factory:temperature",
        "order": 0 }
    ]
  }
]

For what each strategy means in practice and the binding-path format per connector, see Property Sourcing Strategies.

Update a definition#

Update is PATCH, not PUT. A PUT matches no route and is answered with the single-page application shell as 200 text/html.

PATCH /api/v1/branches/main/domains/brewing/instance-maps/instances/line-a-pumps
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Line A Transfer Pumps (rev B)",
  "description": "Motor replaced 2026-04"
}

200 OK with the merged definition. 404 Not Found when no file contains that id.

The merge rule is: an omitted field is left unchanged. This is what makes clearing a collection impossible without the typed clear array below. Note also that id is not on the update body at all: it cannot be changed by PATCH.

Accepted fields: name, description, type, instanceId, sources, map, properties, label, source, target, clear.

The typed clear array

clear names the fields to erase. A field named here is cleared even when its value member is absent or null. Token matching is case-insensitive.

PATCH /api/v1/branches/main/domains/brewing/instance-maps/instances/feeds-pump01-tank01
Authorization: Bearer <token>
Content-Type: application/json

{ "clear": ["source", "target"] }

200 OK, and both endpoints are erased.

Delete a definition#

DELETE /api/v1/branches/main/domains/brewing/instance-maps/instances/line-a-pumps
Authorization: Bearer <token>

204 No Content. 404 Not Found when no file contains that id.

There is no dependents guard on this delete: nothing in the ontology references an instance map by id. A relationship definition whose endpoint you have just orphaned will surface as an I-B6 violation at the next save or compile, not as a 409 here.

Read compiled instances#

These four routes read the compiled world, not the branch. They return nothing until the domain has been compiled with PUT /api/v1/branches/{branch}/domains/{domain}/world. An uncompiled domain returns 400, not 404:

{
  "type": "https://atlas.timebase.io/errors/invalid-request",
  "title": "Invalid Request",
  "status": 400,
  "detail": "Domain 'brewing' on branch 'main' has not been compiled."
}

The {instanceId} path segment is the durable instance URN, percent-encoded. urn:atlas:instance:plant:pump-01 becomes urn%3Aatlas%3Ainstance%3Aplant%3Apump-01.

List instances#

GET /api/v1/branches/main/domains/brewing/instances?type=urn:atlas:ontology:brewing:Pump&page=1&pageSize=100
Authorization: Bearer <token>

200 OK

{
  "items": [
    { "elementId": "urn:atlas:instance:brewing:pump-01",
      "typeUri": "urn:atlas:ontology:brewing:Pump",
      "label": "pump-01" }
  ],
  "totalCount": 4,
  "page": 1,
  "pageSize": 100
}

label here is derived from the last colon-separated segment of elementId, and is null when the identity does not follow that convention. It is not the label template from the instance map definition.

Read one instance#

GET /api/v1/branches/main/domains/brewing/instances/urn%3Aatlas%3Ainstance%3Abrewing%3Apump-01
Authorization: Bearer <token>

200 OK with a single {elementId, typeUri, label} record. 404 when the instance is not in the compiled world. 400 when the domain is not compiled.

Read an instance's relationships#

GET /api/v1/branches/main/domains/brewing/instances/urn%3A…%3Apump-01/relationships?direction=both
Authorization: Bearer <token>

direction accepts outgoing, incoming or both; omitted means both.

200 OK

{
  "items": [
    { "edgeElementId": "urn:atlas:instance:brewing:feeds-pump01-tank01",
      "relationshipTypeUri": "urn:atlas:ontology:brewing:Feeds",
      "relationshipTypeLabel": "Feeds",
      "sourceElementId": "urn:atlas:instance:brewing:pump-01",
      "targetElementId": "urn:atlas:instance:brewing:tank-01",
      "direction": "outgoing" }
  ]
}

edgeElementId is populated when edges are reified in the compiled world, and is null otherwise. This is a structural traversal: edge property values are not included here. Read them by querying the relationship instance itself.

Read an instance's current values#

GET /api/v1/branches/main/domains/brewing/instances/urn%3A…%3Apump-01/values
Authorization: Bearer <token>

200 OK

{
  "items": [
    { "propertyUri": "urn:atlas:ontology:brewing:nominalCapacity",
      "value": 250.0,
      "quality": "Good" }
  ]
}

This is a pull-read snapshot. For a live feed, subscribe to the value hub at /hubs/v1/branches/{branch}/domains/{domain}/subscribe.

quality is one of Good, GoodNoData, Uncertain, Bad. In the shipped implementation a property that holds a value maps to Good and one that holds no value to GoodNoData, with "value": null. No value means nothing has arrived from the source yet, the static value is blank, or a calculation returned none. A timestamp member exists on the record but is omitted from the response when null, and null responses are stripped by the global wire options.

Status codes and errors#

Every failure is RFC-9457 application/problem+json with a frozen type URI. There is no error field, no message field, no path field, and no universal code extension on this surface. Branch your client on the type URI. See Atlas API Overview for the full type table.

Responses use camelCase names, omit null members entirely, and serialize enums as camelCase strings. A client that expects null members to be present will break.

A 2xx does not mean the change is on the branch#

Instance-map writes go through the same write orchestrator as every other Atlas save, so two behaviours apply here in full:

• A save carrying error-severity validation violations returns success, lands in the caller's private draft session, and does not advance the target branch. The only signal is the Atlas-Validation-Violations response header, carrying the count of outstanding violations. The header is absent, not 0, on a clean save.
• Once a draft session exists, every subsequent write on that branch, valid or not, stays in the session until you publish with POST /api/v1/branches/{branch}/draft/publish.

So the read-your-write check for this surface is: inspect Atlas-Validation-Violations on every write, then GET /api/v1/branches/{branch}/domains/{domain}/validation for the rule ids, then publish if a session exists. The mechanism is described once in Atlas API Overview.

Validation rules you will actually hit#

Instance-map rules are I-A1 to I-A11 (format, checked against the persisted file) and I-B1 to I-B22 (semantics, checked against the ontology and the expanded instance set). The ones this API surface generates most often:

GET /api/v1/branches/{branch}/domains/{domain}/validation returns the authoritative current list.

After you write: compile#

Nothing you author here exists as an instance until the domain is compiled.

PUT /api/v1/branches/main/domains/brewing/world
Authorization: Bearer <token>

200 OK returns CompileResult {entityCount, edgeCount, archetypeCount, compiledAt, functionErrors[]}. There is no warnings member.

422 with a violations[] array means compilation aborted and no world was built. Compilation does not degrade: it does not skip the offending definitions and build the rest.

GET .../world reports isStale and compiledAtSha without recompiling. Atlas recompiles every recorded branch and domain pair at startup, so a manual recompile after a restart is normally unnecessary. The exception is a domain with rowset sources whose connector has not advertised yet: that domain waits for the connector and stays uncompiled if it never appears.

Troubleshooting#

Related articles#

• Atlas API Overview
• Instance Maps
• Property Sourcing Strategies - Static, Bound, and Calculated - Static, Bound, and Calculated
• Atlas API Overview - Ontology
• Atlas API Overview - Query
• Atlas API Overview - Connectors