Configurations - Scala Computing

Workload configuration management

Endpoints

Method	Path	Description
GET	`/api/v1/configurations`	List configurations
POST	`/api/v1/configurations`	Create configuration
GET	`/api/v1/configurations/{config_id}`	Get configuration
PATCH	`/api/v1/configurations/{config_id}`	Update configuration
DELETE	`/api/v1/configurations/{config_id}`	Delete configuration
GET	`/api/v1/configurations/{config_id}/applications`	List configuration applications
POST	`/api/v1/configurations/{config_id}/applications`	Add application to configuration
DELETE	`/api/v1/configurations/{config_id}/applications/{app_name}`	Remove application from configuration
PATCH	`/api/v1/configurations/{config_id}/applications/{app_name}/parameters`	Update application parameters
GET	`/api/v1/configurations/{config_id}/components`	List configuration components
POST	`/api/v1/configurations/{config_id}/components`	Add component to configuration
DELETE	`/api/v1/configurations/{config_id}/components/{component_name}`	Remove component from configuration
PATCH	`/api/v1/configurations/{config_id}/components/{component_name}/parameters`	Update component parameters
PATCH	`/api/v1/configurations/{config_id}/configurations/{component_name}`	Add child to component
PATCH	`/api/v1/configurations/{config_id}/configurations/{component_name}/components/{child_name}`	Update child in component
DELETE	`/api/v1/configurations/{config_id}/configurations/{component_name}/components/{child_name}`	Remove child from component
GET	`/api/v1/configurations/{config_id}/containers`	List configuration containers
PATCH	`/api/v1/configurations/{config_id}/containers/{container_name}`	Add component to container
GET	`/api/v1/configurations/{config_id}/containers/{container_name}/allowed`	Get allowed component types for container
PATCH	`/api/v1/configurations/{config_id}/containers/{container_name}/components/{component_name}`	Update component in container
DELETE	`/api/v1/configurations/{config_id}/containers/{container_name}/components/{component_name}`	Remove component from container
PATCH	`/api/v1/configurations/{config_id}/distribution`	Update distribution entry value
GET	`/api/v1/configurations/{config_id}/links`	List configuration links
PATCH	`/api/v1/configurations/{config_id}/links/{link_name}/parameters`	Update link parameters
PATCH	`/api/v1/configurations/{config_id}/parameters`	Update global parameters
GET	`/api/v1/configurations/{config_id}/software-version`	Get software version
PATCH	`/api/v1/configurations/{config_id}/topology`	Add component to topology
PATCH	`/api/v1/configurations/{config_id}/topology/{component_name}`	Update topology component
DELETE	`/api/v1/configurations/{config_id}/topology/{component_name}`	Remove component from topology
GET	`/api/v1/configurations/{config_id}/traceset`	List available tracesets for configuration
PATCH	`/api/v1/configurations/{config_id}/traceset`	Attach traceset to configuration
POST	`/api/v1/configurations/{config_id}/validate`	Validate configuration
GET	`/api/v1/configurations/{config_id}/versions`	List configuration versions
GET	`/api/v1/configurations/{config_id}/versions/{version}`	Get specific configuration version

List configurations

GET /api/v1/configurations

Parameters

Name	In	Type	Required	Description
`limit`	query	integer	No	-
`next`	query	string	No	Opaque cursor token to fetch results after a specific item
`workspaceId`	query	string	No	-
`status`	query	string (enum)	No	Filter by configuration status (comma-separated for multiple)
`search`	query	string	No	Full-text search across name and description fields (case-insensitive)
`createdAfter`	query	string	No	Filter to items created on or after this timestamp (ISO 8601)
`createdBefore`	query	string	No	Filter to items created before this timestamp (ISO 8601)

Responses

200 - List of configurations

{
  "configurations": [
    {
      "componentCount": 1,
      "createdAt": "2024-01-15T10:30:00Z",
      "id": "string",
      "modifiedAt": "2024-01-15T10:30:00Z",
      "name": "string",
      "status": "...",
      "version": 1,
      "workspaceId": "string"
    }
  ],
  "pagination": {
    "count": 1,
    "hasMore": true,
    "nextCursor": "string"
  }
}

Create configuration

POST /api/v1/configurations

Request Body

Field	Type	Required	Description
`activeTraceset`	any	No	Active traceset for chakra-based simulations. Required when any application has trafficType ‘chakra’.
`applications`	array[ApplicationDefinition]	Yes	Traffic generator and workload applications
`components`	array[ComponentDeclaration]	Yes	Component declarations
`containers`	array[ContainerDefinition]	Yes	Container definitions
`globalParameters`	TypedParameters	Yes	Hierarchical parameters structure. Leaf nodes are ParameterValue objects, branch nodes are nested TypedParameters representing ModelComponents.
`links`	array[ComponentDeclaration]	Yes	Layer components defining spine plane linking configuration (type=‘layer’)
`name`	string	Yes	Configuration name
`topology`	TopologyDefinition	Yes	Active network topology definition
`workspaceId`	string	No	Workspace identifier. If omitted, defaults to the well-known default workspace.

{
  "activeTraceset": {},
  "applications": [
    {
      "model": "ChakraWorkload",
      "name": "ScalaChakraGenerator",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "4.0.1"
    }
  ],
  "components": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "3.2.1"
    }
  ],
  "containers": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "configuration": null,
      "model": "ScalaRack",
      "name": "roce-rack",
      "type": "...",
      "version": "4.0.0"
    }
  ],
  "globalParameters": {},
  "links": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "3.2.1"
    }
  ],
  "name": "string",
  "topology": {
    "allowedComponents": [
      "string"
    ],
    "appDistribution": {
      "description": "...",
      "randomApplicationDistribution": "..."
    },
    "components": [
      "..."
    ],
    "name": null,
    "topologyTiers": 1,
    "type": "clos"
  },
  "workspaceId": "string"
}

Responses

201 - Configuration created

{
  "activeTraceset": {},
  "applications": [
    {
      "model": "ChakraWorkload",
      "name": "ScalaChakraGenerator",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "4.0.1"
    }
  ],
  "componentCount": 1,
  "components": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "3.2.1"
    }
  ],
  "containers": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "configuration": null,
      "model": "ScalaRack",
      "name": "roce-rack",
      "type": "...",
      "version": "4.0.0"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "globalParameters": {},
  "id": "config_10045",
  "links": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "3.2.1"
    }
  ],
  "modifiedAt": "2024-01-15T10:30:00Z",
  "name": "string",
  "status": "draft",
  "topology": {
    "allowedComponents": [
      "string"
    ],
    "appDistribution": {
      "description": "...",
      "randomApplicationDistribution": "..."
    },
    "components": [
      "..."
    ],
    "name": null,
    "topologyTiers": 1,
    "type": "clos"
  },
  "version": 1,
  "workspaceId": "string"
}

Get configuration

GET /api/v1/configurations/{config_id}

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-

Responses

200 - Configuration details

{
  "activeTraceset": {},
  "applications": [
    {
      "model": "ChakraWorkload",
      "name": "ScalaChakraGenerator",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "4.0.1"
    }
  ],
  "componentCount": 1,
  "components": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "3.2.1"
    }
  ],
  "containers": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "configuration": null,
      "model": "ScalaRack",
      "name": "roce-rack",
      "type": "...",
      "version": "4.0.0"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "globalParameters": {},
  "id": "config_10045",
  "links": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "3.2.1"
    }
  ],
  "modifiedAt": "2024-01-15T10:30:00Z",
  "name": "string",
  "status": "draft",
  "topology": {
    "allowedComponents": [
      "string"
    ],
    "appDistribution": {
      "description": "...",
      "randomApplicationDistribution": "..."
    },
    "components": [
      "..."
    ],
    "name": null,
    "topologyTiers": 1,
    "type": "clos"
  },
  "version": 1,
  "workspaceId": "string"
}

Update configuration

PATCH /api/v1/configurations/{config_id}

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`If-Match`	header	string	Yes	ETag for optimistic concurrency

Request Body

Field	Type	Required	Description
`activeTraceset`	any	No	Active traceset for chakra-based simulations. Required when any application has trafficType ‘chakra’.
`applications`	array[ApplicationDefinition]	No	Traffic generator and workload applications
`components`	array[ComponentDeclaration]	No	Component declarations
`containers`	array[ContainerDefinition]	No	Container definitions
`globalParameters`	TypedParameters	No	Hierarchical parameters structure. Leaf nodes are ParameterValue objects, branch nodes are nested TypedParameters representing ModelComponents.
`links`	array[ComponentDeclaration]	No	Layer components defining spine plane linking configuration (type=‘layer’)
`name`	[‘string’, ‘null’]	No	Configuration name
`topology`	TopologyDefinition	No	Active network topology definition

{
  "activeTraceset": {},
  "applications": [
    {
      "model": "ChakraWorkload",
      "name": "ScalaChakraGenerator",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "4.0.1"
    }
  ],
  "components": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "3.2.1"
    }
  ],
  "containers": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "configuration": null,
      "model": "ScalaRack",
      "name": "roce-rack",
      "type": "...",
      "version": "4.0.0"
    }
  ],
  "globalParameters": {},
  "links": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "3.2.1"
    }
  ],
  "name": null,
  "topology": {
    "allowedComponents": [
      "string"
    ],
    "appDistribution": {
      "description": "...",
      "randomApplicationDistribution": "..."
    },
    "components": [
      "..."
    ],
    "name": null,
    "topologyTiers": 1,
    "type": "clos"
  }
}

Responses

200 - Configuration updated

{
  "activeTraceset": {},
  "applications": [
    {
      "model": "ChakraWorkload",
      "name": "ScalaChakraGenerator",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "4.0.1"
    }
  ],
  "componentCount": 1,
  "components": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "3.2.1"
    }
  ],
  "containers": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "configuration": null,
      "model": "ScalaRack",
      "name": "roce-rack",
      "type": "...",
      "version": "4.0.0"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "globalParameters": {},
  "id": "config_10045",
  "links": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "3.2.1"
    }
  ],
  "modifiedAt": "2024-01-15T10:30:00Z",
  "name": "string",
  "status": "draft",
  "topology": {
    "allowedComponents": [
      "string"
    ],
    "appDistribution": {
      "description": "...",
      "randomApplicationDistribution": "..."
    },
    "components": [
      "..."
    ],
    "name": null,
    "topologyTiers": 1,
    "type": "clos"
  },
  "version": 1,
  "workspaceId": "string"
}

412 - Precondition failed (ETag mismatch)

Delete configuration

DELETE /api/v1/configurations/{config_id}

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-

Responses

204 - Configuration deleted

List configuration applications

GET /api/v1/configurations/{config_id}/applications Returns all applications in the configuration’s topology

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`withDetails`	query	boolean	No	When true, includes full typedParameters for each application. Defaults to false.

Responses

200 - List of applications

{
  "applications": [
    {
      "model": "ChakraWorkload",
      "name": "ScalaChakraGenerator",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "4.0.1"
    }
  ]
}

404 - Configuration not found

Add application to configuration

POST /api/v1/configurations/{config_id}/applications Adds an application to the configuration’s topology by looking up the model from the database. Server resolves traffic type, version, and default parameters from the model.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`modelId`	query	string	Yes	Application model identifier — KSUID (model_xxx) or model name (e.g., ScalaChakraGenerator). Server resolves traffic type, version, and default parameters.
`name`	query	string	Yes	Unique name for this application in the configuration
`version`	query	string	No	Optional model version. If omitted, uses latest stable version.

Responses

201 - Application added

{
  "model": "ChakraWorkload",
  "name": "ScalaChakraGenerator",
  "trafficType": "chakra",
  "type": "switch",
  "typedParameters": {},
  "version": "4.0.1"
}

400 - Invalid request (distribution sum exceeds 1.0) 404 - Configuration not found

Remove application from configuration

DELETE /api/v1/configurations/{config_id}/applications/{app_name} Removes an application from the configuration’s topology. Remaining applications are auto-scaled to maintain distribution sum of 1.0.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`app_name`	path	string	Yes	-

Responses

200 - Application removed successfully

{
  "id": "string",
  "message": "string",
  "status": "string"
}

404 - Configuration or application not found

Update application parameters

PATCH /api/v1/configurations/{config_id}/applications/{app_name}/parameters Performs a validated merge of the provided TypedParameters patch into the named application’s typed_parameters. Only existing parameter keys can be updated, and types must match.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`app_name`	path	string	Yes	-
`If-Match`	header	string	No	ETag for optimistic concurrency control

Request Body

Responses

200 - Parameters updated successfully. Returns the full updated TypedParameters for the application. 400 - Invalid request (empty patch, unknown parameter key, type mismatch, structural mismatch) 404 - Configuration or application not found 409 - Conflict (serialization failure from concurrent modification) 412 - Precondition failed (ETag mismatch) 409 - Traceset rank count not yet resolved — metadata extraction is still in progress. Retry after extraction completes. 422 - Traceset rank count is present but invalid (zero or negative). The traceset data is malformed and cannot be used for a Chakra simulation.

List configuration components

GET /api/v1/configurations/{config_id}/components Returns all components from the configuration’s components array with optional type filtering

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`type`	query	string	No	Filter by component type (switch, nic, server, host)
`limit`	query	integer	No	-
`next`	query	string	No	Opaque cursor token for pagination
`withDetails`	query	boolean	No	When true, includes full typedParameters for each component. Defaults to false.

Responses

200 - List of components

{
  "components": [
    {
      "container": null,
      "model": "ScalaSwitch",
      "name": "string",
      "type": "...",
      "typedParameters": "...",
      "version": "3.2.1"
    }
  ],
  "pagination": {
    "count": 1,
    "hasMore": true,
    "nextCursor": "string"
  }
}

404 - Configuration not found

Add component to configuration

POST /api/v1/configurations/{config_id}/components Adds a component, container, or layer to the configuration by looking up the model from the database. For switch/nic/server: adds to components array. For rack/pod: adds to containers array. For layer: adds to links array.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`modelId`	query	string	Yes	Model identifier — KSUID (model_xxx) or model name (e.g., ScalaSwitch). Server resolves version and default parameters.
`type`	query	string	Yes	Component type: switch, nic, server, rack, pod, or layer
`name`	query	string	Yes	Unique name for this component in the configuration
`version`	query	string	No	Optional model version. If omitted, uses latest stable version.

Responses

201 - Component added

{
  "allowedComponents": [
    "string"
  ],
  "components": [
    {
      "count": 4,
      "group": null,
      "model": "ScalaSwitch",
      "name": "spine-1",
      "parentApplicationName": null,
      "type": "switch",
      "version": "3.2.1"
    }
  ],
  "model": "ScalaSwitch",
  "name": "spine-switch-1",
  "trafficType": "chakra",
  "type": "switch",
  "typedParameters": {},
  "version": "3.2.1"
}

400 - Invalid request (model not found, invalid parameters) 404 - Configuration not found

Remove component from configuration

DELETE /api/v1/configurations/{config_id}/components/{component_name} Removes a component from the configuration’s components array. Cascades removal to all container references, topology references, and child references in other components.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`component_name`	path	string	Yes	-
`If-Match`	header	string	No	ETag for optimistic concurrency control

Responses

204 - Component removed from configuration 404 - Configuration or component not found 412 - Precondition failed (ETag mismatch)

Update component parameters

PATCH /api/v1/configurations/{config_id}/components/{component_name}/parameters Performs a validated merge of the provided TypedParameters patch into the named component’s typed_parameters. Only existing parameter keys can be updated, and types must match.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`component_name`	path	string	Yes	-
`If-Match`	header	string	No	ETag for optimistic concurrency control

Request Body

Responses

200 - Parameters updated successfully. Returns the full updated TypedParameters for the component. 400 - Invalid request (empty patch, unknown parameter key, type mismatch, structural mismatch) 404 - Configuration or component not found 409 - Conflict (serialization failure from concurrent modification) 412 - Precondition failed (ETag mismatch)

Add child to component

PATCH /api/v1/configurations/{config_id}/configurations/{component_name} Adds a child component (NIC, GPU, or application) to the specified host (server) component. Validates that the child type is in the host’s allowedComponents list.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`component_name`	path	string	Yes	-
`If-Match`	header	string	No	ETag for optimistic concurrency control

Request Body

Field	Type	Required	Description
`count`	integer	No	Number of instances (default 1)
`group`	string	No	Logical group for relating components
`name`	string	Yes	Name of an existing NIC, GPU, or application component in the configuration
`parentApplicationName`	string	No	Parent application name (required for application type children)
`type`	string	Yes	Child component type (nic, gpu, application)

{
  "count": 1,
  "group": "string",
  "name": "string",
  "parentApplicationName": "string",
  "type": "nic"
}

Responses

200 - Child component added to host

{
  "allowedComponents": [
    "string"
  ],
  "components": [
    {
      "count": 4,
      "group": null,
      "model": "ScalaSwitch",
      "name": "spine-1",
      "parentApplicationName": null,
      "type": "switch",
      "version": "3.2.1"
    }
  ],
  "model": "ScalaSwitch",
  "name": "spine-switch-1",
  "trafficType": "chakra",
  "type": "switch",
  "typedParameters": {},
  "version": "3.2.1"
}

400 - Invalid request (child type not allowed, already attached) 404 - Configuration or component not found

Update child in component

PATCH /api/v1/configurations/{config_id}/configurations/{component_name}/components/{child_name} Updates count and/or group on an existing child component reference within the specified host (server) component. At least one of count or group must be provided.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`component_name`	path	string	Yes	-
`child_name`	path	string	Yes	-
`If-Match`	header	string	No	ETag for optimistic concurrency control

Request Body

Field	Type	Required	Description
`count`	integer	No	Updated instance count
`group`	string	No	Updated logical group assignment

{
  "count": 1,
  "group": "string"
}

Responses

200 - Child component updated

{
  "allowedComponents": [
    "string"
  ],
  "components": [
    {
      "count": 4,
      "group": null,
      "model": "ScalaSwitch",
      "name": "spine-1",
      "parentApplicationName": null,
      "type": "switch",
      "version": "3.2.1"
    }
  ],
  "model": "ScalaSwitch",
  "name": "spine-switch-1",
  "trafficType": "chakra",
  "type": "switch",
  "typedParameters": {},
  "version": "3.2.1"
}

400 - Invalid request (empty patch, count < 1) 404 - Configuration, component, or child not found 412 - Precondition failed (ETag mismatch)

Remove child from component

DELETE /api/v1/configurations/{config_id}/configurations/{component_name}/components/{child_name} Removes a child component (NIC, GPU, or application) from the specified host (server) component.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`component_name`	path	string	Yes	-
`child_name`	path	string	Yes	-
`If-Match`	header	string	No	ETag for optimistic concurrency control

Responses

204 - Child component removed from host 404 - Configuration, component, or child not found 412 - Precondition failed (ETag mismatch)

List configuration containers

GET /api/v1/configurations/{config_id}/containers Returns all containers from the configuration with optional type filtering

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`type`	query	string	No	Filter by container type (rack, pod)
`limit`	query	integer	No	-
`next`	query	string	No	Opaque cursor token for pagination

Responses

200 - List of containers

{
  "containers": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "configuration": null,
      "model": "ScalaRack",
      "name": "roce-rack",
      "type": "...",
      "version": "4.0.0"
    }
  ],
  "pagination": {
    "count": 1,
    "hasMore": true,
    "nextCursor": "string"
  }
}

404 - Configuration not found

Add component to container

PATCH /api/v1/configurations/{config_id}/containers/{container_name} Adds a component reference to the specified container. Validates that the component type is in the container’s allowed list.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`container_name`	path	string	Yes	-

Request Body

Field	Type	Required	Description
`count`	integer	No	Number of instances (default 1)
`group`	string	No	Logical group for relating components
`name`	string	Yes	Name of an existing component or container in the configuration to add to this container
`type`	string	Yes	Component type (switch, nic, server, rack, pod)

{
  "count": 1,
  "group": "string",
  "name": "my-spine-switch",
  "type": "switch"
}

Responses

200 - Component added to container

{
  "allowedComponents": [
    "string"
  ],
  "components": [
    {
      "count": 4,
      "group": null,
      "model": "ScalaSwitch",
      "name": "spine-1",
      "parentApplicationName": null,
      "type": "switch",
      "version": "3.2.1"
    }
  ],
  "configuration": null,
  "model": "ScalaRack",
  "name": "roce-rack",
  "type": "rack",
  "version": "4.0.0"
}

400 - Component type not allowed in container 404 - Configuration or container not found

Get allowed component types for container

GET /api/v1/configurations/{config_id}/containers/{container_name}/allowed Returns the list of component types allowed in this container based on its type

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`container_name`	path	string	Yes	-

Responses

200 - Allowed component types

{
  "allowedComponents": [
    "switch",
    "nic",
    "server",
    "application",
    "layer"
  ],
  "containerName": "string",
  "containerType": "rack"
}

404 - Configuration or container not found

Update component in container

PATCH /api/v1/configurations/{config_id}/containers/{container_name}/components/{component_name} Updates count and/or group on an existing component reference in the specified container. At least one of count or group must be provided.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`container_name`	path	string	Yes	-
`component_name`	path	string	Yes	-
`If-Match`	header	string	No	ETag for optimistic concurrency control

Request Body

Field	Type	Required	Description
`count`	integer	No	Updated instance count
`group`	string	No	Updated logical group assignment

{
  "count": 1,
  "group": "string"
}

Responses

200 - Component updated in container

{
  "allowedComponents": [
    "string"
  ],
  "components": [
    {
      "count": 4,
      "group": null,
      "model": "ScalaSwitch",
      "name": "spine-1",
      "parentApplicationName": null,
      "type": "switch",
      "version": "3.2.1"
    }
  ],
  "configuration": null,
  "model": "ScalaRack",
  "name": "roce-rack",
  "type": "rack",
  "version": "4.0.0"
}

400 - Invalid request (empty patch, count < 1) 404 - Configuration, container, or component not found 412 - Precondition failed (ETag mismatch)

Remove component from container

DELETE /api/v1/configurations/{config_id}/containers/{container_name}/components/{component_name} Removes a component reference from the specified container

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`container_name`	path	string	Yes	-
`component_name`	path	string	Yes	-

Responses

204 - Component removed from container 404 - Configuration, container, or component not found

Update distribution entry value

PATCH /api/v1/configurations/{config_id}/distribution Updates the value field of a specific entry in topology.appDistribution.randomApplicationDistribution[]. The entry is identified by parentApplication + distributionId.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`If-Match`	header	string	No	ETag for optimistic concurrency control

Request Body

Field	Type	Required	Description
`distributionId`	string	Yes	Distribution identifier linking to prClientVariable (e.g., prScalaTrafficServer)
`parentApplication`	string	Yes	Root application name (e.g., ScalaTrafficGeneratorApp)
`value`	number	Yes	New distribution percentage value (0.0 to 1.0 inclusive)

{
  "distributionId": "string",
  "parentApplication": "string",
  "value": 1.0
}

Responses

200 - Distribution value updated

{
  "description": null,
  "randomApplicationDistribution": [
    {
      "applicationType": "client",
      "distributionPercent": "...",
      "name": "string",
      "parentApplication": "string"
    }
  ]
}

400 - Invalid request (value out of range, empty fields, no app_distribution) 404 - Configuration or distribution entry not found 409 - Concurrent modification conflict, please retry 412 - Precondition failed (ETag mismatch)

List configuration links

GET /api/v1/configurations/{config_id}/links Returns all links (layer components) from the configuration

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`withDetails`	query	boolean	No	When true, includes full typedParameters for each link. Defaults to false.

Responses

200 - List of links

{
  "links": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "3.2.1"
    }
  ]
}

404 - Configuration not found

Update link parameters

PATCH /api/v1/configurations/{config_id}/links/{link_name}/parameters Performs a validated merge of the provided TypedParameters patch into the named link’s typed_parameters. Only existing parameter keys can be updated, and types must match.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`link_name`	path	string	Yes	-
`If-Match`	header	string	No	ETag for optimistic concurrency control

Request Body

Responses

200 - Parameters updated successfully. Returns the full updated TypedParameters for the link. 400 - Invalid request (empty patch, unknown parameter key, type mismatch, structural mismatch) 404 - Configuration or link not found 409 - Conflict (serialization failure from concurrent modification) 412 - Precondition failed (ETag mismatch)

Update global parameters

PATCH /api/v1/configurations/{config_id}/parameters Performs a validated merge of the provided TypedParameters patch into the configuration’s global_parameters. Backend-managed sections (ComputeConfiguration, ParallelizationParameters, etc.), readonly sections (SoftwareVersion), and hidden parameters are rejected with 400.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`If-Match`	header	string	No	ETag for optimistic concurrency control

Request Body

Responses

200 - Parameters updated successfully. Returns the full updated global TypedParameters (with backend params stripped). 400 - Invalid request (empty patch, unknown parameter key, type mismatch, structural mismatch, attempt to modify backend-managed/readonly/hidden params) 404 - Configuration not found 409 - Conflict (serialization failure from concurrent modification) 412 - Precondition failed (ETag mismatch)

Get software version

GET /api/v1/configurations/{config_id}/software-version Returns the simulator software version from the SoftwareVersion section of globalParameters.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-

Responses

200 - Software version retrieved successfully

{
  "version": "string"
}

404 - Configuration not found

Add component to topology

PATCH /api/v1/configurations/{config_id}/topology Adds a component reference to the configuration’s topology.components array. Validates the named entity exists in the correct collection by type (switch→components, layer→links, pod→containers).

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`If-Match`	header	string	No	ETag for optimistic concurrency control

Request Body

Field	Type	Required	Description
`count`	integer	No	Number of instances (default 1)
`name`	string	Yes	Name of existing component, container, or link to reference
`type`	string	Yes	Type of the referenced entity

{
  "count": 1,
  "name": "my-spine-switch",
  "type": "switch"
}

Responses

200 - Component added to topology

{
  "allowedComponents": [
    "string"
  ],
  "appDistribution": {
    "description": null,
    "randomApplicationDistribution": [
      "..."
    ]
  },
  "components": [
    {
      "count": 4,
      "group": null,
      "model": "ScalaSwitch",
      "name": "spine-1",
      "parentApplicationName": null,
      "type": "switch",
      "version": "3.2.1"
    }
  ],
  "name": null,
  "topologyTiers": 1,
  "type": "clos"
}

400 - Invalid request (type not allowed, duplicate, invalid type) 404 - Configuration or referenced entity not found

Update topology component

PATCH /api/v1/configurations/{config_id}/topology/{component_name} Updates the count on an existing component reference in the topology.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`component_name`	path	string	Yes	-
`If-Match`	header	string	No	ETag for optimistic concurrency control

Request Body

Field	Type	Required	Description
`count`	integer	Yes	Updated instance count

{
  "count": 1
}

Responses

200 - Topology component updated

{
  "allowedComponents": [
    "string"
  ],
  "appDistribution": {
    "description": null,
    "randomApplicationDistribution": [
      "..."
    ]
  },
  "components": [
    {
      "count": 4,
      "group": null,
      "model": "ScalaSwitch",
      "name": "spine-1",
      "parentApplicationName": null,
      "type": "switch",
      "version": "3.2.1"
    }
  ],
  "name": null,
  "topologyTiers": 1,
  "type": "clos"
}

400 - Invalid request (count < 1) 404 - Configuration or component not found in topology 412 - Precondition failed (ETag mismatch)

Remove component from topology

DELETE /api/v1/configurations/{config_id}/topology/{component_name} Removes a component reference from the configuration’s topology.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`component_name`	path	string	Yes	-
`If-Match`	header	string	No	ETag for optimistic concurrency control

Responses

204 - Component removed from topology 404 - Configuration or component not found in topology 412 - Precondition failed (ETag mismatch)

List available tracesets for configuration

GET /api/v1/configurations/{config_id}/traceset Returns tracesets that can be attached to configuration applications. Use scope=global to list all tracesets across all workspaces, or scope=workspace to filter by the configuration’s workspace only.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`status`	query	string	No	Filter by traceset status (completed, uploading, failed)
`limit`	query	integer	No	-
`next`	query	string	No	Opaque cursor token for pagination
`scope`	query	string (enum)	No	Scope filter for tracesets. ‘global’ returns all tracesets across all workspaces (default). ‘workspace’ returns only tracesets in the configuration’s workspace.

Responses

200 - List of available tracesets

{
  "pagination": {
    "count": 1,
    "hasMore": true,
    "nextCursor": "string"
  },
  "tracesets": [
    {
      "createdAt": "2024-01-15T10:30:00Z",
      "description": null,
      "format": "chakra_json_v1",
      "hash": "crc64nvme:abc123...",
      "hashShort": "abc123def456",
      "id": "ts_2RKHfGD5Z8vW9pL3NqM7TjX1YcB",
      "metadataStatus": "pending",
      "name": "string",
      "status": "uploading",
      "totalSize": 1,
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

404 - Configuration not found

Attach traceset to configuration

PATCH /api/v1/configurations/{config_id}/traceset Sets the activeTraceset field on the configuration to reference the specified traceset. Requires at least one application with trafficType ‘chakra’ to exist in the configuration. Workspace-agnostic: any traceset can be attached regardless of workspace.

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`If-Match`	header	string	No	ETag for optimistic concurrency control

Request Body

Field	Type	Required	Description
`tracesetId`	string	Yes	Traceset ID to attach (workspace-agnostic)

{
  "tracesetId": "ts_2RKHfGD5Z8vW9pL3NqM7TjX1YcB"
}

Responses

200 - Traceset attached successfully

{
  "activeTraceset": {
    "id": "string",
    "name": "string"
  }
}

400 - Invalid request (traceset not found, no Chakra application in configuration) 404 - Configuration not found 409 - Traceset rank count not yet resolved — metadata extraction is still in progress. Retry after extraction completes. 412 - Precondition failed (ETag mismatch) 422 - Traceset rank count is present but invalid (zero or negative). The traceset data is malformed and cannot be used for a Chakra simulation.

Validate configuration

POST /api/v1/configurations/{config_id}/validate

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-

Responses

200 - Validation result

{
  "errors": [
    {
      "code": "CONSTRAINT_VIOLATION",
      "component": null,
      "message": "string",
      "parameter": null,
      "path": "$.components[2].typedParameters.numUpLinks",
      "severity": "..."
    }
  ],
  "info": [
    {
      "code": "CONSTRAINT_VIOLATION",
      "component": null,
      "message": "string",
      "parameter": null,
      "path": "$.components[2].typedParameters.numUpLinks",
      "severity": "..."
    }
  ],
  "status": "valid",
  "valid": true,
  "warnings": [
    {
      "code": "CONSTRAINT_VIOLATION",
      "component": null,
      "message": "string",
      "parameter": null,
      "path": "$.components[2].typedParameters.numUpLinks",
      "severity": "..."
    }
  ]
}

List configuration versions

GET /api/v1/configurations/{config_id}/versions

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-

Responses

200 - List of version summaries

{
  "versions": [
    {
      "createdAt": "2024-01-15T10:30:00Z",
      "version": 1
    }
  ]
}

Get specific configuration version

GET /api/v1/configurations/{config_id}/versions/{version}

Parameters

Name	In	Type	Required	Description
`config_id`	path	string	Yes	-
`version`	path	integer	Yes	-

Responses

200 - Configuration version details

{
  "activeTraceset": {},
  "applications": [
    {
      "model": "ChakraWorkload",
      "name": "ScalaChakraGenerator",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "4.0.1"
    }
  ],
  "components": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "3.2.1"
    }
  ],
  "containers": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "configuration": null,
      "model": "ScalaRack",
      "name": "roce-rack",
      "type": "...",
      "version": "4.0.0"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "globalParameters": {},
  "links": [
    {
      "allowedComponents": [
        "..."
      ],
      "components": [
        "..."
      ],
      "model": "ScalaSwitch",
      "name": "spine-switch-1",
      "trafficType": "...",
      "type": "...",
      "typedParameters": "...",
      "version": "3.2.1"
    }
  ],
  "topology": {
    "allowedComponents": [
      "string"
    ],
    "appDistribution": {
      "description": "...",
      "randomApplicationDistribution": "..."
    },
    "components": [
      "..."
    ],
    "name": null,
    "topologyTiers": 1,
    "type": "clos"
  },
  "version": 1
}

404 - Version not found

​Endpoints

​List configurations

​Parameters

​Responses

​Create configuration

​Request Body

​Responses

​Get configuration

​Parameters

​Responses

​Update configuration

​Parameters

​Request Body

​Responses

​Delete configuration

​Parameters

​Responses

​List configuration applications

​Parameters

​Responses

​Add application to configuration

​Parameters

​Responses

​Remove application from configuration

​Parameters

​Responses

​Update application parameters

​Parameters

​Request Body

​Responses

​List configuration components

​Parameters

​Responses

​Add component to configuration

​Parameters

​Responses

​Remove component from configuration

​Parameters

​Responses

​Update component parameters

​Parameters

​Request Body

​Responses

​Add child to component

​Parameters

​Request Body

​Responses

​Update child in component

​Parameters

​Request Body

​Responses

​Remove child from component

​Parameters

​Responses

​List configuration containers

​Parameters

​Responses

​Add component to container

​Parameters

​Request Body

​Responses

​Get allowed component types for container

​Parameters

​Responses

​Update component in container

​Parameters

​Request Body

​Responses

​Remove component from container

​Parameters

​Responses

​Update distribution entry value

​Parameters

​Request Body

​Responses

​List configuration links

​Parameters

​Responses

​Update link parameters

​Parameters

Endpoints

List configurations

Parameters

Responses

Create configuration

Request Body

Responses

Get configuration

Parameters

Responses

Update configuration

Parameters

Request Body

Responses

Delete configuration

Parameters

Responses

List configuration applications

Parameters

Responses

Add application to configuration

Parameters

Responses

Remove application from configuration

Parameters

Responses

Update application parameters

Parameters

Request Body

Responses

List configuration components

Parameters

Responses

Add component to configuration

Parameters

Responses

Remove component from configuration

Parameters

Responses

Update component parameters

Parameters

Request Body

Responses

Add child to component

Parameters

Request Body

Responses

Update child in component

Parameters

Request Body

Responses

Remove child from component

Parameters

Responses

List configuration containers

Parameters

Responses

Add component to container

Parameters

Request Body

Responses

Get allowed component types for container

Parameters

Responses

Update component in container

Parameters

Request Body

Responses

Remove component from container

Parameters

Responses

Update distribution entry value

Parameters

Request Body

Responses

List configuration links

Parameters

Responses

Update link parameters

Parameters