Create a Task Run

POST

https://nico-rest-api.nico.svc.cluster.local/v2/org/:org/nico/task/run

POST

/v2/org/:org/nico/task/run

$ curl -X POST https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/task/run \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "siteId": "site-1234",
>   "name": "Firmware Update Batch 42",
>   "options": {
>     "maxConcurrentTargets": 5
>   },
>   "operation": {
>     "firmware": {
>       "version": "v2.3.1"
>     }
>   }
> }'

1 {
2   "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
3   "name": "Firmware Update Batch 42",
4   "operationType": "Firmware",
5   "status": "Pending",
6   "statusReason": "Awaiting start",
7   "totalPhases": 3,
8   "created": "2024-01-15T09:30:00Z",
9   "updated": "2024-01-15T09:30:00Z",
10   "description": "Rolling firmware update to version v2.3.1 across selected racks",
11   "operationCode": "FW_UPD_202406",
12   "statusMessage": "Task run created and pending execution",
13   "started": "2024-01-15T09:30:00Z",
14   "finished": "2024-01-15T09:30:00Z",
15   "stats": {
16     "currentPhase": {
17       "phaseIndex": 1,
18       "selectedTargets": 10,
19       "outcomeCounts": {
20         "completed": 0,
21         "failed": 0,
22         "terminated": 0,
23         "skipped": 0
24       }
25     },
26     "cumulativePhase": {
27       "phaseIndex": 1,
28       "selectedTargets": 10,
29       "outcomeCounts": {
30         "completed": 0,
31         "failed": 0,
32         "terminated": 0,
33         "skipped": 0
34       }
35     }
36   }
37 }

Create a Task Run: a phased, policy-gated execution of one operation across many Racks. The configuration is validated server-side by Flow; on validation failure no state changes.

A Task Run executes exactly one operation (currently firmware) over a candidate set of Racks, narrowed by an optional selector and divided into phases by an optional options.phasePolicy. The response echoes the assigned id; the Task Run always starts in the Pending state. Poll GET /task/run/{id} for progress.

Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

Create a Task Run: a phased, policy-gated execution of one operation across many Racks. The configuration is validated server-side by Flow; on validation failure no state changes. A Task Run executes exactly one operation (currently firmware) over a candidate set of Racks, narrowed by an optional `selector` and divided into phases by an optional `options.phasePolicy`. The response echoes the assigned `id`; the Task Run always starts in the `Pending` state. Poll `GET /task/run/{id}` for progress. Org must have an Infrastructure Provider entity. User must have authorization role with `PROVIDER_ADMIN` suffix.

Authentication

AuthorizationBearer

export JWT_BEARER_TOKEN="<jwt-bearer-token>"
# Example org name: "acme-inc
export ORG_NAME=<org-name>
# Use the JWT bearer token in your API request auth header:
curl -v -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $JWT_BEARER_TOKEN" https://nico-rest-api.nico.svc.cluster.local/v2/org/$ORG_NAME/nico/user/current

``` export JWT_BEARER_TOKEN="<jwt-bearer-token>" # Example org name: "acme-inc export ORG_NAME=<org-name> # Use the JWT bearer token in your API request auth header: curl -v -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $JWT_BEARER_TOKEN" https://nico-rest-api.nico.svc.cluster.local/v2/org/$ORG_NAME/nico/user/current ```

Path parameters

orgstringRequired

Name of the Org

Request

This endpoint expects an object.

siteIdstringRequiredformat: "uuid"

ID of the Site to create the Task Run on.

namestringRequired

Human-readable name of the Task Run.

optionsobjectRequired

Execution policy for the Task Run.

operationobjectRequired

The operation the Task Run executes. Firmware is the only supported operation today.

descriptionstringOptional

Optional free-form description.

selectorobjectOptional

Narrows the candidate Racks. Omit to target the full candidate scope (100%).

Response

Task Run was created.

idstringformat: "uuid"

Unique identifier of the Task Run.

namestring

Human-readable name of the Task Run.

operationTypeenum

Type of operation this Task Run executes. Currently always FirmwareControl.

statusenum

Current lifecycle state of the Task Run.

statusReasonenum

Why the Task Run is paused or terminal (e.g. PhaseGate, SafetyGate). None when there is no qualifying reason.

totalPhasesinteger

Total number of phases the selected targets were divided into.

createddatetime

Timestamp when the Task Run was created.

updateddatetime

Timestamp when the Task Run was last updated.

descriptionstring

Optional free-form description.

operationCodestring

Operation code within the operation type (e.g. upgrade).

statusMessagestring

Optional human-readable detail for the current status.

starteddatetime or null

Timestamp when the Task Run started execution. Null before it starts.

finisheddatetime or null

Timestamp when the Task Run reached a terminal state. Null while active.

statsobject

Derived per-phase outcome stats. Present only on the single-Task-Run GET when includeStats=true; omitted otherwise.

Errors

400

Bad Request Error

403

Forbidden Error