Is your feature request related to a problem? Please describe.
Currently, command execution is exposed through REST APIs only for individual devices. With the introduction of mass command execution, there will be a requirement for an API interface to resolve target devices, trigger batch command execution, or retrieve and manage previously executed mass command operations.
This limits mass command functionality to the admin interface and prevents external systems, automation workflows, and frontend integrations from interacting with the mass command execution pipeline programmatically.
Describe the solution I would implement
I would like to expose the mass command execution workflow through REST APIs, following the same backend execution flow as the admin interface.
-
Confirmation endpoint: A confirmation endpoint to resolve and preview affected devices before creating a MassCommand operation.
POST /api/v1/controller/batch-command/confirmation/
This endpoint will accept target filters such as organization, device group, location, manual device selection, and all devices.
This acts as a dry-run step before triggering the actual batch operation.
-
Mass command execution endpoint: An endpoint to create and execute a new MassCommand.
POST /api/v1/controller/batch-command/
This endpoint will validate the selected target devices, validate the command type, and create the MassCommand operation to create child Command objects that trigger the asynchronous execution pipeline.
Supported command types may include reboot, change password and custom command.
-
Mass command listing endpoint: An endpoint to retrieve all previously executed MassCommand operations.
GET /api/v1/controller/batch-command/
This endpoint will return the list of mass command operations with their execution metadata, aggregated status, targeted devices count, and timestamps, allowing administrators or API consumers to view the history of batch command executions.
-
Mass command detail endpoint: An endpoint to retrieve a specific MassCommand operation and its execution details.
GET /api/v1/controller/batch-command/{pk}/
This endpoint will return detailed information about the selected mass command operation, including operation metadata, targeted devices, per-device execution status, command outputs, and overall execution progress.
-
Mass command deletion endpoint: An endpoint to delete an existing MassCommand operation.
DELETE /api/v1/controller/batch-command/{pk}/
This endpoint will allow authorized users to delete a previously created mass command operation record while preserving proper permission checks and validation.
Details to preserve during implementation
The exact request and response schemas should be defined before implementation or during the first API work. This includes confirmation, creation, list, detail, and delete responses.
Pagination requirements should be explicit. The API should investigate pagination for the MassCommand list and for per-device execution results in MassCommand detail responses.
Per-device execution results should be exposed clearly. The final schema can decide whether results are embedded in the MassCommand detail response, exposed through a nested endpoint, linked to existing Command resources, or handled with another pattern that fits the existing API design.
Lifecycle and status semantics should be aligned with the backend work in #1344. The API should expose enough information to distinguish in-progress, success, failed, partial success, and other final or transitional states chosen during implementation.
Error behavior and validation rules should be defined. Cases to cover include invalid target combinations, unauthorized devices, unsupported command types, empty target sets, invalid manual device IDs, and devices without usable connections.
Permission behavior should be explicit for all devices, organization-scoped users, cross-organization operations, manual device selection, location filters, and device group filters.
Integration with the existing Command API should be clarified. The implementation can decide whether the existing individual Command API exposes the mass_command relation directly, links to the parent operation, or keeps this relation only in MassCommand-specific responses.
Deletion behavior should remain open until lifecycle and traceability requirements are clear. Possible approaches include allowing deletion while preserving child Command rows, blocking deletion while execution is in progress, protecting records that still have child commands, soft-deleting records, or another approach that preserves the expected command history behavior.
Naming should be kept consistent before implementation. The proposal and issues use terms such as MassCommand, Batch Command, BatchCommand, and /batch-command/. Possible API path options include keeping /batch-command/, switching to /mass-command/, or choosing another convention that matches the rest of the project.
Automated tests should cover request/response schemas, pagination, per-device results, validation errors, permissions, lifecycle constraints, deletion behavior, and integration with the existing Command API.
Is your feature request related to a problem? Please describe.
Currently, command execution is exposed through REST APIs only for individual devices. With the introduction of mass command execution, there will be a requirement for an API interface to resolve target devices, trigger batch command execution, or retrieve and manage previously executed mass command operations.
This limits mass command functionality to the admin interface and prevents external systems, automation workflows, and frontend integrations from interacting with the mass command execution pipeline programmatically.
Describe the solution I would implement
I would like to expose the mass command execution workflow through REST APIs, following the same backend execution flow as the admin interface.
Confirmation endpoint: A confirmation endpoint to resolve and preview affected devices before creating a MassCommand operation.
This endpoint will accept target filters such as organization, device group, location, manual device selection, and all devices.
This acts as a dry-run step before triggering the actual batch operation.
Mass command execution endpoint: An endpoint to create and execute a new MassCommand.
This endpoint will validate the selected target devices, validate the command type, and create the MassCommand operation to create child Command objects that trigger the asynchronous execution pipeline.
Supported command types may include reboot, change password and custom command.
Mass command listing endpoint: An endpoint to retrieve all previously executed MassCommand operations.
This endpoint will return the list of mass command operations with their execution metadata, aggregated status, targeted devices count, and timestamps, allowing administrators or API consumers to view the history of batch command executions.
Mass command detail endpoint: An endpoint to retrieve a specific MassCommand operation and its execution details.
This endpoint will return detailed information about the selected mass command operation, including operation metadata, targeted devices, per-device execution status, command outputs, and overall execution progress.
Mass command deletion endpoint: An endpoint to delete an existing MassCommand operation.
This endpoint will allow authorized users to delete a previously created mass command operation record while preserving proper permission checks and validation.
Details to preserve during implementation
The exact request and response schemas should be defined before implementation or during the first API work. This includes confirmation, creation, list, detail, and delete responses.
Pagination requirements should be explicit. The API should investigate pagination for the MassCommand list and for per-device execution results in MassCommand detail responses.
Per-device execution results should be exposed clearly. The final schema can decide whether results are embedded in the MassCommand detail response, exposed through a nested endpoint, linked to existing Command resources, or handled with another pattern that fits the existing API design.
Lifecycle and status semantics should be aligned with the backend work in #1344. The API should expose enough information to distinguish in-progress, success, failed, partial success, and other final or transitional states chosen during implementation.
Error behavior and validation rules should be defined. Cases to cover include invalid target combinations, unauthorized devices, unsupported command types, empty target sets, invalid manual device IDs, and devices without usable connections.
Permission behavior should be explicit for
all devices, organization-scoped users, cross-organization operations, manual device selection, location filters, and device group filters.Integration with the existing
CommandAPI should be clarified. The implementation can decide whether the existing individual Command API exposes themass_commandrelation directly, links to the parent operation, or keeps this relation only in MassCommand-specific responses.Deletion behavior should remain open until lifecycle and traceability requirements are clear. Possible approaches include allowing deletion while preserving child Command rows, blocking deletion while execution is in progress, protecting records that still have child commands, soft-deleting records, or another approach that preserves the expected command history behavior.
Naming should be kept consistent before implementation. The proposal and issues use terms such as
MassCommand,Batch Command,BatchCommand, and/batch-command/. Possible API path options include keeping/batch-command/, switching to/mass-command/, or choosing another convention that matches the rest of the project.Automated tests should cover request/response schemas, pagination, per-device results, validation errors, permissions, lifecycle constraints, deletion behavior, and integration with the existing Command API.