From bf23533b35d496e6cfe42e9e12b26159a6615e82 Mon Sep 17 00:00:00 2001 From: Rachael Shaw Date: Mon, 8 Sep 2025 17:47:56 -0500 Subject: [PATCH] #28390 API design (schedule script) (#30443) For https://github.com/fleetdm/fleet/issues/28390 --------- Co-authored-by: jacobshandling <61553566+jacobshandling@users.noreply.github.com> --- docs/REST API/rest-api.md | 156 ++++++++++++++++++++++++++++++++++---- 1 file changed, 143 insertions(+), 13 deletions(-) diff --git a/docs/REST API/rest-api.md b/docs/REST API/rest-api.md index a47f82dddb..17e027294a 100644 --- a/docs/REST API/rest-api.md +++ b/docs/REST API/rest-api.md @@ -8863,7 +8863,10 @@ This allows you to easily configure scheduled queries that will impact a whole t - [Run script](#run-script) - [Get script result](#get-script-result) - [Batch-run script](#batch-run-script) -- [Get batch script summary](#get-batch-script-summary) +- [List batch scripts](#list-batch-scripts) +- [Get batch script](#get-batch-script) +- [List hosts targeted in batch script](#list-hosts-targeted-in-batch-script) +- [Cancel batch script](#cancel-batch-script) - [Add script](#add-script) - [Modify script](#modify-script) - [Delete script](#delete-script) @@ -8964,6 +8967,7 @@ The script will be added to each host's list of upcoming activities. | script_id | integer | body | **Required**. The ID of the existing saved script to run. | | host_ids | array | body | List of host IDs. Required if `filters` not specified. Only one of `host_ids` or `filters` may be included in the request. | | | filters | object | body | See [filters](#filters3). Required if `host_ids` not specified. Only one of `host_ids` or `filters` may be included in the request. | +| not_before | string | body | UTC time when the script run is scheduled to begin. If omitted, the batch script will begin right away. | ##### Filters @@ -8975,6 +8979,8 @@ The script will be added to each host's list of upcoming activities. | label_id | number | ID of a label to filter by. | | team_id | number | ID of the team to filter by. | +> Note that if a batch script is scheduled for the future using `not_before`, and hosts are targeted using `filters`, the script will run on any hosts matching the filters _at the time the batch script was added_. To see all targeted hosts, use the [List hosts targeted in batch script](#list-hosts-targeted-in-batch-script) endpoint. + #### Example @@ -8987,7 +8993,8 @@ Request (using `host_ids`): ```json { "script_id": 123, - "host_ids": [1, 2, 3] + "host_ids": [1, 2, 3], + "not_before": "2025-07-01T15:00:00Z" } ``` @@ -9013,22 +9020,89 @@ Request (using `filters`): } ``` -### Get batch script summary +### List batch scripts -Get statuses and host counts for a batch-run script. +Returns a list of batch script executions. -`GET /api/v1/fleet/scripts/batch/summary/:batch_execution_id` +`GET /api/v1/fleet/scripts/batch` #### Parameters | Name | Type | In | Description | | ---- | ------- | ---- | -------------------------------------------- | -| batch_execution_id | string | path | **Required**. The ID returned from a batch script run. | +| team_id | integer | query | _Available in Fleet Premium_. Filters to batch script runs for the specified team. | +| status | string | query | Filters to batch script runs with this status. Either `"started"`, `"scheduled"`, or `"finished"`. | +| page | integer | query | Page number of the results to fetch. | +| per_page | integer | query | Results per page. | #### Example -`GET /api/v1/fleet/scripts/batch/summary/abc-def` +`GET /api/v1/fleet/scripts/batch` + +##### Request body + +```json +{ + "team_id": 123, + "status": "completed" +} +``` + +##### Default response + +`Status: 200` + +```json +{ + "batch_executions": [ + { + "script_id": 555, + "script_name": "my-script.sh", + "batch_execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002", + "team_id": 123, + "not_before": "2025-07-01T15:00:00Z", + "finished_at": "2025-07-06T15:00:00Z", + "started_at": "2025-07-06T14:00:00Z", + "status": "finished", + "canceled": false, + "targeted_host_count": 12599, + "ran_host_count": 12345, + "pending_host_count": 234, + "errored_host_count": 18, + "incompatible_host_count": 3, + "canceled_host_count": 2, + "created_at": "2025-07-01T10:00:00Z" + } + ], + "meta": { + "has_next_results": false, + "has_previous_results": false, + }, + "count": 1 +} +``` + +### Get batch script + +Returns a summary of a batch-run script, including host counts and current status. + +> The [Get batch script summary](https://github.com/fleetdm/fleet/blob/fleet-v4.71.1/docs/REST%20API/rest-api.md#get-batch-script-summary) endpoint is deprecated as of Fleet 4.73. It is maintained for backwards compatibility. Please use this endpoint instead. + +`GET /api/v1/fleet/scripts/batch/:batch_execution_id` + +#### Parameters + +| Name | Type | In | Description | +| ------------------ | ------- | ---- | --------------------------------------------| +| batch_execution_id | string | path | **Required**. The ID returned from a batch script run. | + + +#### Example + +`GET /api/v1/fleet/scripts/batch/abc-def` + + ##### Default response @@ -9037,17 +9111,73 @@ Get statuses and host counts for a batch-run script. ```json { - "ran": 12345, - "pending": 234, - "errored": 18, - "canceled": 2, - "targeted": 12599, "script_id": 555, "script_name": "my-script.sh", - "team_id": 123 + "team_id": 123, + "not_before": "2025-07-01T15:00:00Z", + "finished_at": "2025-07-06T15:00:00Z", + "started_at": "2025-07-06T14:00:00Z", + "status": "finished", + "canceled": false, + "targeted_host_count": 12599, + "ran_host_count": 12345, + "pending_host_count": 234, + "errored_host_count": 18, + "incompatible_host_count": 3, + "canceled_host_count": 2, + "created_at": "2025-07-01T10:00:00Z" } ``` +### List hosts targeted in batch script + +Returns a list hosts targeted in a batch script run, along with their script execution status. + +`GET /api/v1/fleet/scripts/batch/:batch_execution_id/host-results` + +#### Parameters + +| Name | Type | In | Description | +| --------------------| ------- | ----- | -------------------------------------------- | +| batch_execution_id | string | path | **Required**. The ID returned from a batch script run. | +| status | string | query | Filters to hosts with this script status. Either `"ran"`, `"pending"`, `"errored"`, `"incompatible"`, or "`canceled`". | +| page | integer | query | Page number of the results to fetch. | +| per_page | integer | query | Results per page. | + +#### Example + +`GET /api/v1/fleet/scripts/batch/abc-def/host-results?status=ran` + + +##### Default response + +`Status: 200` + + +```json +{ + "hosts": [ + { + "id": 123, + "display_name": "Anna's MacBook Pro", + "script_status": "ran", + "script_execution_id": "e797d6c6-3aae-11ee-be56-0242ac120002", + "script_executed_at": "2024-09-11T20:30:24Z", + "script_output_preview": "hello world" + } + ], + "meta": { + "has_next_results": false, + "has_previous_results": false + }, + "count": 1 +} +``` + +### Cancel batch script + +`POST /scripts/batch/abc-def/cancel` + ### Add script Uploads a script, making it available to run on hosts assigned to the specified team (or no team).