Metagraph

The metagraph is Atlas’s living model of a system. Entities are the nodes (subsystems, components, interfaces, signals, and resources). Relationships are the directed edges connecting them. Together they form the structured representation Atlas reasons over. See Populating the System Metagraph for a workflow guide.

Endpoints

Method	Path	Description
`GET`	`/systems/{system_id}/metagraph`	Get the full metagraph for a system
`GET`	`/systems/{system_id}/entities`	List entities
`GET`	`/systems/{system_id}/entities/{entity_id}`	Get an entity
`GET`	`/systems/{system_id}/relationships`	List relationships
`GET`	`/systems/{system_id}/relationships/{relationship_id}`	Get a relationship
`POST`	`/systems/metagraphs/{system_id}/batch-save`	Batch create/update/delete entities and relationships
`PUT`	`/systems/{system_id}/entities/{entity_id}/memories`	Set entity memories
`GET`	`/systems/{system_id}/entities/{entity_id}/memories/history`	Get entity memory history
`POST`	`/systems/{system_id}/entities/{entity_id}/memories/restore`	Restore entity memory version

Get full metagraph

GET /systems/{system_id}/metagraph Returns all entities and relationships for a system in a single response. Example request:

curl "https://spacex.atlas.arenaphysica.com/api/v1/systems/$SYSTEM_ID/metagraph" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Response fields:

Field	Type	Description
`system_id`	UUID	System identifier
`system_name`	string	System display name
`description`	string	System description
`entities`	array	All entity objects
`relationships`	array	All relationship objects

Example response:

{
  "system_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "system_name": "Power Distribution Unit",
  "description": "24V DC power distribution system",
  "entities": [
    {
      "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "entity_type": "COMPONENT",
      "name": "Battery Management IC",
      "description": "Monitors cell voltages and controls charge/discharge FETs"
    }
  ],
  "relationships": [
    {
      "uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "relationship_type": "PROVIDES",
      "name": "BMS provides power rail",
      "source_entity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "target_entity_id": "d4e5f6a7-b8c9-0123-defa-234567890123"
    }
  ]
}

List entities

GET /systems/{system_id}/entities Query parameters:

Parameter	Required	Type	Description
`entity_type`	No	string	Filter by entity type (e.g. `COMPONENT`, `SUBSYSTEM`)
`include_pending`	No	boolean	Include pending entities. Defaults to `false`
`external_id`	No	string	Filter by external reference ID

Example request:

curl "https://spacex.atlas.arenaphysica.com/api/v1/systems/$SYSTEM_ID/entities" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Returns an array of entity objects.

Get an entity

GET /systems/{system_id}/entities/{entity_id} Example request:

curl "https://spacex.atlas.arenaphysica.com/api/v1/systems/$SYSTEM_ID/entities/$ENTITY_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Returns a single entity object.

Entity object

Field	Type	Nullable	Description
`uuid`	UUID	No	Entity identifier
`system_id`	UUID	No	Parent system
`entity_type`	string	No	Entity type enum value
`name`	string	No	Display name
`description`	string	Yes	Description
`external_id`	string	Yes	External reference
`attributes`	array	No	List of attribute objects
`artifacts`	array	No	List of artifact references
`memories`	string	No	Entity memory content (empty string if none)
`memories_updated_at`	string	Yes	ISO 8601 timestamp of last memory update
`memories_contributors`	array	No	Emails of users who have written memories
`is_deleted`	boolean	No	Soft-delete flag
`is_pending`	boolean	No	Whether entity is pending approval
`created_by`	string	No	Creator email
`created_at`	string	No	ISO 8601 creation timestamp
`updated_at`	string	No	ISO 8601 last-update timestamp

Entity types:

Value	Description
`SYSTEM`	Top-level product or platform
`SUBSYSTEM`	Functional or organizational grouping
`COMPONENT`	Atomic functional element
`INTERFACE`	Shared connection point or protocol
`RESOURCE`	Finite consumable (power, bandwidth, etc.)
`SIGNAL`	Information flow (measurements, commands, state)

List relationships

GET /systems/{system_id}/relationships Query parameters:

Parameter	Required	Type	Description
`relationship_type`	No	string	Filter by relationship type (e.g. `CONTAINS`, `PROVIDES`)
`include_pending`	No	boolean	Include pending relationships. Defaults to `false`

Example request:

curl "https://spacex.atlas.arenaphysica.com/api/v1/systems/$SYSTEM_ID/relationships" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Returns an array of relationship objects.

Get a relationship

GET /systems/{system_id}/relationships/{relationship_id} Example request:

curl "https://spacex.atlas.arenaphysica.com/api/v1/systems/$SYSTEM_ID/relationships/$REL_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Returns a single relationship object.

Relationship object

Field	Type	Nullable	Description
`uuid`	UUID	No	Relationship identifier
`system_id`	UUID	No	Parent system
`relationship_type`	string	No	Relationship type enum value
`name`	string	No	Edge label
`source_entity_id`	UUID	No	Origin entity
`target_entity_id`	UUID	No	Destination entity
`description`	string	Yes	Description
`external_id`	string	Yes	External reference
`attributes`	array	No	Attribute objects
`artifacts`	array	No	Artifact references
`memories`	string	No	Memory content (empty string if none)
`memories_updated_at`	string	Yes	ISO 8601 memory update timestamp
`memories_contributors`	array	No	Contributor emails
`is_deleted`	boolean	No	Soft-delete flag
`is_pending`	boolean	No	Pending approval flag
`created_by`	string	No	Creator email
`created_at`	string	No	ISO 8601 creation timestamp
`updated_at`	string	No	ISO 8601 last-update timestamp

Relationship types:

Value	Description
`CONTAINS`	Hierarchical parent-to-child
`DEPENDS_ON`	Operational dependency
`CONNECTS`	Physical or logical connection
`PROVIDES`	Supplies a resource or signal
`CONSUMES`	Receives a resource or signal
`INFLUENCES`	Cross-domain impact

Batch save

POST /systems/metagraphs/{system_id}/batch-save Create, update, or delete multiple entities and relationships in a single request. This is the recommended way to mutate the metagraph because it correctly increments the version number. Request body:

Field	Required	Type	Description
`creates`	No	array	Entity create objects (see below)
`updates`	No	array	Entity update objects (must include `id`)
`deletes`	No	array	Entity UUIDs to delete
`relationship_creates`	No	array	Relationship create objects (see below)
`relationship_updates`	No	array	Relationship update objects (must include `id`)
`relationship_deletes`	No	array	Relationship UUIDs to delete
`base_version`	No	integer	If provided, the save is rejected when the current version has advanced past this value (optimistic concurrency)

Entity create fields:

Field	Required	Type	Description
`local_id`	Yes	string	Temporary client-side ID. Use this to reference newly created entities in `relationship_creates` within the same request
`type`	Yes	string	Entity type (`SYSTEM`, `SUBSYSTEM`, `COMPONENT`, `INTERFACE`, `RESOURCE`, `SIGNAL`)
`name`	Yes	string	Display name
`parent_ids`	No	array of string	IDs of parent entities
`description`	No	string	Human-readable description
`properties`	No	object	Key-value string pairs

Entity update fields:

Field	Required	Type	Description
`id`	Yes	string	UUID of the entity to update
`name`	No	string	Updated display name
`type`	No	string	Updated entity type
`parent_ids`	No	array of string	Updated parent IDs
`description`	No	string	Updated description
`properties`	No	object	Updated key-value pairs (set a value to `null` to remove it)

Relationship create fields:

Field	Required	Type	Description
`edge_type`	Yes	string	Relationship type (`CONTAINS`, `DEPENDS_ON`, `CONNECTS`, `PROVIDES`, `CONSUMES`, `INFLUENCES`)
`source_id`	Yes	string	Origin entity UUID or `local_id` from `creates`
`target_id`	Yes	string	Destination entity UUID or `local_id` from `creates`
`name`	No	string	Short label for the edge
`properties`	No	object	Key-value string pairs

Relationship update fields:

Field	Required	Type	Description
`id`	Yes	string	UUID of the relationship to update
`relationship_type`	No	string	Updated relationship type
`name`	No	string	Updated edge label
`description`	No	string	Updated description
`properties`	No	object	Updated key-value pairs (set a value to `null` to remove it)

CONTAINS relationships cannot be created via relationship_creates. Instead, set parent_ids on the child entity in creates — Atlas will generate the CONTAINS edge automatically.

Example request:

curl -X POST "https://spacex.atlas.arenaphysica.com/api/v1/systems/metagraphs/$SYSTEM_ID/batch-save" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "creates": [
      {"local_id": "pwr-mgmt", "type": "SUBSYSTEM", "name": "Power Management"},
      {"local_id": "vreg", "type": "COMPONENT", "name": "Voltage Regulator", "parent_ids": ["pwr-mgmt"]},
      {"local_id": "rail", "type": "RESOURCE", "name": "12V Rail"}
    ],
    "relationship_creates": [
      {
        "edge_type": "PROVIDES",
        "source_id": "vreg",
        "target_id": "rail",
        "name": "Voltage Regulator provides 12V Rail"
      }
    ]
  }'

Response fields:

Field	Type	Description
`version`	integer	New metagraph version number after save
`entities_created`	integer	Number of entities created
`entities_updated`	integer	Number of entities updated
`entities_deleted`	integer	Number of entities deleted
`relationships_created`	integer	Number of relationships created
`relationships_updated`	integer	Number of relationships updated
`relationships_deleted`	integer	Number of relationships deleted

Example response:

{
  "version": 7,
  "entities_created": 2,
  "entities_updated": 0,
  "entities_deleted": 0,
  "relationships_created": 1,
  "relationships_updated": 0,
  "relationships_deleted": 0
}

Set entity memories

PUT /systems/{system_id}/entities/{entity_id}/memories Replaces memory content for an entity. Writes are versioned automatically. Request body:

Field	Required	Type	Description
`content`	Yes	string	Memory content (markdown supported)

Example request:

curl -X PUT "https://spacex.atlas.arenaphysica.com/api/v1/systems/$SYSTEM_ID/entities/$ENTITY_ID/memories" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Cell voltages drift above 85°C. BMS compensation firmware required above thermal threshold."
  }'

Response fields:

Field	Type	Nullable	Description
`content`	string	No	Current memory content
`updated_at`	string	Yes	ISO 8601 timestamp of the last update
`contributors`	array of string	No	Emails of users who have written to this memory

Example response:

{
  "content": "Cell voltages drift above 85°C. BMS compensation firmware required above thermal threshold.",
  "updated_at": "2026-04-13T11:00:00.000000",
  "contributors": ["engineer@example.com"]
}

Get entity memory history

GET /systems/{system_id}/entities/{entity_id}/memories/history Returns all previous versions of an entity’s memory document. Example request:

curl "https://spacex.atlas.arenaphysica.com/api/v1/systems/$SYSTEM_ID/entities/$ENTITY_ID/memories/history" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Response fields (array):

Field	Type	Nullable	Description
`version`	integer	No	Version number (1-indexed)
`content`	string	No	Memory content at this version
`updated_at`	string	No	ISO 8601 timestamp
`restored_from_version`	integer	Yes	Version this was restored from, if applicable

Example response:

[
  {
    "version": 2,
    "content": "Cell voltages drift above 85°C. BMS compensation firmware required above thermal threshold.",
    "updated_at": "2026-04-13T11:00:00.000000",
    "restored_from_version": null
  },
  {
    "version": 1,
    "content": "Cell voltages drift above 85°C.",
    "updated_at": "2026-04-12T09:00:00.000000",
    "restored_from_version": null
  }
]

Restore entity memory version

POST /systems/{system_id}/entities/{entity_id}/memories/restore Rolls back an entity’s memory to a previous version. Creates a new version entry rather than overwriting history. Request body:

Field	Required	Type	Description
`version`	Yes	integer	Version number to restore (must be ≥ 1)

Example request:

curl -X POST "https://spacex.atlas.arenaphysica.com/api/v1/systems/$SYSTEM_ID/entities/$ENTITY_ID/memories/restore" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version": 1}'

Returns the restored memory object with the same fields as Set entity memories.

Overview

Resources

Endpoints

Get full metagraph

List entities

Get an entity

Entity object

List relationships

Get a relationship

Relationship object

Batch save

Set entity memories

Get entity memory history

Restore entity memory version

Overview

Resources

​Endpoints

​Get full metagraph

​List entities

​Get an entity

​Entity object

​List relationships

​Get a relationship

​Relationship object

​Batch save

​Set entity memories

​Get entity memory history

​Restore entity memory version

Endpoints

Get full metagraph

List entities

Get an entity

Entity object

List relationships

Get a relationship

Relationship object

Batch save

Set entity memories

Get entity memory history

Restore entity memory version