System

All the objects in SIM can be related to the system breakdown structure. SIM supports multi-level system breakdown structures stored as a tree. The system breakdown structure is not the same as the work breakdown structure.

System Object

Field	Type	Description
id	snowflake	the system's ID
organisation_id	snowflake	the ID of the organisation the system belongs to
number	integer	the system's number
formatted_number	string	the system's formatted number
code	string	the system's code (max 12 characters)
name	string	the system's name (max 60 characters)
description	string	the system's description
root_prefix	string	the root system's prefix
root_id	?snowflake	the root system's ID
root	system object	the root system
parent_id	?snowflake	the parent system's ID
parent	system object	the parent system
unused	boolean	whether the system is unused (soft delete flag)

Get System

GET /systems/{system.id}

Returns the system object for the given system id. Requires membership in the organisation that owns the system.

Error Responses

Status Code	Description
400	The system was not found
403	The user is not a member of the organisation

Get SubSystems

GET /systems/{system.id}/subsystems

Returns an array of system objects that are subsystems of the given root system id. Requires membership in the organisation that owns the root system.

Error Responses

Status Code	Description
400	The root system was not found
403	The user is not a member of the organisation

List Systems

GET /organisations/{organisation.id}/systems

Returns an array of system objects for the organisation. Requires membership in the organisation, or an accepted fleet share from the organisation.

Parameters

Field	Type	Description	Default
root	?boolean	when set to true, only root systems will be returned	true
unused	?boolean	when set to true, unused systems will be included in the response	false

Create System

POST /organisations/{organisation.id}/systems

Creates a new system in the organisation. Requires the MANAGE_SYSTEMS permission.

All parameters for this method are optional.

Parameters

Field	Type	Description	Default
parent_id	?snowflake	the parent system's ID; if provided, the new system becomes a subsystem	null
root_prefix	string	the root system's prefix (only used if no parent is specified)
name	string	the system's name (max 60 characters)	new system
code	string	the system's code (max 12 characters)
description	string	the system's description	new system description

Notes

• If parent_id is provided, the parent system must belong to the same organisation.
• If a parent is specified, the new system inherits the parent's root_id and root_prefix.
• The system number is automatically assigned atomically.

Error Responses

Status Code	Description
400	The organisation was not found
400	The parent system does not belong to the organisation
403	The user lacks the MANAGE_SYSTEMS permission

Update System

PATCH /systems/{system.id}

Updates a system. Requires the MANAGE_SYSTEMS permission for the organisation.

All parameters for this method are optional. Only the fields provided will be updated.

Parameters

Field	Type	Description
name	string	the system's name (max 60 characters)
code	string	the system's code (max 12 characters)
description	string	the system's description
unused	boolean	whether the system is unused (soft delete flag)
root_prefix	string	the root system's prefix (only applied if system has no parent)

Notes

• If the system has no parent (root_id is null), setting root_prefix will also update the RootPrefix for all systems sharing the same RootId and OrganisationId.
• Re-ordering systems is not currently supported.

Error Responses

Status Code	Description
400	The system was not found
403	The user lacks the MANAGE_SYSTEMS permission

Delete System

Cannot delete systems, use Update setting unused to true instead.