Systems

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 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:

curl -X POST "$ATLAS_URL/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:

{
  "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:

curl "$ATLAS_URL/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.

Get a system

GET /systems/{system_id} Path parameters:

Parameter	Required	Type	Description
`system_id`	Yes	UUID	System identifier

Example request:

curl "$ATLAS_URL/api/v1/systems/$SYSTEM_ID" \
  -H "Authorization: Bearer $ATLAS_TOKEN"

Returns a single system object with the same fields as the create response.

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:

curl -X PUT "$ATLAS_URL/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.

Delete a system

DELETE /systems/{system_id} Soft-deletes a system. The system remains in the database with is_deleted: true. Example request:

curl -X DELETE "$ATLAS_URL/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:

{
  "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:

curl -X POST "$ATLAS_URL/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:

{
  "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:

curl "$ATLAS_URL/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:

{
  "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
}

Overview

Resources

Endpoints

Create a system

List systems

Get a system

Update a system

Delete a system

Upload a reference document

Search system memories

Overview

Resources

Documentation Index

​Endpoints

​Create a system

​List systems

​Get a system

​Update a system

​Delete a system

​Upload a reference document

​Search system memories

Endpoints

Create a system

List systems

Get a system

Update a system

Delete a system

Upload a reference document

Search system memories