> ## 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.

# Systems

> Create and manage systems — the top-level organizational boundary in Atlas.

A system is a hardware project you're building, operating, or analyzing. All metagraph data, jobs, issues, test runs, and sessions are scoped to a system.

See [Populating the System Metagraph](/guides/systems-and-metagraph) for a workflow guide.

## Endpoints

| Method   | Path                       | Description                            |
| -------- | -------------------------- | -------------------------------------- |
| `POST`   | `/systems`                 | Create a system                        |
| `GET`    | `/systems`                 | List systems                           |
| `GET`    | `/systems/{system_id}`     | Get a system                           |
| `PUT`    | `/systems/{system_id}`     | Update a system                        |
| `DELETE` | `/systems/{system_id}`     | Delete a system                        |
| `POST`   | `/systems/upload_document` | Upload a reference document            |
| `GET`    | `/system-memories`         | Search entity memories across a system |

***

## Create a system

`POST /systems`

**Request body:**

| Field         | Required | Type   | Description                 |
| ------------- | -------- | ------ | --------------------------- |
| `system_name` | Yes      | string | Display name for the system |
| `description` | No       | string | Optional description        |

**Example request:**

```bash theme={null}
curl -X POST "https://nokia.atlas.arenaphysica.com/api/v1/systems" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "system_name": "Power Distribution Unit",
    "description": "24V DC power distribution system for the vehicle platform"
  }'
```

**Response fields:**

| Field            | Type    | Nullable | Description                                  |
| ---------------- | ------- | -------- | -------------------------------------------- |
| `system_id`      | UUID    | No       | Unique system identifier                     |
| `system_name`    | string  | No       | Display name                                 |
| `description`    | string  | Yes      | System description                           |
| `has_blueprints` | boolean | No       | Whether the system has associated blueprints |
| `created_by`     | string  | No       | Email of the user who created the system     |
| `created_at`     | string  | No       | ISO 8601 creation timestamp                  |
| `is_deleted`     | boolean | No       | Soft-delete flag                             |

**Example response:**

```json theme={null}
{
  "system_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "system_name": "Power Distribution Unit",
  "description": "24V DC power distribution system for the vehicle platform",
  "has_blueprints": false,
  "created_by": "engineer@example.com",
  "created_at": "2026-04-13T10:00:00.000000",
  "is_deleted": false
}
```

***

## List systems

`GET /systems`

**Query parameters:**

| Parameter    | Required | Type    | Description                                                        |
| ------------ | -------- | ------- | ------------------------------------------------------------------ |
| `search`     | No       | string  | Filter by name (case-insensitive substring match)                  |
| `is_deleted` | No       | boolean | Set to `true` to include soft-deleted systems. Defaults to `false` |

**Example request:**

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

Returns `{"items": [...], "count": N}` where each item is a system object with the same fields as the [create response](#create-a-system).

***

## Get a system

`GET /systems/{system_id}`

**Path parameters:**

| Parameter   | Required | Type | Description       |
| ----------- | -------- | ---- | ----------------- |
| `system_id` | Yes      | UUID | System identifier |

**Example request:**

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

Returns a single system object with the same fields as the [create response](#create-a-system).

***

## Update a system

`PUT /systems/{system_id}`

All fields are optional. Only provided fields are updated.

| Field         | Type   | Description      |
| ------------- | ------ | ---------------- |
| `system_name` | string | New display name |
| `description` | string | New description  |

**Example request:**

```bash theme={null}
curl -X PUT "https://nokia.atlas.arenaphysica.com/api/v1/systems/$SYSTEM_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated: 48V system after board revision 3"}'
```

Returns the updated system object with the same fields as the [create response](#create-a-system).

***

## Delete a system

`DELETE /systems/{system_id}`

Soft-deletes a system. The system remains in the database with `is_deleted: true`.

**Example request:**

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

**Response fields:**

| Field     | Type   | Description              |
| --------- | ------ | ------------------------ |
| `message` | string | Confirmation message     |
| `uuid`    | UUID   | ID of the deleted system |

**Example response:**

```json theme={null}
{
  "message": "System deleted successfully",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

***

## Upload a reference document

`POST /systems/upload_document`

Attaches PDFs, specs, schematics, or other documents to a system. Uploaded files are embedded and made available to Atlas during reasoning and metagraph updates.

**Query parameters:**

| Parameter   | Required | Type | Description                     |
| ----------- | -------- | ---- | ------------------------------- |
| `system_id` | No       | UUID | System to scope the document to |

**Form fields (`multipart/form-data`):**

| Field      | Required | Description                                                             |
| ---------- | -------- | ----------------------------------------------------------------------- |
| `file`     | Yes      | File binary. Use multiple `file` fields to upload several files at once |
| `metadata` | No       | JSON string with optional `file_name` (string) and `file_type` (string) |

**Example request:**

```bash theme={null}
curl -X POST "https://nokia.atlas.arenaphysica.com/api/v1/systems/upload_document?system_id=$SYSTEM_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN" \
  -F "file=@system_spec.pdf" \
  -F 'metadata={"file_name": "system_spec.pdf", "file_type": "pdf"}'
```

**Response fields:**

| Field         | Type    | Description                            |
| ------------- | ------- | -------------------------------------- |
| `message`     | string  | Summary message                        |
| `system_id`   | UUID    | System the documents were attached to  |
| `total_files` | integer | Number of files submitted              |
| `successful`  | integer | Number of files successfully processed |
| `failed`      | integer | Number of files that failed            |
| `results`     | array   | Per-file result objects                |

Each item in `results`:

| Field          | Type    | Nullable | Description                  |
| -------------- | ------- | -------- | ---------------------------- |
| `file_name`    | string  | No       | Name of the file             |
| `success`      | boolean | No       | Whether processing succeeded |
| `dataset_name` | string  | Yes      | Dataset identifier assigned  |
| `job_run_id`   | UUID    | Yes      | ID of the embedding job run  |
| `error`        | string  | Yes      | Error message if failed      |

**Example response:**

```json theme={null}
{
  "message": "Processed 1 file(s)",
  "system_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "total_files": 1,
  "successful": 1,
  "failed": 0,
  "results": [
    {
      "file_name": "system_spec.pdf",
      "success": true,
      "dataset_name": "pdu-system-spec",
      "job_run_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "error": null
    }
  ]
}
```

***

## Search system memories

`GET /system-memories`

Searches entity memories across all entities. Returns matching memory entries with their associated entity and system context.

**Query parameters:**

| Parameter         | Required | Type            | Description                                     |
| ----------------- | -------- | --------------- | ----------------------------------------------- |
| `search`          | No       | string          | Keyword search across memory content            |
| `entity_ids`      | No       | array of UUID   | Filter to specific entity IDs                   |
| `root_entity_ids` | No       | array of UUID   | Filter to entities under specific root entities |
| `contributors`    | No       | array of string | Filter by contributor email                     |
| `sort_by`         | No       | string          | Sort field                                      |
| `offset`          | No       | integer         | Default `0`                                     |
| `limit`           | No       | integer         | Default `20`                                    |

**Example request:**

```bash theme={null}
curl "https://nokia.atlas.arenaphysica.com/api/v1/system-memories?search=temperature" \
  -H "Authorization: Bearer $ATLAS_TOKEN"
```

**Response fields:**

| Field   | Type    | Description                      |
| ------- | ------- | -------------------------------- |
| `items` | array   | List of memory result objects    |
| `count` | integer | Total number of matching entries |

Each item in `items`:

| Field               | Type            | Description                                 |
| ------------------- | --------------- | ------------------------------------------- |
| `item.id`           | string          | Memory entry identifier                     |
| `item.content`      | string          | Memory text                                 |
| `item.source`       | string          | How the memory was created                  |
| `item.contributors` | array of string | Emails of users who contributed             |
| `item.created_at`   | string          | ISO 8601 creation timestamp                 |
| `item.tags`         | array of string | Labels applied to this memory               |
| `system_id`         | string          | ID of the system the entity belongs to      |
| `system_name`       | string          | Name of the system                          |
| `entity_id`         | string          | ID of the entity this memory is attached to |
| `entity_name`       | string          | Display name of the entity                  |
| `entity_type`       | string          | Entity type (e.g. `COMPONENT`, `SUBSYSTEM`) |

**Example response:**

```json theme={null}
{
  "items": [
    {
      "item": {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "content": "Known temperature sensitivity above 85°C. Readings drift ~0.5 deg/s per degree above threshold.",
        "source": "user",
        "contributors": ["engineer@example.com"],
        "created_at": "2026-04-13T09:00:00.000000",
        "tags": []
      },
      "system_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "system_name": "Power Distribution Unit",
      "entity_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "entity_name": "Battery Management IC",
      "entity_type": "COMPONENT"
    }
  ],
  "count": 1
}
```