Overview#

The Ontology API reads and writes the type definitions that make up an Atlas model. There are five ontology resources, and each one is mounted twice: once under a domain and once under a library.

Resource	Route segment	What it defines
Entity types	`entity-types`	The kinds of thing in your model (`Pump`, `Tank`, `ProductionLine`)
Properties	`properties`	Standalone value definitions, attached to the types that carry them
Data types	`data-types`	Compound value shapes: several named fields that travel together, such as `TVQ`
Relationship types	`relationship-types`	Named, directed connections, with their own properties
Functions	`functions`	Reusable calculation logic

This article is written for developers building an integration against Atlas. It documents the request bodies, response bodies, verbs and status codes of all 54 ontology endpoints.

Read Atlas API Overview first. That article is the single source of truth for the base address, authentication, the RFC-9457 error envelope, pagination and the /api/v2 surface. This article does not restate any of it and links back wherever it matters. For the meaning of the words used here (domain, library, branch, ontology, compile, draft session, binding path), see Timebase Atlas Key Concepts.

The three corrections most likely to break an existing client#

nodes is now entity-types and relationships is now relationship-types. Both renames were part of the /api/v1 cutover. A request to the old segment does not return 404: the single-page-application fallback answers it with 200 text/html. See the Overview article's Troubleshooting table.
Update is PATCH for entity types, properties and relationship types. PUT survives only for data types and functions. Sending the wrong verb also gives you the HTML shell, not a 405.
Data types are a full ontology resource. If your integration models anything historian-bound, you need them.

Scopes: every route is mounted twice#

Each of the five resources has an identical domain group and library group. The request bodies, response bodies and status codes are the same; only the scope segment differs.

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

{branch} is always required and is a Git branch name, typically main. {domain} and {library} are the lowercased, hyphenated internal names, not display labels.

Every example in this article uses the domain scope. To use the library scope, swap domains/{domain} for libraries/{library} and change nothing else.

Note

Libraries hold types only. They have no instances, no compiled World and no compile step, so an ontology write to a library is complete once it commits. A domain still needs PUT /api/v1/branches/{branch}/domains/{domain}/world before the change is queryable.

Authentication#

/api/v1 requires a Pulse-issued bearer token whose aud claim includes Atlas (Authentication is required on all ten ontology route groups). A browser session cookie is not accepted on this plane. Every example below sends the header; do not omit it.

Authorization: Bearer <your-pulse-token>

Note

Git commit authorship comes from the authenticated caller's sub and name claims, defaulting to Anonymous when Auth:Enabled is false.

Serialization#

Responses use camelCase property names, omit null members entirely rather than emitting null, and serialize enums as camelCase strings, so NodeKind.Entity arrives as "entity". A strongly typed client that expects every declared member to be present will see gaps. The response samples in this article show the fields as they appear when populated.

201 Created responses carry the created resource in the body. Ontology creates do not set a Location header (only domain, library and branch creation do), so do not build a client that follows it.

Naming: one URN namespace for all five kinds#

Every entity type, property, data type, relationship type and function is identified by a URN with exactly one shape:

urn:atlas:ontology:{scope}:{LocalName}

{scope} is the domain or library name. {LocalName} is the name you supplied on create. A Plant entity type in the lonestar-plant scope is:

urn:atlas:ontology:lonestar-plant:Plant

There are no per-kind prefixes. urn:atlas:class:, urn:atlas:prop:, urn:atlas:rel: and urn:atlas:fn: do not exist and never did on this surface. A Cypher query or binding path built on one matches nothing. In the shipped libraries every @id resolves to urn:atlas:ontology:..., for example urn:atlas:ontology:atlas-common:TVQ.

Two adjacent namespaces you will also encounter in responses:

urn:atlas:vocab:... for the Atlas framework vocabulary, such as urn:atlas:vocab:NodeBase, urn:atlas:vocab:ContainsBase and urn:atlas:vocab:RelationshipBase.
urn:atlas:instance:... for individual instances in the compiled World.

`{name}` in a route is the local name#

Every single-item route addresses the resource by its local name, not its URI. GET .../entity-types/Pump, never GET .../entity-types/urn:atlas:ontology:brewery:Pump. The server mints the URI from the scope and the name.

A name collision across kinds is rejected#

Because all five kinds mint from the same namespace, a name is unique across the whole scope, not just within its own kind. Creating a property called Tank in a scope that already has an entity type called Tank fails with 409 Conflict:

{
  "type": "https://atlas.timebase.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "Cannot create Property 'Tank': the key 'urn:atlas:ontology:brewery:Tank' is already used by a Type. All element kinds (Types, Properties, Relationships, Data Types, Functions) share one URN namespace per domain."
}

This is a different failure from a same-kind duplicate, which reports Property 'Tank' already exists. The cross-kind case cannot be fixed by switching to an update: pick a different local name. The occupying kind is named in the detail string as one of Type, Property, Relationship, Data Type or Function.

What a successful write actually means#

This is the single most consequential behaviour on the ontology surface, and it changed. Read it before you write anything.

A save that fails validation still returns 2xx. When an ontology write leaves the scope with outstanding error-severity violations, the content is committed to the caller's private draft session and the target branch does not advance. You still receive 201 Created or 200 OK with the resource in the body. Nobody else sees the change.

A valid save commits straight through. It runs in a throwaway worktree, fast-forwards the target branch and leaves nothing behind. There is no session to publish and nothing else to do.

So a draft session is not a mode you opt into. Having one means "I have unpublished work that does not validate".

The only signal is a response header#

Atlas-Validation-Violations: 3

The header carries the count of outstanding error-severity violations in the state the write just persisted. It is absent on a clean save, not 0. Check for its presence on every write.

The header carries only a count. To get the actionable list, read the violations resource:

GET /api/v1/branches/{branch}/domains/{domain}/validation
GET /api/v1/branches/{branch}/libraries/{library}/validation

To promote your draft onto the branch:

POST /api/v1/branches/{branch}/draft/publish

Rule IDs in the violations you get back are O-A* and O-B* for ontology problems and I-A* and I-B* for instance-map problems. See the Validation Rules Reference for what each one means and how to clear it.

Important

Function creates and updates are the one exception to "saves return 2xx". They run a synchronous pre-save validator and reject with 422 before anything is persisted. See Function validation.

`rdfs:domain` on a property is now a validation error#

If you migrate hand-written JSON-LD into Atlas, note that property-to-type attachment moved onto the entity class as an owl:Restriction. An rdfs:domain on a property definition is reported as O-A12. Atlas framework vocabulary under urn:atlas:vocab: and the atlas: CURIE are exempt; your own subjects never are.

Compile is a separate action with a different failure shape#

PUT /api/v1/branches/{branch}/domains/{domain}/world returns 422 with a violations[] array and builds no World when validation fails. Do not conflate the two: saves return 2xx and route to a draft; compile returns 422 and aborts. Full detail is in the Overview article.

Note

when the caller is draft-routed, the compile builds your own copy and leaves the shared world in place. Combined with a draft-routed save, a write and a compile can both succeed while the branch is unchanged. Check Atlas-Validation-Violations, then GET /api/v1/branches/{branch}/draft, and publish.

Entity types#

An entity type is a kind of thing. It may inherit from a parent entity type and it carries a set of attached properties.

Routes#

Operation	Method and path	Success
List	`GET .../entity-types`	`200`
Get one	`GET .../entity-types/{name}`	`200`
Create	`POST .../entity-types`	`201`
Update	`PATCH` `.../entity-types/{name}`	`200`
Delete	`DELETE .../entity-types/{name}`	`204`
Attach a property	`PUT .../entity-types/{name}/properties/{property}`	`204`
Detach a property	`DELETE .../entity-types/{name}/properties/{property}`	`204`

Declared (domain) and (library).

List all entity types#

GET /api/v1/branches/main/domains/brewery/entity-types
Authorization: Bearer <your-pulse-token>

Response - 200 OK

[
  {
    "uri": "urn:atlas:ontology:brewery:Pump",
    "label": "Pump",
    "comment": "Centrifugal pump",
    "parentType": "urn:atlas:ontology:opc10030-isa95-common:Equipment",
    "kind": "entity",
    "properties": [
      {
        "uri": "urn:atlas:ontology:brewery:Speed",
        "label": "Speed",
        "attachedTypes": ["urn:atlas:ontology:brewery:Pump"],
        "range": "http://www.w3.org/2001/XMLSchema#double",
        "isObjectProperty": false
      }
    ]
  }
]

Read field	Type	Notes
`uri`	string	Full URN. Minted from scope plus local name
`label`	string	Display name. Omitted when null
`comment`	string	Description. Omitted when null
`parentType`	string	Full URI of the `rdfs:subClassOf` parent. Omitted when the type has no parent
`properties`	array	The full property read models the type carries, declared and inherited
`sourceLibrary`	string	Short name of the imported library that declared this type. Omitted for types declared in the scope you are reading
`kind`	string	`"entity"` or `"dataType"`. A camelCase enum string, never `0` or `1`
`timeAxisField`	string	Set only when `kind` is `"dataType"`. The bare local name of the compound's time-axis field

Note

The entity-types list is a read over all classes, so compound data types appear here too, discriminated by kind: "dataType". Filter on kind if you want entities only. Data types are authored through the data-types resource, never through this one.

Get a single entity type#

GET /api/v1/branches/main/domains/brewery/entity-types/Pump
Authorization: Bearer <your-pulse-token>

{name} is the local name. Returns 200 with a single object in the shape above, or 404 when no entity type of that name exists in the scope.

Create an entity type#

POST /api/v1/branches/main/domains/brewery/entity-types
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "name": "Compressor",
  "label": "Gas Compressor",
  "comment": "Reciprocating gas compressor",
  "parentType": "Equipment",
  "properties": ["Speed", "Description"]
}

Field	Type	Required	Description
`name`	string	Yes	Local name, PascalCase. Must be unique across all five kinds in this scope
`label`	string	No	Display name
`comment`	string	No	Description
`parentType`	string	No	Local name or full URI of the parent type. May reference a type from an imported library
`properties`	string[]	No	Local names or full URIs of existing properties to attach in the same atomic commit

Response - 201 Created, body is the created entity type read model.

properties is the atomic create-plus-attach path (AddEntityTypeRequest). Every entry is resolved before anything is written, so one unresolvable reference fails the whole create and the type is never half-created. That failure is 400 Bad Request with the detail Cannot attach property '<ref>' - no such property in scope..

parentType resolution searches the current scope first, then the Atlas framework vocabulary roots, then every loaded entity by local-name suffix. If nothing matches, it falls back to a scope-local URI, and whole-scope validation reports it.

Update an entity type#

PATCH /api/v1/branches/main/domains/brewery/entity-types/Compressor
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "label": "Reciprocating Compressor",
  "properties": ["Speed", "Description", "UOM"]
}

PATCH is a partial merge. Fields you do not send are preserved.

Field	Type	Semantics
`label`	string	`null` or omitted leaves it unchanged
`comment`	string	`null` or omitted leaves it unchanged
`parentType`	string	`null` or omitted leaves it unchanged
`properties`	string[]	Full replacement of the type's declared attachments. `null` or omitted leaves them untouched; `[]` detaches every declared attachment

Response - 200 OK, body is the updated read model. 404 when the name does not exist.

The properties replacement is all-or-nothing and lands as one commit with the metadata edit, so a metadata change never persists alone when an attachment reference is bad. Inherited attachments, declared on an ancestor type, are never affected by this list.

Delete an entity type#

DELETE /api/v1/branches/main/domains/brewery/entity-types/Compressor
Authorization: Bearer <your-pulse-token>

Response - 204 No Content. 404 when the name does not exist.

Entity types carry no per-item dependents guard, so check for references before you delete one. Unlike properties, data types and functions, a delete that leaves a dangling reference is not blocked with a 409. It is caught by whole-scope re-validation instead, which aborts the write. Practically that means the delete either succeeds cleanly or routes to your draft session with an Atlas-Validation-Violations header.

Attach and detach a property#

This is the primary day-to-day ontology edit and it is a sub-resource of the entity type, not of the property.

PUT    /api/v1/branches/main/domains/brewery/entity-types/Pump/properties/Speed
DELETE /api/v1/branches/main/domains/brewery/entity-types/Pump/properties/Speed
Authorization: Bearer <your-pulse-token>

Both return 204 No Content with no body. Neither takes a request body.

Behaviour	Attach (`PUT`)	Detach (`DELETE`)
Already in the target state	Idempotent no-op success	`404`, the property is not among the type's declared attachments
Unknown entity type	`404`	`404`
Unknown property	`404`	`404`
Entity type declared by an imported library	`400`	`400`

The write subject is the entity class, which is what makes cross-scope attachment work: a property imported from a library attaches to a local type by construction, and the change persists only in the local type's file. The reverse is not allowed. Attaching onto a type that an import declared would be a phantom write, validated and read back but dropped by the scope-filtered save, so it is rejected with 400 and the detail Entity type '<name>' is declared by an import ('<uri>') and cannot be modified from this scope. Attach properties to it from its declaring library instead.

Detach is surgical: it retracts exactly one restriction and only from the type's declared attachments. An attachment inherited from an ancestor cannot be detached from a subtype.

Note

attachment is addressed under the entity type. If your client called GET, PUT or DELETE on .../properties/{name}/attached-types/..., move it to the route above. See the Overview article's Troubleshooting table.

Properties#

A property is a standalone value definition. It is not owned by a type. The attachment link lives on the type, and the same property can be attached to any number of types.

Routes#

Operation	Method and path	Success
List	`GET .../properties`	`200`
Get one	`GET .../properties/{name}`	`200`
Create	`POST .../properties`	`201`
Update	`PATCH` `.../properties/{name}`	`200`
Delete	`DELETE .../properties/{name}`	`204`, or `409` when blocked

Declared (domain) and (library).

List all properties#

GET /api/v1/branches/main/domains/brewery/properties
Authorization: Bearer <your-pulse-token>

Response - 200 OK

[
  {
    "uri": "urn:atlas:ontology:brewery:Speed",
    "label": "Speed",
    "comment": "Shaft speed in RPM",
    "attachedTypes": [
      "urn:atlas:ontology:brewery:Pump",
      "urn:atlas:ontology:brewery:Compressor"
    ],
    "range": "http://www.w3.org/2001/XMLSchema#double",
    "isObjectProperty": false
  }
]

Read field	Type	Notes
`uri`	string	Full URN
`label`, `comment`	string	Omitted when null
`attachedTypes`	string[]	Full URIs of the types this property is declared on, not inherited attachments. Unioned with any compound data types that link it as a field
`range`	string	The value type URI. Omitted when the property carries a compound or union range instead
`isObjectProperty`	boolean	`true` when the property links to another entity type
`defaultConfig`	object	The class-level default sourcing strategy, in the same flat shape you post. Omitted when none is set
`compoundRange`	object	Present when the range is a compound with pinned field types
`subPropertyOf`	string	Full URI of the first asserted `rdfs:subPropertyOf`. Omitted when none
`unionMembers`	string[]	Read-only projection of an `owl:unionOf` range. Omitted for a single-URI range
`rangeUnion`	string[]	The write-side union carrier
`sourceLibrary`	string	Short name of the imported library that declared it. Omitted for locally declared properties

Note

the field is attachedTypes and it is an array. There is no domain field on a property; in Atlas the word means the workspace. A client reading body.domain gets undefined, and the singular string it expected could never represent a property attached to several types anyway.

An empty attachedTypes is legal. A property attached to nothing stays available until you attach it, and is not reached by any type read.

Get a single property#

GET /api/v1/branches/main/domains/brewery/properties/Speed
Authorization: Bearer <your-pulse-token>

200 with a single object, or 404.

Create a property#

POST /api/v1/branches/main/domains/brewery/properties
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "name": "TargetSpeed",
  "label": "Target Speed",
  "comment": "Setpoint speed in RPM",
  "attachToTypes": ["Pump"],
  "range": "xsd:double",
  "isObjectProperty": false
}

Field	Type	Required	Description
`name`	string	Yes	Local name. Must be unique across all five kinds in this scope
`label`	string	No	Display name
`comment`	string	No	Description
`attachToTypes`	string[]	Yes	Local names or full URIs of the entity types to attach this property to, in the same commit. One class-side `owl:Restriction` per entry. Send `[]` to create the property unattached
`range`	string	No	The value type. An XSD CURIE (`xsd:double`, `xsd:string`, `xsd:boolean`, `xsd:dateTime`, `xsd:integer`), a data type local name such as `TVQ`, or an entity type local name for an object property
`isObjectProperty`	boolean	No	Defaults to `false`
`defaultConfig`	object	No	A class-level default sourcing strategy for this property. `StaticStrategy`, `BoundStrategy` or `CalculatedStrategy`; `ReferenceStrategy` is rejected. See Property Sourcing Strategies
`fieldTypeOverrides`	object	No	Pins individual fields of a compound range to an XSD CURIE, for example `{"Value": "xsd:double"}`. When set, `range` is the base compound local name. Mutually exclusive with `rangeUnion`
`subPropertyOf`	string	No	Local name of the `rdfs:subPropertyOf` base property. Organizational metadata only
`rangeUnion`	string[]	No	XSD CURIE members of an authored value-type union. Two or more members produce an `owl:unionOf` range; exactly one collapses to a plain single-URI range

Response - 201 Created, body is the created property read model.

Note the asymmetry that catches people out: you send attachToTypes and you read back attachedTypes.

range values carrying a reserved CURIE prefix (xsd:, rdf:, rdfs:, owl:) pass through unscoped and are expanded to a full URI downstream. Anything else is resolved against the loaded ontology.

Update a property#

PATCH /api/v1/branches/main/domains/brewery/properties/TargetSpeed
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "label": "Speed Setpoint",
  "attachToTypes": ["Pump", "Compressor"]
}

PATCH is a partial merge; unsent fields are preserved. Every field is independently nullable.

Field	Semantics
`label`, `comment`	`null` or omitted leaves unchanged
`attachToTypes`	Full replacement of the declared attachment set. `null` leaves it untouched; `[]` detaches every declared attachment
`range`, `isObjectProperty`	`null` or omitted leaves unchanged
`fieldTypeOverrides`	`null` or empty leaves the existing range untouched, plain or compound
`subPropertyOf`	`null` leaves unchanged; `""` clears it
`rangeUnion`	`null` leaves the existing range untouched

Response - 200 OK, or 404 when the name does not exist.

Delete a property#

DELETE /api/v1/branches/main/domains/brewery/properties/TargetSpeed
Authorization: Bearer <your-pulse-token>

Response - 204 No Content when nothing references it.

409 Conflict when a type still declares it, or a data type links it as a field. The body is an RFC-9457 problem with target and dependents extensions:

{
  "type": "https://atlas.timebase.io/errors/delete-blocked",
  "title": "Delete Blocked",
  "status": 409,
  "detail": "Cannot delete 'TargetSpeed' — it is declared on 2 types. Detach from those types first.",
  "target": { "name": "TargetSpeed", "kind": "property" },
  "dependents": [
    { "id": "Pump", "name": "Pump", "kind": "entity", "referenceType": "type-declares-property" },
    { "id": "Compressor", "name": "Compressor", "kind": "entity", "referenceType": "type-declares-property" }
  ]
}

The dependents list is never truncated. Note that the dependent kind is renamed from type to entity on this surface, to match the entity-types naming. Clear the block by detaching from each listed type first, using DELETE .../entity-types/{type}/properties/{name}.

Data types#

A data type is a compound: one property value made of several named fields that always travel together. This is the fifth ontology resource, a peer of the other four, and it shares their URN namespace.

The canonical example ships in the atlas-common library as TVQ, for Timestamp-Value-Quality, and it is how nearly every measurement in Atlas is shaped.

Routes#

Operation	Method and path	Success
List	`GET .../data-types`	`200`
Get one	`GET .../data-types/{name}`	`200`
Create	`POST .../data-types`	`201`
Update	`PUT` `.../data-types/{name}`	`200`
Delete	`DELETE .../data-types/{name}`	`204`, or `409` when blocked

Declared (domain) and (library).

The library scope gained PUT and DELETE in this cutover. ### List all data types

GET /api/v1/branches/main/domains/brewery/data-types
Authorization: Bearer <your-pulse-token>

Response - 200 OK

[
  {
    "uri": "urn:atlas:ontology:atlas-common:TVQ",
    "sourceLibrary": "atlas-common",
    "fields": [
      { "name": "Timestamp", "typeUri": "urn:atlas:ontology:atlas-common:Timestamp", "isTimeAxis": true },
      { "name": "Value",     "typeUri": "urn:atlas:ontology:atlas-common:Value",     "isTimeAxis": false },
      { "name": "Quality",   "typeUri": "urn:atlas:ontology:atlas-common:Quality",   "isTimeAxis": false }
    ]
  }
]

Read field	Type	Notes
`uri`	string	Full URN
`fields`	array	Already sorted by the persisted `atlas:fieldOrder`, so the array order is the author's intended field order
`fields[].name`	string	Bare local name of the linked property
`fields[].typeUri`	string	Full URI of the property that supplies this field
`fields[].isTimeAxis`	boolean	`true` on at most one field
`sourceLibrary`	string	Short name of the imported library that declared it. Omitted for locally declared data types

Important

The data-type read model carries only uri, fields and sourceLibrary. It does not return label or comment, even though the create and update bodies accept both. Do not build a client that round-trips a data type by reading it and sending it back: the label and comment are cleared. Read the label from the entity-types list instead, where the same subject appears with kind: "dataType" and carries label, comment and timeAxisField.

Get a single data type#

GET /api/v1/branches/main/domains/brewery/data-types/TVQ
Authorization: Bearer <your-pulse-token>

200 with a single object, or 404.

Create a data type#

POST /api/v1/branches/main/domains/brewery/data-types
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "name": "TVQR",
  "label": "TVQ with Rate",
  "comment": "Measurement tuple carrying a derived rate",
  "fields": ["Timestamp", "Value", "Quality", "Rate"],
  "timeAxisField": "Timestamp"
}

Field	Type	Required	Description
`name`	string	Yes	Local name. Must be unique across all five kinds in this scope
`label`	string	No	Display name. Persisted but not returned by the data-type read
`comment`	string	No	Description. Persisted but not returned by the data-type read
`fields`	string[]	Yes	Local names or full URIs of existing first-class properties to link as fields, in field order. The array index is the `fieldOrder`. Selection only, never inline definitions
`timeAxisField`	string	No	Which entry of `fields` is the time axis. Must resolve to one of `fields` and must be a `dateTime`-ranged property. At most one per data type. `null` means no axis

Response - 201 Created, body is the created data-type read model.

Three rules bite here:

Fields are selected, not defined. Each entry must already exist as a property in the scope or in an imported library. The write mints only the field-membership edge; the linked property already carries its own range.
No field may resolve to a property declared by an import when the compound itself is local, because the scope-filtered save would drop that back-pointer. This is rejected rather than allowed to become a phantom write.
The array is a complete roster. There is no per-field add or remove operation.

An unresolvable timeAxisField fails the write with DataType.UnknownTimeAxisField.

Note

The time axis is what tells Atlas which field means "when this happened". Time-range queries and point normalization both depend on it. A compound with no time axis still compiles but cannot participate in either.

Update a data type#

Update is PUT, not PATCH. The backend retracts the prior compound and re-emits the class plus every field edge in one commit, so relabelling, adding, removing and reordering fields all land together.

PUT /api/v1/branches/main/domains/brewery/data-types/TVQR
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "label": "TVQ with Rate",
  "comment": "Measurement tuple carrying a derived rate",
  "fields": ["Timestamp", "Value", "Quality", "Rate", "Confidence"],
  "timeAxisField": "Timestamp"
}

Field	Type	Semantics
`label`, `comment`	string	Sent value replaces the stored value. Omitting them clears them
`fields`	string[]	Full replacement of the roster, in field order. An empty list clears every field
`timeAxisField`	string	Full replacement. `null` or omitted clears any previously declared axis

Response - 200 OK, body is the updated read model. 404 when the name does not exist.

Important

PUT here is a genuine replacement, not a merge. Because the read model does not return label, comment or timeAxisField, and because omitting them clears them, a read-modify-write needs all three fields sent back. Always send the complete intended body. The URI key itself is immutable: to rename a data type, create a new one and delete the old.

Delete a data type#

DELETE /api/v1/branches/main/domains/brewery/data-types/TVQR
Authorization: Bearer <your-pulse-token>

Response - 204 No Content, or 409 Conflict with target and dependents when something still references it.

Two reference shapes block the delete:

Dependent `kind`	`referenceType`	Meaning
`property`	`property-ranges-over-data-type`	A property whose `range` is this data type
`dataType`	`data-type-nests-data-type`	Another data type that links a property whose range is this data type

{
  "type": "https://atlas.timebase.io/errors/delete-blocked",
  "title": "Delete Blocked",
  "status": 409,
  "detail": "Cannot delete 'TVQR' — it is referenced by 1 dependent.",
  "target": { "name": "TVQR", "kind": "dataType" },
  "dependents": [
    { "id": "Flow", "name": "Flow", "kind": "property", "referenceType": "property-ranges-over-data-type" }
  ]
}

Relationship types#

A relationship type is a named, directed connection with a Source end and a Target end. In Atlas a relationship is a thing, not a line: it is reified as an instance in its own right, it carries its own property values, and it is created by its own instance map with top-level source and target templates.

Important

Because relationships are first-class and carry properties natively, the old advice to promote a data-bearing association into an intermediate entity type is now strictly worse than the native shape. Model it as a relationship type with properties and give it its own instance map.

Important

author each connection as its own instance map definition. The inline relationships[] form is not part of the current shape, and an unrecognised JSON property is ignored, so sending it returns 201 with no edges created.

Routes#

Operation	Method and path	Success
List	`GET .../relationship-types`	`200`
Get one	`GET .../relationship-types/{name}`	`200`
Create	`POST .../relationship-types`	`201`
Update	`PATCH` `.../relationship-types/{name}`	`200`
Delete	`DELETE .../relationship-types/{name}`	`204`

Declared (domain) and (library).

Note

/relationships at instance scope is a different resource. The ontology resource is relationship-types.

List all relationship types#

GET /api/v1/branches/main/domains/brewery/relationship-types
Authorization: Bearer <your-pulse-token>

Response - 200 OK

[
  {
    "uri": "urn:atlas:ontology:brewery:LineContainsPump",
    "label": "Line Contains Pump",
    "comment": "Physical containment of a pump within a brewing line",
    "baseType": "urn:atlas:vocab:ContainsBase",
    "sourceNodeType": "urn:atlas:ontology:brewery:BrewingLine",
    "targetNodeType": "urn:atlas:ontology:brewery:Pump",
    "properties": ["urn:atlas:ontology:brewery:CommissionedOn"],
    "isContainment": true
  }
]

Read field	Type	Notes
`uri`	string	Full URN
`label`, `comment`	string	Omitted when null
`baseType`	string	The framework root as a full URI, `urn:atlas:vocab:ContainsBase` or `urn:atlas:vocab:RelationshipBase`, or the URI of the relationship type this one narrows
`parent`	string	The immediate user-defined `rdfs:subClassOf` super-relationship-type. Distinct from `baseType`. Omitted when there is none
`sourceNodeType`	string	Full URI of the entity type allowed at the Source end. Omitted when the end is unconstrained ("any node")
`targetNodeType`	string	Full URI of the entity type allowed at the Target end
`properties`	string[]	Full URIs of the edge properties attached to this relationship class, merged across the parent chain. Excludes the reserved Source and Target members
`isContainment`	boolean	`true` when the type is rooted at `ContainsBase`, directly or transitively. Drives hierarchy views
`sourceLibrary`	string	Short name of the imported library that declared it. Omitted for locally declared types

Create a relationship type#

POST /api/v1/branches/main/domains/brewery/relationship-types
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "name": "LineContainsPump",
  "baseType": "ContainsBase",
  "label": "Line Contains Pump",
  "comment": "Physical containment of a pump within a brewing line",
  "sourceNodeType": "BrewingLine",
  "targetNodeType": "Pump",
  "properties": ["CommissionedOn"]
}

Field	Type	Required	Description
`name`	string	Yes	Local name, PascalCase. Must be unique across all five kinds in this scope
`baseType`	string	Yes	`ContainsBase` for containment, `RelationshipBase` for a peer association, or the full URI of an existing relationship type to narrow. See the warning below
`label`	string	No	Display name
`comment`	string	No	Description, stored as `rdfs:comment`
`sourceNodeType`	string	No	Local name or full URI of the entity type at the Source end. Use `NodeBase` for "any node". Omit for unconstrained
`targetNodeType`	string	No	Local name or full URI of the entity type at the Target end
`properties`	string[]	No	Local names or full URIs of existing properties to attach as first-class edge data

Response - 201 Created, body is the created read model with parent and merged inherited constraints populated.

Important

baseType is resolved with the URN resolver, which prefixes any value that is not already a full URI with urn:atlas:vocab:. So "ContainsBase" correctly becomes urn:atlas:vocab:ContainsBase, but a bare local name such as "Feeds" becomes urn:atlas:vocab:Feeds, which is not a class that exists. To narrow an existing relationship type, send its full URI (urn:atlas:ontology:{scope}:Feeds), not its local name. A local name here fails later at whole-scope validation, not at the create.

Edge properties

properties is how a relationship carries data of its own: a flow rate on a feeds, a commissioning date on a contains. Each entry becomes an owl:Restriction on the relationship class, the same shape the Source and Target ends use, so no new vocabulary is involved.

Primitive-ranged edge properties compile end to end. Give a relationship property a scalar value type such as xsd:double, or carry a compound on one of the connected entity types.

Update a relationship type#

PATCH /api/v1/branches/main/domains/brewery/relationship-types/LineContainsPump
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "label": "Brewing Line Contains Pump",
  "targetNodeType": "CentrifugalPump",
  "properties": []
}

PATCH is a partial merge. Note that name and baseType are not updatable.

Field	Semantics
`label`	`null` or omitted leaves unchanged
`comment`	`null` or omitted leaves unchanged. Any non-null value, including `""`, replaces it
`sourceNodeType`	Three-state. `null` or omitted leaves the end unchanged; `""` clears it back to "any node" and drops the restriction; a name or URI replaces it
`targetNodeType`	Three-state, exactly as `sourceNodeType`
`properties`	Full replacement of the edge properties. `null` leaves them untouched; `[]` clears them all

Response - 200 OK, or 404 when the name does not exist.

The ""-to-clear sentinel on the endpoints is undiscoverable from the wire and there is no other way to relax a constrained end back to "any node". Note the asymmetry: on comment, "" sets an empty comment; on the two endpoints, "" is a clear sentinel.

Delete a relationship type#

DELETE /api/v1/branches/main/domains/brewery/relationship-types/LineContainsPump
Authorization: Bearer <your-pulse-token>

Response - 204 No Content. 404 when the name does not exist.

Like entity types, relationship types have no per-item dependents guard. A dangling reference is caught by whole-scope re-validation, which aborts the write.

Functions#

A function is reusable calculation logic with named parameters, one structured output, an inline C# body, and optionally a normalization anchor. Functions have full CRUD on both scopes. They are not read-only and they are not written for you by the instance-map layer.

A function has no schedule and no trigger settings. A calculated value is worked out when something reads it.

Routes#

Operation	Method and path	Success
List	`GET .../functions`	`200`
Get one	`GET .../functions/{name}`	`200`
Create	`POST .../functions`	`201`, or `422` on validation
Update	`PUT` `.../functions/{name}`	`200`, or `422` on validation
Delete	`DELETE .../functions/{name}`	`204`, or `409` when blocked

Declared (domain) and (library).

List all functions#

GET /api/v1/branches/main/domains/brewery/functions
Authorization: Bearer <your-pulse-token>

Response - 200 OK

[
  {
    "uri": "urn:atlas:ontology:brewery:ConvertFlowRate",
    "label": "Convert Flow Rate",
    "comment": "Scales a raw flow reading by a calibration coefficient",
    "parameters": [
      {
        "name": "rawFlow",
        "type": "http://www.w3.org/2001/XMLSchema#double",
        "predicateUri": "urn:atlas:ontology:brewery:param/rawFlow",
        "required": true
      },
      {
        "name": "coefficient",
        "type": "http://www.w3.org/2001/XMLSchema#double",
        "predicateUri": "urn:atlas:ontology:brewery:param/coefficient",
        "required": true
      }
    ],
    "output": {
      "name": "flow",
      "type": "http://www.w3.org/2001/XMLSchema#double",
      "predicateUri": "urn:atlas:ontology:brewery:output/flow"
    },
    "returnType": "http://www.w3.org/2001/XMLSchema#double",
    "implementation": {
      "body": "return rawFlow * coefficient;"
    }
  }
]

Read field	Type	Notes
`uri`	string	Full URN
`label`, `comment`	string	Omitted when null
`library`	string	Optional library marker on the function
`parameters`	array	Ordered input list
`parameters[].name`	string	The local C# identifier used in the body
`parameters[].type`	string	The value type URI
`parameters[].predicateUri`	string	Non-nullable. The full predicate URI used as the arguments-dictionary key at execution time, and the key an instance map's Calculated strategy binds against
`parameters[].required`	boolean	Defaults to `true`
`parameters[].label`, `.comment`	string	Label and comment on the shared predicate declaration
`output`	object	The single structured output: `name`, `type`, `predicateUri`, `label`
`returnType`	string	Computed convenience only. It is a projection of `output.type` and cannot be set independently
`implementation.body`	string	C# method-body statements only. No signature, no braces. The compiler wraps it in a scaffold
`anchor`	object	Present only on multi-row functions. See below

Note

returnType appears on the wire as a read-only view over output.type. Author a function by sending the structured output object.

Create a function#

POST /api/v1/branches/main/domains/brewery/functions
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "name": "ConvertFlowRate",
  "label": "Convert Flow Rate",
  "comment": "Scales a raw flow reading by a calibration coefficient",
  "parameters": [
    {
      "name": "rawFlow",
      "type": "xsd:double",
      "predicateUri": "urn:atlas:ontology:brewery:param/rawFlow",
      "required": true
    },
    {
      "name": "coefficient",
      "type": "xsd:double",
      "predicateUri": "urn:atlas:ontology:brewery:param/coefficient",
      "required": true
    }
  ],
  "output": {
    "name": "flow",
    "type": "xsd:double",
    "predicateUri": "urn:atlas:ontology:brewery:output/flow"
  },
  "implementation": {
    "body": "return rawFlow * coefficient;"
  }
}

Field	Type	Required	Description
`name`	string	Yes	Local name. Must be unique across all five kinds in this scope
`label`, `comment`	string	No	Display name and description
`library`	string	No	Library marker
`parameters`	array	Yes	Ordered inputs. Each entry needs `name`, `predicateUri`, and normally `type`
`output`	object	Yes in practice	Exactly one output is required by validation. `name`, `type`, `predicateUri`
`implementation`	object	Yes in practice	`{ "body": "..." }`. A non-empty body is required by validation
`anchor`	object	No	Normalization-anchor spec. `null` means single-row

Response - 201 Created. The body is a save envelope, not the bare read model:

{
  "function": { "uri": "urn:atlas:ontology:brewery:ConvertFlowRate", "...": "..." },
  "compileDiagnostics": [
    {
      "id": "CS0019",
      "severity": "Error",
      "message": "Operator '*' cannot be applied to operands of type 'string' and 'double'",
      "line": 1,
      "column": 8
    }
  ]
}

Atlas compiles the body as part of the save and returns the compiler's diagnostics in compileDiagnostics, empty when the body is clean. line and column are 1-based and relative to the first line of the body you sent, not to a file.

The save itself is not blocked by a diagnostic: a body that does not compile is still stored, and the function is set aside at compile time until it does. Treat a non-empty compileDiagnostics as work to finish rather than as a failed write. A 422 remains the validation path, for the O-F rules.

The predicate URIs are domain-shared and reused across functions. They follow the convention {scope-urn}:param/{name} and {scope-urn}:output/{name}. They are what an instance map's Calculated strategy binds arguments against, so they are part of your model's contract, not an implementation detail.

Anchors and multi-row normalization

An anchor turns a scalar converter into one that aligns two or more time series onto a common instant before calculating.

{
  "anchor": {
    "outputField": "Timestamp",
    "inputs": [
      { "parameterName": "rawFlow",     "inputField": "Timestamp" },
      { "parameterName": "coefficient", "inputField": "Timestamp" }
    ]
  }
}

Field	Description
`outputField`	The datetime field on the output compound that the anchor resolves to
`inputs[].parameterName`	Matches a `parameters[].name`
`inputs[].inputField`	The datetime field on that input's compound whose sample timestamps drive the anchor grid

When anchor is set, the compiler runs the function multi-row and auto-injects a single anchor local fed by the union of the contributing inputs. null or an empty inputs array means single-row, and no provenance nodes are emitted.

Point normalization needs both halves: the data type must declare a time axis, and the function must declare contributing anchor inputs. Without both, the calculation returns a number built from each input at its latest known value, which is the ordinary behaviour.

Update a function#

Update is PUT. The backend retracts the prior fno:Function subgraph and re-asserts a complete one, so relabelling and signature, output, implementation and anchor changes all land in one commit.

PUT /api/v1/branches/main/domains/brewery/functions/ConvertFlowRate
Authorization: Bearer <your-pulse-token>
Content-Type: application/json

{
  "label": "Convert Flow Rate (calibrated)",
  "implementation": {
    "body": "return rawFlow * coefficient * 1.02;"
  }
}

Despite the PUT verb, each top-level field is independently nullable and null means "leave unchanged" (UpdateFunctionRequest):

Field	Semantics
`label`, `comment`, `library`	`null` or omitted leaves unchanged
`parameters`	`null` leaves the existing signature untouched. A sent list replaces it wholesale
`output`	`null` leaves the existing output untouched
`implementation`	`null` leaves the existing body untouched
`anchor`	`null` leaves the existing anchor untouched. A spec with an empty `inputs` array clears the anchor back to single-row. A populated spec replaces it

Response - 200 OK, or 404 when the name does not exist, or 422 on validation.

Function validation: O-F1 to O-F5#

Functions are the one ontology resource with a synchronous pre-save validator. A rejected create or update returns 422 Unprocessable Content as application/problem+json and nothing is persisted, so the draft-session behaviour described earlier does not apply.

Rule	What it checks
`O-F1`	Identity. The name must be non-empty and its URI must not already be taken
`O-F2`	Type resolvability. Every input and output type must resolve to a primitive or a known compound
`O-F3`	Predicate clash. A shared parameter predicate reused with a different type than an existing declaration
`O-F4`	Shape. Exactly one output, and a non-empty implementation body
`O-F5`	Anchor consistency. The output field and every contributing input field must be valid datetime fields on the right compounds

The 422 body:

{
  "type": "https://atlas.timebase.io/errors/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "1 violation(s) found in brewery.",
  "violations": [
    {
      "ruleId": "O-F4",
      "severity": "Error",
      "filePath": "ontology.jsonld",
      "message": "A function must declare exactly one output."
    }
  ]
}

jsonPointer, instanceId and suggestion also appear on each violation when populated.

Delete a function#

DELETE /api/v1/branches/main/domains/brewery/functions/ConvertFlowRate
Authorization: Bearer <your-pulse-token>

Response - 204 No Content, or 409 Conflict when an instance-map Calculated strategy still references it.

{
  "type": "https://atlas.timebase.io/errors/delete-blocked",
  "title": "Delete Blocked",
  "status": 409,
  "detail": "Cannot delete 'ConvertFlowRate' — it is referenced by 1 dependent.",
  "target": { "name": "ConvertFlowRate", "kind": "function" },
  "dependents": [
    { "id": "pumps", "name": "pumps", "kind": "instanceMap", "referenceType": "calculated-strategy" }
  ]
}

Clear the block by changing the strategy on each listed instance map first.

Errors on this surface#

All failures are RFC-9457 application/problem+json. The full type-URI table lives in the Atlas API Overview. These are the shapes specific to the ontology resources:

Status	Type URI token	When
`400`	`.../errors/invalid-request`	An attachment reference does not resolve; a write targets a subject declared by an import
`404`	`.../errors/not-found`	The scope, branch, or named resource does not exist; a detach targets a property that is not declared on the type
`409`	`.../errors/conflict`	A same-kind duplicate name, or a cross-kind key collision. Read the `detail` to tell them apart
`409`	`.../errors/delete-blocked`	Properties, data types and functions only. Adds `target` and `dependents`
`422`	`.../errors/validation-failed`	Function create and update only, on this surface. Adds `violations[]`

Note

There is no universal code field. The generic error path emits only type, title, status and detail, plus the framework's traceId. Branch your client on the type URI. On the ontology surface no endpoint emits a code extension.

The `/app` plane is not an alternative#

Every route in this article has a twin under /app/branches/{branch}/... that dispatches the same commands and returns the same wire shapes. It is private glue for the Atlas single-page application, excluded from the published API documents, gated by a session cookie for reads and an inline admin check for writes. A bearer token does not clear it.

Browser code inside Atlas uses /app. Machine integrations use /api/v1. Picking the wrong one is a guaranteed 401. Do not build against /app.

Troubleshooting#

Symptom	Cause	What to do
A request returns `200 text/html` instead of JSON	The path matched no route and the single-page-application fallback answered it. Almost always `nodes` instead of `entity-types`, `relationships` instead of `relationship-types`, `/api/v2` instead of `/api/v1`, or `PUT` where `PATCH` is expected	Check `Content-Type` before parsing. Then check the segment and the verb against the route tables above
An update returns no change and no `405`	The verb does not match a route on that group	Entity types, properties and relationship types use `PATCH`. Data types and functions use `PUT`
A write returned `201` or `200` but the change is not on the branch	The save carried outstanding validation errors and was routed to your private draft session	Check for the `Atlas-Validation-Violations` response header, read `GET .../validation` for the list, fix, then `POST /api/v1/branches/{branch}/draft/publish`
You saved, you compiled, and nothing changed	Both of the above at once. A draft-routed compile does not overwrite the shared World cache	Check `GET /api/v1/branches/{branch}/draft`, publish, then compile again
`409` on create and your handler says "already exists", but the name is free for that kind	A cross-kind key collision. All five kinds share one URN namespace per scope	Read the `detail`, which names the occupying kind. Pick a different local name. An update cannot fix this
Your client reads `property.domain` and gets `undefined`	The field is `attachedTypes` on read, and it is an array	Read `attachedTypes`. Write `attachToTypes`
A property you created never appears on the type you meant	`attachToTypes` was empty or omitted. An unattached property is valid and is simply never reached by a type read	Attach it with `PUT .../entity-types/{type}/properties/{name}`
You cannot attach a property to a type imported from a library	The write subject must live in the save scope. Attaching onto an imported class would be dropped by the scope-filtered save	Attach it from the declaring library's scope, or create a local subtype and attach there
Detach returns `404` for a property you can see on the type	The attachment is inherited from an ancestor, not declared on this type. Detach only touches declared attachments	Detach from the ancestor that declares it, or accept the inheritance
A data-type round trip cleared the label and comment	The data-type read model does not return `label` or `comment`, and `PUT` is a full replacement	Always send the complete intended body on `PUT .../data-types/{name}`
A relationship type you narrowed does not resolve	`baseType` prefixes any non-URI value with `urn:atlas:vocab:`, so a bare local name becomes a vocabulary class that does not exist	Send the full URI `urn:atlas:ontology:{scope}:{Name}` to narrow an existing relationship type
You cannot relax a relationship end back to "any node"	The clear sentinel is an empty string, not `null`. `null` means "leave unchanged"	`PATCH` with `"sourceNodeType": ""`
An instance map created a relationship but no edges exist	The inline `relationships[]` form is not part of the current shape, and an unrecognised property is ignored	Author the relationship as its own instance map whose `type` is the relationship archetype, with top-level `source` and `target`
`POST .../functions` returns `422` and the save never lands	Functions run a synchronous pre-save validator	Read the `violations[]` array and fix the `O-F1` to `O-F5` rule reported
A calculated property is always `0`	A function parameter was left unbound on the instance map. That is rule `I-B22`, which is only a warning and never blocks a compile	Check the warning count on `GET .../validation`
A `409` on delete that your handler reports as "name already exists"	A blocked delete uses the distinct type `.../errors/delete-blocked` and carries `target` and `dependents`	Branch on the `type` URI, not the status code, and show the `dependents` list
Migrating hand-written JSON-LD fails with `O-A12`	The file carries `rdfs:domain` on a property, the retired attachment shape	Remove it. Express attachment as an `owl:Restriction` on the entity class, or by sending `attachToTypes`
Deleted type still appears in query results	The domain has not been recompiled	`PUT /api/v1/branches/{branch}/domains/{domain}/world`. `GET .../world` reports `isStale` without recompiling
`401` on every call	`/api/v1` needs a Pulse bearer whose `aud` includes `Atlas`. A cookie is not accepted	See Authentication in the Atlas API Overview

Atlas API Overview - base address, authentication, the full route table, RFC-9457 errors, pagination
Timebase Atlas Key Concepts - the vocabulary this article assumes
Validation Rules Reference - every O-A*, O-B*, O-F*, I-A* and I-B* rule
Atlas API - Instance Maps - authoring the instances these types describe, including relationship instance maps
Atlas API - Domains and Atlas API - Libraries - creating the scopes these routes address
Atlas API - Compile and Query - reading the compiled World
Compiling and Publishing a Domain - the compile lifecycle and draft publishing