> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nokia.atlas.arenaphysica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Metagraph

> Build and query the structured graph of entities and relationships that represents your system.

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](/guides/systems-and-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:**

```bash theme={null}
curl "https://nokia.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](#entity-object)             |
| `relationships` | array  | All [relationship objects](#relationship-object) |

**Example response:**

```json theme={null}
{
  "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:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/systems/$SYSTEM_ID/entities" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns an array of [entity objects](#entity-object).

***

## Get an entity

`GET /systems/{system_id}/entities/{entity_id}`

**Example request:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/systems/$SYSTEM_ID/entities/$ENTITY_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns a single [entity object](#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:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/systems/$SYSTEM_ID/relationships" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns an array of [relationship objects](#relationship-object).

***

## Get a relationship

`GET /systems/{system_id}/relationships/{relationship_id}`

**Example request:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/systems/$SYSTEM_ID/relationships/$REL_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

Returns a single [relationship object](#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) |

<Note>
  `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.
</Note>

**Example request:**

```bash theme={null}
curl -X POST "https://nokia.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:**

```json theme={null}
{
  "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:**

```bash theme={null}
curl -X PUT "https://nokia.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:**

```json theme={null}
{
  "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:**

```bash theme={null}
curl "https://nokia.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:**

```json theme={null}
[
  {
    "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:**

```bash theme={null}
curl -X POST "https://nokia.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](#set-entity-memories).