Skip to content
Picogrid Legion

Dispatch task

Dispatch task

Open in ChatGPT ↗Open in Claude ↗
POST
/v3/tasking
curl --request POST \
  --url https://api.hopper.west.prod.govcloud.legion.picogrid.com/v3/tasking \
  --header 'Content-Type: application/json' \
  --data '{ "command_name": "Restart", "entity_id": "d4e5f6a1-b2c3-7890-1234-567890abcdef", "payload": { "force": true, "reason": "System maintenance", "timeout": 30 }, "qos": 1 }'

Dispatches a task to the specified entity using the specified MQTT topic and payload. The command must have been registered in the system and the payload must match the schema for that command.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
command_name
required
string
Example
Restart
entity_id
required
string format: uuid
Example
d4e5f6a1-b2c3-7890-1234-567890abcdef
payload
object
Example
{
  "force": true,
  "reason": "System maintenance",
  "timeout": 30
}
qos
required
number
<= 2
Example
1

Responses

Section titled “Responses”

200

Section titled “200”

Successful response

Media typeapplication/json
object
command_name
required
string
dispatched_at
required
string
entity_id
required
string format: uuid
task_id
required
string format: uuid
Example
{
  "command_name": "GetStatus",
  "dispatched_at": "2024-01-15T11:00:00Z",
  "entity_id": "f6a1b2c3-d4e5-7890-1234-567890abcdef",
  "task_id": "c3d4e5f6-e7f8-9012-3456-789012cdef01"
}

400

Section titled “400”

Bad Request

Media typeapplication/json
object
category
required
string
code
required
number
details
Array<object>
object
field
required
string
issue
required
string
message
required
string
status
required
string
timestamp
required
string
trace_id
required
string
Example
{
  "code": 400,
  "details": [
    {
      "Field": "organization_id",
      "Issue": "must be a valid UUID format"
    }
  ],
  "message": "Request cannot be processed due to invalid input",
  "status": "error",
  "timestamp": "2026-01-15T14:32:45Z",
  "trace_id": "req_2J9K8L7M6N5P4Q3R"
}

401

Section titled “401”

Unauthorized

Media typeapplication/json
object
category
required
string
code
required
number
details
Array<object>
object
field
required
string
issue
required
string
message
required
string
status
required
string
timestamp
required
string
trace_id
required
string
Example
{
  "code": 401,
  "details": [
    {
      "Field": "authorization_header",
      "Issue": "Bearer token is expired or malformed"
    }
  ],
  "message": "Authentication credentials are missing or invalid",
  "status": "error",
  "timestamp": "2026-01-15T14:32:45Z",
  "trace_id": "req_2J9K8L7M6N5P4Q3R"
}

403

Section titled “403”

Forbidden

Media typeapplication/json
object
category
required
string
code
required
number
details
Array<object>
object
field
required
string
issue
required
string
message
required
string
status
required
string
timestamp
required
string
trace_id
required
string
Example
{
  "code": 403,
  "details": [
    {
      "Field": "required_scope",
      "Issue": "requires 'orion:settings:write' scope, but token only has 'orion:settings:read'"
    }
  ],
  "message": "Access denied: insufficient permissions for this resource",
  "status": "error",
  "timestamp": "2026-01-15T14:32:45Z",
  "trace_id": "req_2J9K8L7M6N5P4Q3R"
}

404

Section titled “404”

Not Found

Media typeapplication/json
object
category
required
string
code
required
number
details
Array<object>
object
field
required
string
issue
required
string
message
required
string
status
required
string
timestamp
required
string
trace_id
required
string
Example
{
  "code": 404,
  "details": [
    {
      "Field": "organization_id",
      "Issue": "organization with ID 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' not found"
    }
  ],
  "message": "The requested resource could not be found",
  "status": "error",
  "timestamp": "2026-01-15T14:32:45Z",
  "trace_id": "req_2J9K8L7M6N5P4Q3R"
}

500

Section titled “500”

Internal Server Error

Media typeapplication/json
object
category
required

The category of the error

string
code
required

The HTTP status code

number
details

Additional details about the error

Array<object>
object
field

The field that caused the error

string
issue

The specific issue with the field

string
message
required

A human-readable error message

string
status
required

The status of the response, always ‘error’ for error responses

string
timestamp
required

The timestamp when the error occurred

string format: date-time
trace_id
required

A unique identifier for tracing the error

string format: uuid
Example
{
  "category": "server_error",
  "code": 500,
  "details": [
    {
      "field": "field_name",
      "issue": "Field validation issue"
    }
  ],
  "message": "Internal Server Error",
  "status": "error",
  "timestamp": "2024-03-15T10:30:00Z",
  "trace_id": "b7c5e4d3-a2b1-4f0e-8d9c-1a2b3c4d5e6f"
}

Version 3.14.0 · commit 0771262